kdk-storage 0.0.1

A library for working with a directory with KDK's

kdk_storage

A small Python library for working with a directory of Apple Kernel Debug Kits (KDKs).

It scans a folder full of installed KDKs, sorts them by version (handling beta ordering), and gives you a simple API to locate the kernel and driver (kext) binaries inside any given KDK.

What is a KDK?

A Kernel Debug Kit is a package Apple ships for each macOS build that contains the (usually unstripped) kernel and kext binaries used for kernel debugging and research. When installed, each KDK lives in its own directory named like:

KDK_15.5_24F74.kdk

kdk_storage treats a parent folder holding many such directories as a single addressable storage.

Installation

Requires Python >= 3.9. The project is built with Hatchling.

pip install .

or, for development:

pip install -e .

Usage

from pathlib import Path
from kdk_storage import KDKStorage

# Point at the directory that contains your KDK_* folders.
storage = KDKStorage(Path("/Library/Developer/KDKs"))

# List available versions (optionally skipping betas).
print(storage.get_versions_list(skip_betas=False))
# ['15.4_24E248', '15.5_24F74', ...]

# Human-readable listing that marks betas.
for line in storage.get_versions_list_to_print(skip_betas=False):
    print(line)
# 15.5_24F74
# 15.6_24G5054d (beta)

# Resolve a kernel binary for a version.
kernel = storage.kernel("15.5_24F74", "kernel")
print(kernel.binary)        # full path to the kernel Mach-O
print(kernel.is_macho_fat())  # True if it's a fat/universal binary

Partial version matching

KDKStorage.kernel() accepts a partial version string. If the argument isn't an exact match but is a substring of exactly one available version, that version is used:

storage.kernel("24F74", "kernel")   # matches 15.5_24F74

If the substring is ambiguous (matches more than one version) or matches none, kernel() returns None.

Working with drivers

Given a specific KDK, you can also resolve a driver (kext) binary:

kdk = storage.hashmap_versions["15.5_24F74"]
driver = kdk.driver("AppleACPIPlatform")
print(driver.binary)  # path to the kext's Mach-O under Contents/MacOS

API overview

Class	Purpose
KDKStorage	Scans a directory of KDKs, sorts them by version, and resolves kernels/drivers.
KDK	A single Kernel Debug Kit directory; knows its version and whether it's a beta.
KDKElement	Base class for a binary inside a KDK. Provides is_macho_fat().
Kernel	A kernel binary under System/Library/Kernels.
Driver	A kext binary under System/Library/Extensions/<name>.kext/Contents/MacOS.

Version ordering

KDKs are sorted by their numeric version components, with two tie-breaking rules:

• A beta build (detected when the last character of the version string is a lowercase letter, e.g. 24G5054d) sorts before the corresponding release build.
• Otherwise the build identifier (the part after _) is compared lexicographically.

License

MIT © Valentin Shilnenkov