diff options
| -rw-r--r-- | docs/guide/kernelcache.md | 84 | ||||
| -rw-r--r-- | docs/guide/sharedcache.md | 72 | ||||
| -rw-r--r-- | mkdocs.yml | 1 |
3 files changed, 123 insertions, 34 deletions
diff --git a/docs/guide/kernelcache.md b/docs/guide/kernelcache.md new file mode 100644 index 00000000..5fff06f8 --- /dev/null +++ b/docs/guide/kernelcache.md @@ -0,0 +1,84 @@ +# Kernel Cache + +Kernel Cache support in Binary Ninja provides you with tools to selectively load specific images, search for +specific symbols, and follow analysis references between any images loaded from an `kernelcache` in one view. + +Our support for `kernelcache` is largely open source. The supporting code can can be found in our public API repository [here](https://github.com/Vector35/binaryninja-api/tree/dev/view/kernelcache). Instructions for setting up your development environment and building plugins like this yourself can be found in our [Developer Guide](../dev/plugins.html#writing-native-plugins). Contributions are welcome! + +## Support Matrix + +List of supported features for the given `kernelcache` targets: + +| Platform | Arch | Versions | Features | +|----------|--------|----------|-----------------------------| +| macOS | x86_64 | 11 - 15 | Core, Objective-C | +| macOS | arm64 | 11 - 15 | Core, Objective-C | +| iOS | arm64 | 14 - 18 | Core, Objective-C | + +- **Core**: Core functionality, such as loading, navigating, and analyzing `kernelcache` files. +- **Objective-C**: Support for analyzing Objective-C information and symbols within the `kernelcache`. + +**Note:** *In general, this plugin does not support `kernelcache` files that are not in `MH_FILESET` format at this time.* + +## Obtaining a Kernel Cache + +The `kernelcache` is a file that contains all the kernel and all of its extensions used by modern Apple operating systems (like macOS, iOS, and tvOS). These can be obtained directly from Apple, or with the help of a tool such as `blacktop/ipsw`. + +A `kernelcache` should typically be automatically decompressed by Binary Ninja. If automatic decompression fails, Binary Ninja can still load +caches decompressed by other tools as long as they are valid `MH_FILESET` Mach-O files. + +### With `blacktop/ipsw` + +Our recommended way to retrieve a `kernelcache` is using blacktop's wonderful [`ipsw` tool](https://github.com/blacktop/ipsw). + +1. [Install blacktop/ipsw](https://github.com/blacktop/ipsw?tab=readme-ov-file#install) +2. Run `ipsw download ipsw --version [target iOS version] --device [target device model (e.g. iPhone10,3)]` +3. Run `ipsw extract --kernel [filename]` + +### From Local macOS Install + +Getting to the local `kernelcache` on macOS is not the easiest. Try some of the following: + +* `/System/Library/Kernel/`, which should have the `kernel`, but not necessarily the extensions + * `/System/Library/Extensions/` should have each of the individual extensions +* `/System/Library/PrelinkedKernels/`, which should have the full `kernelcache`, but may not exist on earlier versions of macOS +* `/System/Library/Caches/com.apple.kernelcaches/`, which may be empty +* `/System/Library/Caches/com.apple.kext.caches/Startup/kernelcache/`, which may be empty + +## Interacting With a Kernel Cache + +After opening a `kernelcache`, you will be provided a custom binary view. Due to the large size of these files, we do not load all the information into the binary view by default. Instead, we do this selectively. + +### Kernel Cache Triage (KCTriage) + +The main way to interact with kernel cache information is through the Kernel Cache Triage view (KCTriage). This is the first thing you see when +opening a `kernelcache` and is how you add images to the actual binary view. + +=== "Images" + Shows a list of all images within the `kernelcache` and their virtual addresses. + + - Double click on an image to load + - Select image(s) and click button "Load Selected" to load multiple images at once + - Select image(s) and right click if you want more options for loading images + +  + +=== "Symbols" + Shows a list of all exported symbols within the `kernelcache` and their virtual addresses. + + - Double click on a symbol to load the associated image, or use the "Load Image" button + +  + +### Scripting + +Another way to interact with the kernel cache information is through the provided Python API, available in the `binaryninja.kernelcache` module. + +```python +# Load the XNU kernel +from binaryninja import kernelcache +kc = kernelcache.KernelCache(bv) +kc.load_image_with_install_name('com.apple.kernel') +``` + +**Note:** *We do not support single-section loading at this time and can only load entire images.* diff --git a/docs/guide/sharedcache.md b/docs/guide/sharedcache.md index b3037cf3..3a08b359 100644 --- a/docs/guide/sharedcache.md +++ b/docs/guide/sharedcache.md @@ -1,42 +1,44 @@ # Shared Cache -Shared Cache support in Binary Ninja provides you with tools to selectively load specific images, search for -specific symbols, and follow analysis references between any loaded images in one view. +Shared cache support in Binary Ninja provides you with tools to selectively load specific images, search for +specific symbols, and follow analysis references between any images loaded from a `dyld_shared_cache` in one view. + +Our support for `dyld_shared_cache` is largely open source. The supporting code can can be found in our public API repository [here](https://github.com/Vector35/binaryninja-api/tree/dev/view/sharedcache). Instructions for setting up your development environment and building plugins like this yourself can be found in our [Developer Guide](../dev/plugins.html#writing-native-plugins). Contributions are welcome! ## Support Matrix -List of supported features for the given shared cache targets. +List of supported features for the given shared cache targets: | Platform | Arch | Versions | Features | |----------|--------|----------|-----------------------------| -| iOS | arm64 | 11 - 18 | Core, Objective-C, Workflow | | macOS | x86_64 | 11 - 15 | Core, Objective-C, Workflow | | macOS | arm64 | 11 - 15 | Core, Objective-C, Workflow | +| iOS | arm64 | 11 - 18 | Core, Objective-C, Workflow | -- **Core**: Core functionality, such as loading, navigating, and analyzing shared cache files. +- **Core**: Core functionality, such as loading, navigating, and analyzing `dyld_shared_cache` files. - **Objective-C**: Support for analyzing Objective-C information and symbols within the shared cache. - **Workflow**: Shared cache workflow that improves on the base Binary Ninja analysis with shared cache specific analysis. ## Obtaining a Shared Cache -The shared cache is one or more files that contain all the shared libraries used by macOS and iOS. These can be obtained -directly from apple, or with the help of a tool such as `blacktop/ipsw`. +The `dyld_shared_cache` is one or more files that contain all the shared libraries used by modern Apple operating systems (like macOS, iOS, and tvOS). These can be obtained +directly from Apple, or with the help of a tool such as `blacktop/ipsw`. -### With blacktop/ipsw tool +### With `blacktop/ipsw` -The recommended way to retrieve iOS shared caches is using blacktop's wonderful ipsw tool. +Our recommended way to retrieve a `dyld_shared_cache` is using blacktop's wonderful [`ipsw` tool](https://github.com/blacktop/ipsw). 1. [Install blacktop/ipsw](https://github.com/blacktop/ipsw?tab=readme-ov-file#install) 2. Run `ipsw download ipsw --version [target iOS version] --device [target device model (e.g. iPhone10,3)]` 3. Run `ipsw extract --dyld [filename]` -### With Local macOS install +### From Local macOS Install The local shared cache on macOS is located at `/System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/`. ## Opening a Shared Cache -Binary Ninja currently supports shared cache files extracted into a flat directory only, so you will need to extract the IPSW (if there is one) first. +Binary Ninja currently only supports `dyld_shared_cache` files that have been extracted into a flat directory, so you will need to extract the IPSW (if there is one) first. After extraction, we are expecting a file structure similar to the following: - `your_directory` - `dyld_shared_cache_arm64` (**Primary**) @@ -44,15 +46,15 @@ Binary Ninja currently supports shared cache files extracted into a flat directo - `dyld_shared_cache_arm64.02` (Secondary, optional) - `dyld_shared_cache_arm64.symbols` (Symbols, optional) -To access the entire shared cache, open the **Primary** file in Binary Ninja, for the example above this would be `dyld_shared_cache_arm64`. +To access the entire shared cache, open the **Primary** file in Binary Ninja. In the example above this would be `dyld_shared_cache_arm64`. Opening any other file (e.g. `dyld_shared_cache_arm64.01`) will result in a partial shared cache, with only the information present in the file you opened. ### Project Support -Shared caches are supported for Binary Ninja projects, however due to the nature of the project files not having a mappable path, -saving shared cache databases (`.bndb`) in a seperate directory will require you to select the primary shared cache file on -every open of the database. It is advised to keep your shared cache databases next to your shared cache files (in the same folder). +Binary Ninja projects support `dyld_shared_cache` files. However, due to the nature of the project files not having a mappable path, +saving the analysis database (`.bndb`) in a separate directory will require you to select the primary shared cache file on +every open of the database. As a result, we advise keeping your analysis database in the same folder as your `dyld_shared_cache` files. - `your_project_folder` - `dyld_shared_cache_arm64` (**Primary**) @@ -61,19 +63,19 @@ every open of the database. It is advised to keep your shared cache databases ne - `dyld_shared_cache_arm64.symbols` (Symbols, optional) - `your_database.bndb` (This is recommended) -## Interacting with a Shared Cache +## Interacting With a Shared Cache -After opening a shared cache you will be provided a supercharged binary view, one which has information not only from -the opened primary file, but all the associated files (ex. `dyld_shared_cache_arm64.02`). Because of the large size of these -caches we cannot load all the information into the binary view, instead we do so selectively. +After opening a `dyld_shared_cache`, you will be provided a supercharged binary view: one which has information not only from +the opened primary file, but all the associated files (ex. `dyld_shared_cache_arm64.02`). Due to the large size of these +files, we cannot load all the information into the binary view. Instead, we do this selectively. ### Shared Cache Triage (DSCTriage) -The main way to interact with the shared cache information is through the triage view. This is the first thing you see when -opening a shared cache and is how you add images to the actual binary view. +The main way to interact with shared cache information is through the Shared Cache Triage view (DSCTriage). This is the first thing you see when +opening a `dyld_shared_cache` and is how you add images to the actual binary view. === "Images" - Shows a list of all images within the shared cache and their virtual addresses. + Shows a list of all images within the `dyld_shared_cache` and their virtual addresses. - Double click on an image to load - Select image(s) and click button "Load Selected" to load multiple images at once @@ -82,7 +84,7 @@ opening a shared cache and is how you add images to the actual binary view.  === "Symbols" - Shows a list of all exported symbols within the shared cache and their virtual addresses. + Shows a list of all exported symbols within the `dyld_shared_cache` and their virtual addresses. - Double click on a symbol to load the associated image, or use the "Load Image" button @@ -95,9 +97,9 @@ opening a shared cache and is how you add images to the actual binary view. ### Scripting -Another way to interact with the shared cache information is through the provided python API, available in the `binaryninja.sharedcache` module. +Another way to interact with the shared cache information is through the provided Python API, available in the `binaryninja.sharedcache` module. -Additionally, the `dsc` magic variable is available in the scripting console whenever a Shared Cache is opened. +Additionally, the `dsc` (or `shared_cache`) magic variable is available in the scripting console whenever a shared cache is opened. ```python # Load all dependency images for the current loaded images @@ -111,25 +113,27 @@ for image in dsc.loaded_images: dsc.apply_image(bv, dep_image) ``` +**Note:** If you are processing `dyld_shared_cache` files headlessly, [`loader.dsc.autoLoadPattern`](settings.md) is a *very* useful setting to override. This is a regex you can have match all the files you *want* to analyze, skipping the need to use the Python or C++ API to load them manually. + ## Glossary ### CacheEntry -A **CacheEntry** is a single file in the shared cache. It contains images, symbols, and regions that collectively -represent a portion of the shared cache's contents. +A **CacheEntry** is a single file in the `dyld_shared_cache`. It contains images, symbols, and regions that collectively +represent a portion of its contents. ### CacheRegion -A **CacheRegion** is the logical segment of the shared cache for which the memory is mapped into the `BinaryView`. It -represents distinct sections of the cache, no region should be overlapping. +A **CacheRegion** is the logical segment of the `dyld_shared_cache` for which the memory is mapped into the `BinaryView`. It +represents distinct sections of the cache, so no region should be overlapping. ### CacheImage -A **CacheImage** is a single shared library within the shared cache. It consists of sections (located within cache -regions) that include both code and data. This is analogous to a single mach-o file. +A **CacheImage** is a single shared library within the `dyld_shared_cache`. It consists of sections (located within cache +regions) that include both code and data. This is analogous to a single Mach-O file. ### CacheSymbol -A **CacheSymbol** represents a symbol within the shared cache, such as a function or data variable. It is **not** a view -symbol and is **not** directly available from the `BinaryView`. Instead, it is specifically associated with the shared -cache data, otherwise we would be putting millions of symbols into the view and slowing down the core unnecessarily. +A **CacheSymbol** represents a symbol within the `dyld_shared_cache`, such as a function or data variable. It is *not* a view +symbol and is *not* directly available from the `BinaryView`. Instead, it is associated with the shared +cache data. Otherwise, we would be putting millions of symbols into the view and slowing down the core unnecessarily. @@ -95,6 +95,7 @@ nav: - Objective-C: 'guide/objectivec.md' - Firmware Ninja: 'guide/firmwareninja.md' - Shared Cache: 'guide/sharedcache.md' + - Kernel Cache: 'guide/kernelcache.md' - Debugger: - Overview: 'guide/debugger/index.md' - Remote Debugging: 'guide/debugger/remote-debugging.md' |