dylex 2.3.2

A high-performance dyld shared cache extractor for macOS and iOS
Documentation

dylex

Crates.io Documentation License: MIT Rust

A high-performance dyld shared cache extractor for macOS and iOS, written in Rust.

dylex extracts Mach-O files for static analysis from Apple's dyld shared cache, with symbol table reconstruction, pointer decoding, and LINKEDIT rebuilding. Extraction does not reconstruct a runnable OS loader environment.

Features

  • Fast Extraction - Memory-mapped I/O and parallel processing for maximum speed
  • Automatic Cache Discovery - Finds system caches automatically on macOS
  • Architecture Selection - Support for 32-bit ARM (armv6, armv7, armv7s, armv7k), arm64, arm64e, and x86_64 caches
  • Symbol Table Reconstruction - Rebuilds standalone LINKEDIT with proper symbol tables
  • Pointer Rebasing - Handles slide info v3/v5 for correct pointer values
  • ObjC Metadata Restoration - Reconstructs coalesced strings and absolute method entries before clearing encoding flags
  • Cache Islands - Retains referenced sectionless ARM64 stubs and libobjcMsgSend* dispatcher code
  • Rosetta Cache Products - Discovers native, full Rosetta, and reduced x86Support trees separately
  • Directory Structure Preservation - Optionally preserves full framework paths
  • Batch Extraction - Extract multiple images with filters and parallel processing
  • String Search - Find a literal string or hex byte sequence in cache images, with an optional image filter, in one architecture or every discovered cache. extract --search writes every image that contains the match

See cache compatibility and validation for the tested macOS 27 build, older-format fixtures, source provenance, assumptions, and mode limitations.

Installation

From crates.io

cargo install dylex

From Source

git clone https://github.com/19h/dylex
cd dylex
cargo install --path .

GitHub Actions binaries

The macOS build workflow tests and builds Intel (x86_64) and Apple Silicon (arm64) binaries on pushes, pull requests, and manual runs. Download dylex-x86_64-apple-darwin or dylex-aarch64-apple-darwin from the run's artifacts. Each contains a .tar.gz with the executable and license, plus a SHA-256 checksum file.

See CI build details for runner selection and validation scope.

Quick Start

# List available architectures in the system cache
dylex arches

# Show cache information
dylex info -a arm64e

# List all images containing "UIKit"
dylex list -a arm64e -f UIKit

# Find images that contain a literal string
dylex strings -a arm64e -f IOHID com.apple.hid.manager.user-access-device

# Find images that contain a hex byte sequence
dylex strings -a arm64e -x '63 6f 6d 2e 61 70 70 6c 65'

# Search every image in every discovered architecture cache
dylex strings --all-arches com.apple.hid.manager.user-access-device

# Extract a single library
dylex extract -a arm64e -i libobjc.A.dylib -o libobjc.A.dylib

# Extract all MapKit-related frameworks with preserved paths
dylex extract -a arm64e -f MapKit -o ./extracted

# Extract every image that contains a literal string
dylex extract -a arm64e --search com.apple.hid.manager.user-access-device -o ./hid

# Extract every image that contains a hex byte sequence
dylex extract -a arm64e --hex --search '63 6f 6d 2e 61 70 70 6c 65' -o ./hid

For an exact x86_64 cache, pass its path as the positional [CACHE] argument. -a/--arch accepts architecture names such as x86_64:

# Select the reduced Rosetta x86Support cache
cache=/System/Volumes/Preboot/Cryptexes/Rosetta/System/x86Support/System/Library/dyld/dyld_shared_cache_x86_64
dylex list "$cache" -f dyld
dylex extract "$cache" -f dyld -o ./x86_64-dyld

# Extract every image in that cache
dylex extract "$cache" -f '' -o ./x86_64-all

To select the full Rosetta cache, use /System/Volumes/Preboot/Cryptexes/Rosetta/System/Library/dyld/dyld_shared_cache_x86_64 instead. When both caches are discovered, -a x86_64 alone is ambiguous.

Commands

dylex extract

Extract images from the dyld shared cache.

Usage: dylex extract [OPTIONS] [CACHE]

Arguments:
  [CACHE]  Path to the dyld shared cache (file or directory).
           If not specified, searches default system locations.

