{"id":20716839,"url":"https://github.com/blacktop/darwin-xnu-build","last_synced_at":"2025-04-13T00:47:13.065Z","repository":{"id":123131950,"uuid":"609392560","full_name":"blacktop/darwin-xnu-build","owner":"blacktop","description":"XNU kernel, Kernel Collection and CodeQL build scripts","archived":false,"fork":false,"pushed_at":"2025-04-07T16:03:13.000Z","size":15531,"stargazers_count":227,"open_issues_count":13,"forks_count":34,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-13T00:47:05.979Z","etag":null,"topics":["apple","codeql","darwin","kernel","kernelcache","xnu"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blacktop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-04T03:19:53.000Z","updated_at":"2025-04-10T14:11:31.000Z","dependencies_parsed_at":"2024-02-14T21:25:15.751Z","dependency_job_id":"9f9a1acb-f0f5-4173-9a44-4ea5ee15b887","html_url":"https://github.com/blacktop/darwin-xnu-build","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacktop%2Fdarwin-xnu-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacktop%2Fdarwin-xnu-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacktop%2Fdarwin-xnu-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacktop%2Fdarwin-xnu-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blacktop","download_url":"https://codeload.github.com/blacktop/darwin-xnu-build/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650433,"owners_count":21139672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","codeql","darwin","kernel","kernelcache","xnu"],"created_at":"2024-11-17T03:06:58.477Z","updated_at":"2025-04-13T00:47:13.045Z","avatar_url":"https://github.com/blacktop.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# darwin-xnu-build\n\n[![XNU CodeQL](https://github.com/blacktop/darwin-xnu-build/actions/workflows/c-cpp.yml/badge.svg)](https://github.com/blacktop/darwin-xnu-build/actions/workflows/c-cpp.yml) ![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/blacktop/darwin-xnu-build/total)\n [![LICENSE](https://img.shields.io/:license-mit-blue.svg)](https://doge.mit-license.org)\n\n\n\n\n\u003e This repository contains scripts to build [xnu](https://github.com/apple-oss-distributions/xnu) as well as generate a kernel collection and [CodeQL](https://codeql.github.com) databases.\n\n---\n\n## Supported OS Versions\n\n| Version    | Compiles |                                          CodeQL                                           | Boots *(arm64/x86_64)* |\n| ---------- | :------: | :---------------------------------------------------------------------------------------: | :--------------------: |\n| macOS 12.5 |    ✅     |                                             ❔                                            |    ❔       /     ✅     |\n| macOS 13.0 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v13.0/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 13.1 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v13.1/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 13.2 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v13.2/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 13.3 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v13.3/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 13.4 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v13.4/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 13.5 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v13.5/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 14.0 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v14.0/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 14.1 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v14.1/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 14.2 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v14.2/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 14.3 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v14.3/xnu-codeql.zip) |    ✅       /     ✅     |\n| macOS 14.4 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v14.4/xnu-codeql.zip) |    ✅       /     ✅     |\n| macOS 14.5 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v14.5/xnu-codeql.zip) |    ✅       /     ✅     |\n| macOS 14.6 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v14.6/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 15.0 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v15.0/xnu-codeql.zip) |    ✅       /     ✅     |\n| macOS 15.1 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v15.1/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 15.2 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v15.2/xnu-codeql.zip) |    ❔       /     ❔     |\n| macOS 15.3 |    ✅     | [DB](https://github.com/blacktop/darwin-xnu-build/releases/download/v15.3/xnu-codeql.zip) |    ❔       /     ❔     |\n\n\u003e [!NOTE]\n\u003e CodeQL DBs built with `MACHINE_CONFIG=VMAPPLE`  \n\u003e MacOS `14.3` booted:\n\u003e - via Virtualization.framework with `MACHINE_CONFIG=VMAPPLE`\n\u003e - via qemu with `ARCH_CONFIG=x86_64`\n\u003e - via ASi tested with `MACHINE_CONFIG=T8101` and `MACHINE_CONFIG=T6000`\n\n### Known Issue ⚠️\n\nCurrently `MACHINE_CONFIG=T8103` is not correctly building for at least `14.3`\n\n\u003e [!NOTE]\n\u003e When attempting to boot try adding the boot-arg: `sudo nvram boot-args=\"-unsafe_kernel_text\"`\n\n\u003e [!WARNING]  \n\u003e Booting VMAPPLE kernels in VMs only works on Apple M1s [see issue](https://github.com/blacktop/darwin-xnu-build/issues/22)\n\n## Why? 🤔\n\nI'm hoping to patch and build the xnu source in interesting ways to aid in research and development of macOS/iOS security research tools as well as generate [CodeQL](https://securitylab.github.com/tools/codeql) databases for the community to use.\n\n## Getting Started\n\n### Dependencies\n\n- [homebrew](https://brew.sh)\n  - [jq](https://stedolan.github.io/jq/)\n  - [gum](https://github.com/charmbracelet/gum)\n  - [xcodes](https://github.com/RobotsAndPencils/xcodes)\n  - [ipsw](https://github.com/blacktop/ipsw)\n  - [cmake](https://cmake.org)\n  - [ninja](https://ninja-build.org)\n- XCode\n- python3\n- [codeql CLI](https://codeql.github.com/docs/codeql-cli/)\n\n\u003e [!NOTE]\n\u003e The `build.sh` script will install all these for you if you are connected to the internet.\n\n### Clone the repo\n\n```bash\ngit clone https://github.com/blacktop/darwin-xnu-build.git\ncd darwin-xnu-build\n```\n\n```bash\n❯ ./build.sh --help\n\nUsage: build.sh [-h] [--clean] [--kc]\n\nThis script builds the macOS XNU kernel\n\nWhere:\n    -h|--help       show this help text\n    -c|--clean      cleans build artifacts and cloned repos\n    -k|--kc         create kernel collection (via kmutil create)\n```\n\n### Build the kernel and kernel Collection\n\n```bash\nKERNEL_CONFIG=RELEASE ARCH_CONFIG=ARM64 MACHINE_CONFIG=VMAPPLE ./build.sh --kc\n```\n\n\u003e [!NOTE]\n\u003e Supported `KERNEL_CONFIG` include:\n\u003e - `RELEASE`\n\u003e - `DEVELOPMENT`\n\u003e\n\u003e Supported `MACHINE_CONFIG` include:\n\u003e - `T8101`\n\u003e - `T8103`\n\u003e - `T6000`\n\u003e - `VMAPPLE`\n\n```bash\n\u003cSNIP\u003e\n ⇒ 📦 Building kernel collection for 'kernel.release.t6000'\n   • Decompressing KernelManagement kernelcache\nMerged LINKEDIT:\n  weak bindings size:          0KB\n  exports info size:           0KB\n  bindings size:               0KB\n  lazy bindings size:          0KB\n  function starts size:       41KB\n  data in code size:           0KB\n  symbol table size:        3702KB (85348 exports, 87979 imports)\n  symbol string pool size:  6465KB\nLINKEDITS optimized from 30MB to 10MB\ntime to layout cache: 0ms\ntime to copy cached dylibs into buffer: 1ms\ntime to adjust segments for new split locations: 2ms\ntime to bind all images: 8ms\ntime to optimize Objective-C: 0ms\ntime to do stub elimination: 0ms\ntime to optimize LINKEDITs: 2ms\ntime to compute slide info: 1ms\ntime to compute UUID and codesign cache file: 1ms\n  🎉 XNU Build Done!\n```\n\nCheck that the output contains all the KEXTs\n\n```bash\n❯ ipsw macho info build/oss-xnu.kc | head\nMagic         = 64-bit MachO\nType          = FILESET\nCPU           = AARCH64, ARM64e\nCommands      = 241 (Size: 17160)\nFlags         = None\n000: LC_UUID                     67DF7148-8EEC-B1A6-5F51-7502DADF2264\n001: LC_BUILD_VERSION            Platform: unknown, SDK: 0.0\n002: LC_UNIXTHREAD               Threads: 1, ARM64 EntryPoint: 0xfffffe0007ad1488\n003: LC_DYLD_CHAINED_FIXUPS      offset=0x003690000  size=0x444\n004: LC_SEGMENT_64 sz=0x00008000 off=0x00000000-0x00008000 addr=0xfffffe0007004000-0xfffffe000700c000 r--/r--   __TEXT\n\u003cSNIP\u003e\n```\n\n### Clean rebuild the kernel and kernel collection\n\n```bash\nMACOS_VERSION='15.0' KERNEL_CONFIG=RELEASE ARCH_CONFIG=ARM64 MACHINE_CONFIG=VMAPPLE ./build.sh --clean --kc\n```\n\n### Generate a CodeQL database\n\n```bash\nMACOS_VERSION='15.0' KERNEL_CONFIG=RELEASE ARCH_CONFIG=ARM64 MACHINE_CONFIG=VMAPPLE ./codeql.sh\n```\n```bash\n\u003cSNIP\u003e\n[2023-03-03 22:33:20] [build-stdout]   🎉 XNU Build Done!\nFinalizing database at darwin-xnu-build/xnu-codeql.\nRunning TRAP import for CodeQL database at darwin-xnu-build/xnu-codeql...\nTRAP import complete (1m46s).\nSuccessfully created database at darwin-xnu-build/xnu-codeql.\n[info] Deleting log files...\n[info] Zipping the CodeQL database...\n  🎉 CodeQL Database Create Done!\n```\n\nScript builds and zips up the CodeQL database\n\n```bash\n❯ ll xnu-codeql.zip\n-rw-r--r--@ 1 blacktop  staff   219M Mar  3 22:35 xnu-codeql.zip\n```\n\n### Generate a CodeQL database *(in a `local` **Tart** VM)*\n\nInstall deps: *[packer](https://developer.hashicorp.com/packer), [tart](https://tart.ru) and [cirrus](https://github.com/cirruslabs/cirrus-cli)*\n\n```bash\nmake deps\n```\n\nBuild VM image\n\n```bash\nmake build-vm\n```\n\nCreate CodeQL DB\n\n```bash\nmake codeql-db\n```\n\n```bash\n \u003e Building CodeQL Database\n🕓 'Build' Task 08:22\n   ✅ pull virtual machine 0.0s\n✅ 'Build' Task 47:59\n 🎉 Done! 🎉\n🕒 'Build' Task 46:28\n✅ 'Build' Task 48:15\n```\n\n```bash\n❯ tree artifacts/\n\nartifacts/\n└── Build\n    └── binary\n        └── xnu-codeql.zip\n\n3 directories, 1 file\n```\n\n## TODO\n\n- [x] ~~Auto build xnu with Github Actions~~\n- [x] ~~Auto generate CodeQL database with Github Actions~~\n\n## NOTES\n\nTo see kernel logs\n\n```bash\nlog show --debug --last boot --predicate 'process == \"kernel\"'\n```\n\n## Credit\n\n- \u003chttps://github.com/pwn0rz/xnu-build\u003e\n- \u003chttps://kernelshaman.blogspot.com/2021/02/building-xnu-for-macos-112-intel-apple.html\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblacktop%2Fdarwin-xnu-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblacktop%2Fdarwin-xnu-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblacktop%2Fdarwin-xnu-build/lists"}