An overview of macOS kernel debugging

What is a kernel debugger?

Debugging is the process of searching and correcting software issues that may cause a program to misbehave. Faults include wrong results, program freezes or crashes, and sometimes even security vulnerabilities. To examine running applications, operating systems provide userland debuggers mechanisms like ptrace or exception ports [1]; but when working at kernel/driver/OS level, more powerful capabilities are required.

Modern operating systems like macOS or iOS consist of millions of lines of code, through which the kernel orchestrates the execution of hundreds of threads manipulating thousands of critical data structures. This complexity facilitates the introduction of likewise complex programming errors, which at minimum can cause the machine to stop or reboot. Even when kernel sources are available, tracing the root causes of such bugs is often very difficult, especially without knowing exactly which code has been executed or the state of registers and memory; similarly, the analysis of kernel rootkits and exploits of security vulnerabilities requires an accurate study of the behaviour of the machine.

For these reasons, operating systems often implement a kernel debugger, usually composed of a simple agent running inside the kernel, which receives and executes debugging commands, and a complete debugger running on a remote machine, which sends commands to the kernel and displays the results. The debugging stub internal to the kernel generally has the tasks of:

• reading and writing registers;

• reading and writing memory;

• single-stepping through the code;

• catching CPU interrupts.

With these capabilities, it also becomes possible to:

• pause the kernel execution at specific virtual addresses, by patching the code with INT3 instructions and then waiting for type-3 interrupts to occur;

• introspect kernel structures by parsing the kernel header and reading memory.

The next sections describe in detail how kernel debugging is implemented by XNU.

Debugging the macOS kernel

As described in the README of [XNU49032212], XNU supports remote (two-machine) debugging by implementing the Kernel Debugging Protocol (KDP, described later in the article). Apple's documentation about the topic [DarwinDoc1] is outdated and no longer being updated, but luckily detailed guides on how to set up recent macOS kernels for remote debugging are available on the Internet [2] [3] [4] [5]; summarising, it is required to switch to one of the debug builds of the kernel (released as part of the Kernel Debug Kit, or KDK, also discussed later), rebuild the kernel extension (kext) caches and set the debug boot-arg in the NVRAM to the appropriate values (see XNU code kern/debug.h#L419). After this, LLDB (or any other debugger supporting KDP) can attach to the kernel. Conveniently, it is also possible to debug a virtual machine instead of a second Mac [6] [7] [8].

Mentioned for completeness, at least two other methods for kernel debugging have been supported at some point for several XNU releases. The archived Apple's docs suggest to use ddb over a serial line when debugging via KDP is not possible or problematic (e.g. before the network hardware is initialised) [DarwinDoc2], but support for this feature seems to have been dropped after XNU 1699.26.8 as all related files (i.e. the directory osfmk/ddb/ from [XNU1699268]) were removed in the next release. Other documents, like the README of the kernel debug kit for macOS 10.7.3 build 11D50, allude to the possibility of using /dev/kmem for limited self-debugging:

‘Live (single-machine) kernel debugging was introduced in Mac OS X Leopard. This allows limited introspection of the kernel on a currently-running system. This works using the normal kernel and the symbols in this Kernel Debug Kit by specifying kmem=1 in your boot-args; the DEBUG kernel is not required.’

This method still works in recent macOS builds provided that System Integrity Protection (SIP) is disabled (bsd/dev/mem.c:L225, pexpert/i386/pe_init.c#L354), but newer KDKs do not mention it anymore, and a note from the archived Apple's docs says that support for /dev/kmem will be removed entirely in the future [DarwinDoc3].

Limitations of the available tools

The combination of KDP and LLDB, alongside with the notable introspection possibilities offered by lldbmacros, make for a great kernel debugger; still, at present time this approach also has a few annoyances and drawbacks, here summarised.

First, as already noted, the KDP stub in the kernel is activated only after setting the debug boot-arg in the non-volatile RAM, but such operation requires to disable SIP. Secondly, the whole debugging procedure has many side effects: the modification of global variables (like kdp_flag); the value of the kernel base address written at a fixed memory location (DynamicLoaderDarwinKernel.cpp#L226 from [LLDB800]); the altering of kernel code with 0xCC software breakpoints (osfmk/kdp/ml/x86_64/kdp_machdep.c#L471, osfmk/kdp/kdp.c#L937)—watchpoints are not even supported (ProcessKDP.cpp#L699 from [LLDB800]). All these (and others) can be easily detected by drivers, rootkits and exploits by reading NVRAM or global variables or with code checksums. Thirdly, the remote debugger cannot stop the execution of the kernel once it has been resumed: the only way to return to the debugger is to wait for breakpoints to occur (or to generate traps by, for example, injecting an NMI with dtrace from inside the debuggee). Fourthly, debugging can obviously start only after the initialisation of the KDP agent in the kernel, which happens relatively late in the startup phase and makes early debugging impossible. Finally, being part of the Kernel Debug Kits, lldbmacros are unfortunately only available for a few macOS releases.

Wrapping up

With this post, we tried to document accurately how macOS kernel debugging works, in the hope of creating an up-to-date reference on the topic. In the next post, we will present our solution for a better macOS debugging experience, also intended to overcome the limitations of the current approach.

References and footnotes