Options:
  -i, --image <IMAGE>           Image to extract (e.g., "UIKit" or full path)
  -f, --filter <FILTER>         Filter images by substring match
      --search <STRING>         Extract every image that contains this string or hex bytes
  -x, --hex                     Interpret --search as hex bytes
      --ignore-case             ASCII case-insensitive --search
  -a, --arch <ARCH>             Architecture (arm64e, arm64, x86_64)
  -o, --output <OUTPUT>         Output path (file or directory)
      --merge-image <IMAGE>    Merge a selected additional image (repeatable)
      --merge-runtime          Merge directly referenced runtime libraries
      --merge-plan             Preview merge selection and reference evidence
      --merge-deps             Experimental automatic dependency merge
      --merge-depth <N>        Depth for --merge-deps [default: 1]
      --preserve-paths <BOOL>   Preserve directory structure [default: auto]
  -v, --verbosity <LEVEL>       Verbosity (0=quiet, 1=warn, 2=info, 3=debug)
  -j, --jobs <N>                Parallel jobs (default: CPU count)
  -h, --help                    Print help

Examples

# Extract single image to specific file
dylex extract -a arm64e -i libobjc.A.dylib -o /tmp/libobjc.dylib

# Extract by full path
dylex extract -a arm64e -i /System/Library/Frameworks/UIKit.framework/UIKit

# Extract all Foundation-related images
dylex extract -a arm64e -f Foundation -o ./foundation_libs

# Extract every image whose bytes contain the string.
# --filter limits which images are searched. Output is always a directory.
dylex extract -a arm64e --search com.apple.hid.manager.user-access-device -o ./hid
dylex extract -a arm64e -f IOHID --search user-access-device --ignore-case -o ./hid
dylex extract -a arm64e --hex --search '63 6f 6d 2e 61 70 70 6c 65' -o ./hid

# Extract everything (warning: large!)
dylex extract -a arm64e -f "" -o ./all_binaries

# Extract with verbose output
dylex extract -a arm64e -i CoreFoundation -v 2

# Use custom cache path
dylex extract -a arm64e -i libobjc.A.dylib /path/to/dyld_shared_cache_arm64e

Merge referenced runtime libraries

# Inspect which runtime images are referenced and where
dylex extract -i GeoServicesCore --merge-runtime --merge-plan

# Merge the inferred runtime set
dylex extract -i GeoServicesCore --merge-runtime

# Add an explicit framework to the roots used for runtime inference
dylex extract -i GeoServicesCore --merge-runtime --merge-image GeoServices

--merge-runtime selects directly referenced libraries in /usr/lib/system/, Objective-C, libc++, libc++abi, libSystem, and /usr/lib/swift/libswift*.dylib. It scans ARM64 direct branches and declared pointer sections, resolves recognized stubs, and reports reference counts with an example source/target chain for each inferred image. The primary and explicit additions are scan roots. Inferred libraries are not scanned recursively; dependency lists do not drive selection. Frameworks and other libraries remain explicit additions.

--merge-plan writes no output. Computed calls without static pointer evidence are unknown; x86 inference uses pointer sections rather than instruction decoding. On the tested cache, GeoServicesCore selects ten runtime libraries. Empty section markers left by cache optimization are omitted unless a symbol references them. All populated sections are retained regardless of count. Because nlist n_sect is 8 bits, a symbol in a section past ordinal 255 carries the ordinal of an earlier section of the same kind; its address stays exact. Adding GeoServices as a root infers 29 runtime images and merges 31 images into 724 sections.

Merge selected images

Use --merge-image once per additional image. This selects the primary image and the listed images without traversing their dependency lists:

dylex extract -i GeoServicesCore \
  --merge-image libdispatch.dylib \
  --merge-image libobjc.A.dylib \
  -o GeoServicesCore.selected

Image selection prefers a full path, then an exact basename, then a unique substring. Ambiguous names produce an error listing candidate paths. Repeated images are included once, and the command prints the canonical selection. --merge-image and --merge-runtime cannot be combined with --merge-deps, --merge-depth, --with-deps, or --filter.

The output keeps source virtual addresses and instruction bytes. It combines sections, symbols, indirect-symbol tables, and function-start labels; referenced cache trampolines/dispatchers and Objective-C metadata are restored for the combined image. Those support regions can make output substantially larger than the selected images' own segments. External targets outside the selection can remain unmapped. These outputs are for static analysis; runtime loading is not supported. Open the newly extracted file in a fresh IDA database.

See selected-merge validation for tested behavior and format limits. The automatic --merge-deps mode retains its older experimental relocation pipeline.

dylex list

List images in the cache.

Usage: dylex list [OPTIONS] [CACHE]

Options:
  -a, --arch <ARCH>       Architecture to use
  -f, --filter <FILTER>   Filter images by name
  -A, --addresses         Show virtual addresses
  -b, --basenames         Show only basenames (not full paths)
  -h, --help              Print help

