diff options
| -rw-r--r-- | docs/guide/index.md | 31 | ||||
| -rw-r--r-- | docs/guide/sharedcache.md | 135 | ||||
| -rw-r--r-- | docs/img/dsc/alpha.png | bin | 387605 -> 0 bytes | |||
| -rw-r--r-- | docs/img/dsc/cache.png | bin | 247869 -> 0 bytes | |||
| -rw-r--r-- | docs/img/dsc/images.png | bin | 457284 -> 0 bytes | |||
| -rw-r--r-- | docs/img/dsc/symbols.png | bin | 471052 -> 0 bytes | |||
| -rw-r--r-- | docs/img/dsc/triage-images.png | bin | 0 -> 268814 bytes | |||
| -rw-r--r-- | docs/img/dsc/triage-mappings-and-regions.png | bin | 0 -> 333609 bytes | |||
| -rw-r--r-- | docs/img/dsc/triage-symbols.png | bin | 0 -> 274140 bytes | |||
| -rw-r--r-- | mkdocs.yml | 1 |
10 files changed, 136 insertions, 31 deletions
diff --git a/docs/guide/index.md b/docs/guide/index.md index dc5b7d20..e98aab83 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -681,37 +681,6 @@ clickable to navigate to the virtual address. Strings can be double clicked to navigate to them, and the table can be sorted or the list filtered by typing in the search box. -## Dyld Shared Cache Triage (Alpha) - -The Dyld Shared Cache Triage View (or DSCView) allows loading dyld shared cache files from macOS and iOS. You can selectively load specific images, search for specific symbols, and follow analysis between specific images, search for specific symbols, and follow analysis references between any loaded images in one view. - -!!! note "Dyld Shared Cache Tabs" - - === "Image List" - - { width="800" } - - The image list shows a list of all images within the dyld shared cache and their virtual addresses. Double clicking on an image will load the image and begin analyzing it. - - === "Symbol Search" - - { width="800" } - - All symbols exported by each of the shared libraries in the cache can be searched from this view. Double clicking any line will prompt the user whether to load the associated library for that symbol. - - === "Cache" - - { width="800" } - - The cache view shows currently loaded shared objects and is informational only. - - === "Alpha" - - { width="800" } - - The current DSCView is considered an Alpha feature and more details on the limitations and known-issues is included in this tab. As the DSCView leaves alpha state, this tab will be removed. - - ## Byte Overview { width="800" } diff --git a/docs/guide/sharedcache.md b/docs/guide/sharedcache.md new file mode 100644 index 00000000..b3037cf3 --- /dev/null +++ b/docs/guide/sharedcache.md @@ -0,0 +1,135 @@ +# 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. + +## Support Matrix + +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 | + +- **Core**: Core functionality, such as loading, navigating, and analyzing 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`. + +### With blacktop/ipsw tool + +The recommended way to retrieve iOS shared caches is using blacktop's wonderful ipsw tool. + +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 + +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. + +- `your_directory` + - `dyld_shared_cache_arm64` (**Primary**) + - `dyld_shared_cache_arm64.01` (Secondary, optional) + - `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`. +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). + +- `your_project_folder` + - `dyld_shared_cache_arm64` (**Primary**) + - `dyld_shared_cache_arm64.01` (Secondary, optional) + - `dyld_shared_cache_arm64.02` (Secondary, optional) + - `dyld_shared_cache_arm64.symbols` (Symbols, optional) + - `your_database.bndb` (This is recommended) + +## 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. + +### 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. + +=== "Images" + Shows a list of all images within the 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 + - Select image(s) and right click if you want more options for loading images + +  + +=== "Symbols" + Shows a list of all exported symbols within the shared cache and their virtual addresses. + + - Double click on a symbol to load the associated image, or use the "Load Image" button + +  + +=== "Mappings & Regions" + Shows information about the entry mappings and the cache regions. + +  + +### Scripting + +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. + +```python +# Load all dependency images for the current loaded images +from binaryninja import sharedcache +for image in dsc.loaded_images: + dependencies = dsc.get_image_dependencies(image) + for dependency in dependencies: + dep_image = dsc.get_image_with_name(dependency) + if dep_image is None: + continue + dsc.apply_image(bv, dep_image) +``` + +## 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. + +### 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. + +### 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. + +### 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. diff --git a/docs/img/dsc/alpha.png b/docs/img/dsc/alpha.png Binary files differdeleted file mode 100644 index 9d4b18f6..00000000 --- a/docs/img/dsc/alpha.png +++ /dev/null diff --git a/docs/img/dsc/cache.png b/docs/img/dsc/cache.png Binary files differdeleted file mode 100644 index 295ebddd..00000000 --- a/docs/img/dsc/cache.png +++ /dev/null diff --git a/docs/img/dsc/images.png b/docs/img/dsc/images.png Binary files differdeleted file mode 100644 index 450f2805..00000000 --- a/docs/img/dsc/images.png +++ /dev/null diff --git a/docs/img/dsc/symbols.png b/docs/img/dsc/symbols.png Binary files differdeleted file mode 100644 index 0883b7c3..00000000 --- a/docs/img/dsc/symbols.png +++ /dev/null diff --git a/docs/img/dsc/triage-images.png b/docs/img/dsc/triage-images.png Binary files differnew file mode 100644 index 00000000..cf4fb72f --- /dev/null +++ b/docs/img/dsc/triage-images.png diff --git a/docs/img/dsc/triage-mappings-and-regions.png b/docs/img/dsc/triage-mappings-and-regions.png Binary files differnew file mode 100644 index 00000000..df89eea7 --- /dev/null +++ b/docs/img/dsc/triage-mappings-and-regions.png diff --git a/docs/img/dsc/triage-symbols.png b/docs/img/dsc/triage-symbols.png Binary files differnew file mode 100644 index 00000000..e0326081 --- /dev/null +++ b/docs/img/dsc/triage-symbols.png @@ -94,6 +94,7 @@ nav: - Troubleshooting: 'guide/troubleshooting.md' - Objective-C: 'guide/objectivec.md' - Firmware Ninja: 'guide/firmwareninja.md' + - Shared Cache: 'guide/sharedcache.md' - Debugger: - Overview: 'guide/debugger/index.md' - Remote Debugging: 'guide/debugger/remote-debugging.md' |