Examples

# List all images
dylex list -a arm64e

# List with addresses
dylex list -a arm64e -A

# Filter and show basenames
dylex list -a arm64e -f Swift -b

# Count images matching filter
dylex list -a arm64e -f Framework | wc -l

dylex strings

Search file-backed bytes of cache images for a literal string. --hex reads the needle as bytes instead: deadbeef, de ad be ef, 0xde:ad, and \xde\xad are the same four bytes. Quote a needle that contains spaces. Omit --filter to search every image. --arch selects one architecture and can be repeated. --all-arches searches every discovered cache, including both Rosetta products. With no architecture flag and no cache path, the command uses the same native cache default as the other commands.

A segment range mapped by more than one image is skipped. On current caches that range is the shared __LINKEDIT. Objective-C strings coalesced into a single image are reported on that image.

Each match is one line:

arm64e  /System/Library/Extensions/IOHIDFamily.kext/IOHIDFamily  __TEXT,__cstring  0x180abc000  com.apple.hid.manager.user-access-device

When more than one cache is searched, the cache file name is included after the architecture. The address is the start of the enclosing C string when the match is an ASCII printable run ending in NUL. A summary is written to stderr.

Usage: dylex strings [OPTIONS] <NEEDLE> [CACHE]

Arguments:
  <NEEDLE>  Literal string to find, or hex bytes with --hex
  [CACHE]   Path to the dyld shared cache (file or directory)

Options:
  -x, --hex               Interpret the needle as hex bytes
  -f, --filter <FILTER>   Only search images whose path contains this substring
  -a, --arch <ARCH>       Architecture to search, repeatable
      --all-arches        Search every discovered architecture cache
  -i, --ignore-case       Compare ASCII letters without regard to case
  -j, --jobs <N>          Parallel jobs (default: number of CPUs)
  -h, --help              Print help

Examples

# One architecture, every image
dylex strings -a arm64e com.apple.hid.manager.user-access-device

# Only images whose path contains IOHID
dylex strings -a arm64e -f IOHID com.apple.hid.manager.user-access-device

# Every discovered architecture cache
dylex strings --all-arches com.apple.hid.manager.user-access-device

# Hex bytes. Spaces, colons, dashes, and 0x prefixes are optional
dylex strings -a arm64e -x '63 6f 6d 2e 61 70 70 6c 65'
dylex strings -a arm64e --hex 0xdeadbeef

# One exact cache file
dylex strings com.apple.hid.manager.user-access-device /path/to/dyld_shared_cache_arm64e

dylex info

Display detailed cache information.

Usage: dylex info [OPTIONS] [CACHE]

Options:
  -a, --arch <ARCH>   Architecture to use
  -h, --help          Print help

Example Output

Dyld Shared Cache Information
==============================
Path:         /System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/dyld_shared_cache_arm64e
Architecture: arm64e
Images:       3554
Mappings:     22
Subcaches:    2
Total size:   5307.38 MB

Mappings:
  [ 0] 0x0000000180000000 - 0x00000001e6660000 (    1.6G) r-x
  [ 1] 0x00000001e6660000 - 0x00000001e8874000 (   34.1M) r-- [slide]
  ...

Subcaches:
  [ 1] dyld_shared_cache_arm64e.01 (2543.53 MB)
  [ 2] dyld_shared_cache_arm64e.02 (196.12 MB)

dylex arches

List available cache architectures.

Usage: dylex arches [PATH]

Arguments:
  [PATH]  Directory to search. If not specified, uses system default.

Example Output

Available architectures in /System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld:
  arm64e - dyld_shared_cache_arm64e
  x86_64 - dyld_shared_cache_x86_64

dylex lookup

Find which image contains a specific unslid cache address. Cache-owned ARM64 stub islands are followed to their target image (up to 64 hops, with cycle detection). Output includes the image path, segment, exact symbol or nearest preceding symbol, an extraction command using the same cache, and a --merge-image option. A nearest symbol does not establish function extent.

For the cache used in this validation:

0x2480895f0 → 0x1806cf570 → /usr/lib/system/libdispatch.dylib
Symbol: _dispatch_once

0x2480896b0 → 0x180410d48 → /usr/lib/libobjc.A.dylib
Symbol: _objc_retainAutoreleaseReturnValue

Addresses vary between cache builds.

Usage: dylex lookup [OPTIONS] <ADDRESS> [CACHE]

Arguments:
  <ADDRESS>   Address to lookup (hex, e.g., 0x180000000)

Options:
  -a, --arch <ARCH>   Architecture to use
  -h, --help          Print help

Default Cache Locations

When no cache path is specified, dylex searches these locations in order:

  1. /System/Volumes/Preboot/Cryptexes (OS, DriverKit, staged updates, and Rosetta products)
  2. /System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld
  3. /System/Volumes/Preboot/Cryptexes/OS/System/DriverKit/System/Library/dyld
  4. /System/Volumes/Preboot/Cryptexes/Incoming/OS/System/Library/dyld
  5. /System/Volumes/Preboot/Cryptexes/Incoming/OS/System/DriverKit/System/Library/dyld
  6. /System/Library/dyld
  7. /var/db/dyld

Commands without --arch retain the native system-cache default. dylex arches lists each product separately. dylex strings --all-arches searches every discovered product. Single-cache selection, including --arch arm, prefers matching primary caches over Incoming and DriverKit products. An explicit cache file or directory selects those products directly. When --arch x86 matches both Rosetta caches, an exact main-file path selects the product:

dylex info /System/Volumes/Preboot/Cryptexes/Rosetta/System/Library/dyld/dyld_shared_cache_x86_64
dylex info /System/Volumes/Preboot/Cryptexes/Rosetta/System/x86Support/System/Library/dyld/dyld_shared_cache_x86_64

These Rosetta paths were observed on macOS 27 build 26A5425a. Discovery also includes staged Incoming updates and DriverKit subtrees. If multiple products remain after applying the preference, select the exact main cache file using positional [CACHE].

32-bit ARM caches

Legacy little-endian ARM caches use MH_MAGIC (0xfeedface), a 28-byte header, LC_SEGMENT, 68-byte sections, 12-byte symbol entries, and 4-byte pointers. Dylex preserves this ABI throughout extraction, including Thumb symbol descriptors and pointer state bits. It supports slide formats v1 (bitmap), v2 (32-bit chains), and v4 (chains with small integer entries), cache-local symbols, indirect symbol tables, ARM lazy stubs, and Objective-C classes, categories, protocols, methods, ivars, properties, and selectors. Pointer fields absent from a slide chain retain their original absolute values.

Pass the cache path positionally; no architecture override is necessary:

cargo build --release
cache=/path/to/dyld_shared_cache_armv7s
./target/release/dylex extract "$cache" -f dylib -o ./armv7s-dylibs
./target/release/dylex extract "$cache" -f '' -o ./armv7s-all
./target/release/dylex extract "$cache" -i /usr/lib/libobjc.A.dylib \
    --merge-image /usr/lib/libSystem.B.dylib -o ./objc-system.dylib

Selected-image and dependency merges retain original ARM/Thumb code addresses. Install-name aliases sharing an image address are merged once. Runtime inference uses declared 4-byte pointer sections, recognized ARM stubs, and direct ARM/Thumb branches where mapped or cache-local symbols establish instruction mode. Instruction regions with unknown mode and register-only targets remain unknown. As with other architectures, outputs are for static analysis; loading them on an iOS device is not a validation criterion.

MachOContext exposes widened segment, section, symbol, and header fields in its existing Rust types. Use header_size(), pointer_size(), nlist_size(), write_segment(), write_section(), and sync_header() rather than serializing those widened structures directly into a 32-bit image.

Validation includes synthetic armv6/armv7/armv7s/armv7k fixtures, slide v1/v2/v4, Objective-C graphs, cache-local symbols, aliases, dependencies, runtime inference, and both merge paths. A separate standard-library Python verifier checks an archived ARM32 v2 cache and its extraction directory without using Dylex's parser:

cargo test --all-targets
python3 scripts/verify_arm32_cache.py "$cache" ./armv7s-all --report verification.json

The verifier checks every image path, code byte preservation, complete and partial slide words, symbol and indirect-symbol bounds, dyld-info extents, and Objective-C class/method/selector references. It currently targets monolithic ARM32 v2 caches; synthetic Rust tests cover v1 and v4.

Format references: Apple's Mach-O loader definitions, slide format definitions, ARM stub/Thumb branch optimizer, and Objective-C runtime layouts.

Architecture Selection

The --arch flag uses substring matching:

Flag Matches
-a arm64e arm64e only
-a arm64 arm64 and arm64e
-a x86 x86_64 and x86_64h

If multiple architectures match, you'll be prompted to be more specific.

Output Structure

Single Image Extraction

By default, single images are extracted to the current directory with their basename:

dylex extract -a arm64e -i libobjc.A.dylib
# Creates: ./libobjc.A.dylib

Batch Extraction with Filter

When using -f/--filter, directory structure is preserved by default:

dylex extract -a arm64e -f MapKit -o ./extracted

# Creates:
# ./extracted/System/Library/Frameworks/MapKit.framework/Versions/A/MapKit
# ./extracted/System/Library/Frameworks/_MapKit_SwiftUI.framework/Versions/A/_MapKit_SwiftUI
# ./extracted/usr/lib/swift/libswiftMapKit.dylib
# ...

Use --preserve-paths false to flatten:

dylex extract -a arm64e -f MapKit -o ./flat --preserve-paths false

# Creates:
# ./flat/MapKit
# ./flat/_MapKit_SwiftUI
# ./flat/libswiftMapKit.dylib

What dylex Does

When extracting an image, dylex performs these operations:

  1. Copies Segment Data - Extracts __TEXT, __DATA, __LINKEDIT, etc.
  2. Rebases Pointers - Applies slide info to fix pointer values
  3. Rebuilds LINKEDIT - Creates standalone symbol table, string table, and other metadata (replaces ~600MB shared LINKEDIT)
  4. Fixes ObjC Metadata - Clears OBJC_IMAGE_OPTIMIZED_BY_DYLD flag
  5. Updates Load Commands - Adjusts offsets for standalone operation
  6. Optimizes File Layout - Removes unnecessary padding

Library Usage

dylex can be used as a library:

use dylex::{DyldContext, extract_image_with_options, ExtractionOptions};

fn main() -> anyhow::Result<()> {
    // Open the cache
    let cache = DyldContext::open("/path/to/dyld_shared_cache_arm64e")?;
    
    // List images
    for image in cache.iter_images() {
        println!("{}: {:#x}", image.path, image.address);
    }
    
    // Extract an image
    let options = ExtractionOptions::default();
    extract_image_with_options(
        &cache,
        "/usr/lib/libobjc.A.dylib",
        "libobjc.A.dylib",
        options,
    )?;
    
    Ok(())
}

Performance

dylex is designed for speed:

  • Memory-mapped I/O - No unnecessary copying
  • Parallel extraction - Uses all CPU cores for batch operations
  • Efficient data structures - FxHashMap for fast lookups
  • LTO-optimized release builds - Maximum binary performance

Typical extraction times on Apple M1:

  • Single library: ~0.3s
  • 100 libraries: ~5s
  • Full cache (~3500 images): ~3-5 minutes

Limitations

  • macOS/iOS only - dyld caches are Apple-specific
  • Read-only - Cannot modify or repack caches
  • No code signing - Extracted binaries need re-signing for execution
  • External references - Ordinary inter-library targets can remain external
  • Analysis layout - Images with insufficient header padding use a separate __DYLEX_HDR segment; original code addresses remain unchanged
  • Unknown extensions - Version-4 ObjC optimization fields after the common prefix are not interpreted as version-2 buffer sizes
  • Merged extraction - --merge-image supports explicit selection at cache addresses, with at most 255 retained symbol sections after removing unused empty markers. --merge-deps retains its separate experimental relocation pipeline

Comparison with Other Tools

Feature dylex dsc_extractor DyldExtractor
Language Rust C++ Python
Speed Fast Medium Slow
LINKEDIT rebuild Yes Partial Yes
Slide info v5 Yes Yes Yes
Parallel extraction Yes No No
Library API Yes No Yes

Troubleshooting

"No dyld shared caches found"

The default cache locations may not exist on your system. Specify the path explicitly:

dylex info /path/to/cache/directory

"Multiple caches match"

If different architectures match, use a more specific architecture:

# Instead of -a arm64 (matches arm64 and arm64e)
dylex info -a arm64e

If both caches have the same architecture (e.g., the full and reduced Rosetta products), select the exact cache with its positional path:

dylex info /System/Volumes/Preboot/Cryptexes/Rosetta/System/Library/dyld/dyld_shared_cache_x86_64

Cache path passed to -a/--arch

Move the cache path out of the architecture option:

dylex list /path/to/dyld_shared_cache_x86_64 -f dyld
dylex extract /path/to/dyld_shared_cache_x86_64 -f dyld -o ./x86_64-dyld

Extracted binary won't run

Extraction produces files for static analysis. Code signing alone does not restore bind/rebase metadata, cache-wide runtime state, or unresolved external references.

Large extracted file sizes

Some libraries (like libobjc) include large shared ObjC metadata segments. This is expected behavior.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

  • Inspired by DyldExtractor
  • Apple's dyld source code for format documentation
  • The reverse engineering community