Parse Mach-O Load Commands for Dynamic Library and Framework Path Extraction

[unclesp1d3r]

Background

Mach-O binaries (macOS/iOS executables and libraries) embed critical runtime metadata in load commands within the binary header. These commands specify:

• Dynamically linked libraries and frameworks
• Runtime search paths (@rpath, @executable_path, @loader_path)
• Library installation names and version requirements
• Platform minimum version information

Currently, StringyMcStringFace's standard string extraction only scans data sections, missing these header-resident strings that are essential for understanding binary dependencies and runtime behavior.

Problem Statement

Security analysts and reverse engineers need to:

1. Map dependency chains: Identify all dynamically loaded libraries and frameworks
2. Resolve runtime paths: Understand @rpath resolution order for detecting hijacking opportunities
3. Version analysis: Extract minimum platform versions and compatibility constraints
4. Installation verification: Compare expected vs actual library locations

Without load command parsing, these critical artifacts remain hidden from analysis workflows.

Proposed Solution

Architecture Changes

Extend src/container/macho.rs to implement a dedicated load command parser that runs before section-level extraction.

Target Load Commands

Command	Purpose	Example Output
LC_LOAD_DYLIB	Required dynamic libraries	/usr/lib/libSystem.B.dylib
LC_LOAD_WEAK_DYLIB	Optional dynamic libraries	/System/Library/Frameworks/Metal.framework/Metal
LC_REEXPORT_DYLIB	Re-exported libraries	@rpath/MyFramework.framework/MyFramework
LC_ID_DYLIB	Library installation name	/usr/local/lib/libcustom.1.dylib
LC_RPATH	Runtime search paths	@executable_path/../Frameworks
LC_VERSION_MIN_MACOSX	Platform version	10.15.0
LC_BUILD_VERSION	Build version info	Platform + SDK version

Implementation Steps

1. Parse Load Commands - Extend src/container/macho.rs to iterate through load commands using goblin::mach::load_command APIs
2. Extract String Data - Pull path strings from dylib and rpath structures
3. Add Extraction Hook - Call load command extraction before extract_from_sections()
4. Tag Classification - Apply tags: macho-lc, filepath, framework, rpath, version
5. Relevance Scoring - Base score 85-90, boost @rpath paths by +5, frameworks +3

Example Output

String: "/System/Library/Frameworks/Foundation.framework/Foundation"
Source: MachOLoadCommand(LC_LOAD_DYLIB, offset=0x1a8)
Score: 90
Tags: [macho-lc, filepath, framework]

String: "@rpath/CustomFramework.framework/CustomFramework"
Source: MachOLoadCommand(LC_LOAD_DYLIB, offset=0x1f0)
Score: 95
Tags: [macho-lc, filepath, framework, rpath]

String: "@executable_path/../Frameworks"
Source: MachOLoadCommand(LC_RPATH, offset=0x238)
Score: 95
Tags: [macho-lc, rpath]

Implementation Considerations

Path Variable Preservation

• DO NOT resolve or expand path variables
• Preserve @executable_path, @loader_path, @rpath verbatim
• These are runtime-resolved and their literal form is analytically valuable

Multi-Architecture Binaries

• Universal binaries contain multiple Mach-O images
• Extract load commands from each architecture slice independently
• Tag with architecture context (arm64, x86_64, etc.)

Error Handling

• Gracefully handle malformed load commands (corrupted binaries, packers)
• Validate command size fields before string extraction
• Continue extraction on individual command failures

CLI Integration

Add optional filtering: --macho-load-commands flag to show only load command strings

Testing Strategy

Test Cases Required

1. Basic Dylib Loading - Test binary with standard system library dependencies
2. Framework Dependencies - Binary using Cocoa/UIKit frameworks
3. @rpath Usage - Binary with embedded framework using @rpath
4. Universal Binary - Fat binary with arm64 + x86_64 slices
5. Malformed Commands - Truncated structures, invalid sizes, non-UTF8 data

Test Binaries

Use real-world samples from:

• macOS system binaries (/bin/ls, /usr/bin/ssh)
• iOS apps (.ipa extraction)
• Custom test binaries with controlled dependencies

Success Criteria

• All standard load command types parsed
• String extraction working for dylib/rpath commands
• Path variables preserved correctly
• Universal binary support (multiple architectures)
• Appropriate tags and scoring applied
• CLI filter option implemented
• Test coverage >80% for new code
• Documentation updated with examples

References

• Mach-O File Format Reference
• goblin crate documentation
• dyld source code - @rpath resolution semantics
• Dynamic Library Programming Topics

Related Work

This complements existing PE import parsing (if implemented) and provides Mach-O parity with other binary format analyzers.

[traycerai]

Plan

Observations

The codebase uses goblin for parsing Mach-O in src/container/macho.rs, extracting sections, imports, and exports into ContainerInfo from src/types.rs. StringSource already includes LoadCommand, but Tag needs Mach-O specifics. ContainerInfo requires a new load_command_strings field. ELF and PE parsers in src/container/ must initialize it empty. CLI in src/main.rs is basic; add flag. Integration tests in tests/integration_macho.rs use test_binary_macho fixture. Docs in docs/src/ cover formats and architecture.

Approach

Extend MachoParser to parse load commands via goblin, extracting strings from dylibs, rpaths, versions into FoundStrings with tags like MachOLoadCommand, RPath, Framework, scores 85-95. Preserve @variables. Update ContainerInfo with load_command_strings. Initialize empty in ELF/PE. Add CLI --macho-load-commands flag for filtering. Implement tests for extraction accuracy using fixtures. Update docs with examples, supported commands, and integration details.

Reasoning

I listed project directories to map structure, focusing on src/container and tests. I read macho.rs to analyze current parsing flow for sections/imports. I examined types.rs for enums and structs to plan extensions. I reviewed elf.rs and pe.rs for consistency. I checked main.rs for CLI integration. I inspected test fixtures and integration tests for validation strategy. I browsed docs for update points.

Proposed File Changes

📄 src/types.rs ^(MODIFY) 🔗

References

• 📄 src/container/macho.rs ^(MODIFY)

Extend Tag enum:

Add variants: MachOLoadCommand (#[serde(rename = "macho-lc")]), RPath, Framework.

Update ContainerInfo:

Add pub load_command_strings: Vec<FoundString> after exports.

Refer to macho.rs for usage in Mach-O parsing; ELF/PE will use empty vec.

📄 src/container/macho.rs ^(MODIFY) 🔗

References

• 📄 src/types.rs ^(MODIFY)

Add extract_load_commands method:

Take &MachO, compute base offset. Iterate macho.load_commands:

• Dylib commands (LC_LOAD_DYLIB etc.): Extract name as text, tags MachOLoadCommand + FilePath; if .framework, add Framework. Preserve @vars. Offset: command offset + name offset. Score: 85 +5 for @rpath +3 framework.
• LC_RPATH: Extract path, tags MachOLoadCommand + RPath, score 90 +5 @rpath.
• Version (LC_VERSION_MIN_MACOSX etc.): Format version, tags MachOLoadCommand + Version, score 85.

Set source: LoadCommand, encoding: Utf8, section: None, rva: None, length: text.len() as u32.

Handle fat binaries by adjusting offsets per arch.

Update parse_single_macho:

Call extract_load_commands after extract_imports, add to ContainerInfo { ..., load_command_strings }.

Update parse_fat_binary:

Pass arch offset to extract_load_commands for accurate positioning.

Refer to types.rs for FoundString fields.

📄 src/container/elf.rs ^(MODIFY) 🔗

References

• 📄 src/types.rs ^(MODIFY)

Update parse method:

In ContainerInfo creation, add load_command_strings: vec![] to maintain compatibility.

Refer to updated ContainerInfo in types.rs.

📄 src/container/pe.rs ^(MODIFY) 🔗

References

• 📄 src/types.rs ^(MODIFY)

Update parse method:

In ContainerInfo creation, add load_command_strings: vec![] to maintain compatibility.

Refer to updated ContainerInfo in types.rs.

📄 src/main.rs ^(MODIFY) 🔗

References

• 📄 src/types.rs ^(MODIFY)
• 📄 src/container/macho.rs ^(MODIFY)

Extend Cli:

Add #[arg(long, short = 'l', help = "Filter to Mach-O load commands only")] pub macho_load_commands: bool.

Update main:

Read input file, detect format, parse with appropriate parser. If MachO and flag set, output only load_command_strings as JSON/table. Else, basic output all strings.

Implement simple JSON serialization for FoundString using serde.

Refer to types.rs for structs.

📄 tests/integration_macho.rs ^(MODIFY) 🔗

References

• 📄 src/container/macho.rs ^(MODIFY)
• 📄 tests/fixtures/test_binary_macho

Add test_load_commands_extraction:

Read fixtures/test_binary_macho, parse with MachoParser. Assert container_info.load_command_strings non-empty. Verify specific FoundStrings: dylib paths with FilePath/Framework, rpaths with RPath, versions with Version. Check scores, preserved @vars, offsets. For fat binary, verify multi-arch if applicable.

Use serde_json for assertions if needed.

Refer to macho.rs and fixture.

📄 docs/src/architecture.md ^(MODIFY) 🔗

References

• 📄 src/container/macho.rs ^(MODIFY)

Update Container Module:

Add Mach-O load commands extraction into load_command_strings via goblin. Describe flow: parse commands before sections, tag/score for dependency analysis.

Update formats table: Mach-O includes "Load Commands (dylibs, rpaths, versions)".

Refer to macho.rs.

📄 docs/src/binary-formats.md ^(MODIFY) 🔗

References

• 📄 src/container/macho.rs ^(MODIFY)

Add Mach-O Load Commands section:

List supported: LC_LOAD_DYLIB (tags: macho-lc, filepath, framework), LC_RPATH (rpath), LC_VERSION_MIN (version). Examples:

• "/usr/lib/libSystem.B.dylib" (score 88, tags [macho-lc, filepath])
• "@rpath/Frameworks/MyLib.framework/MyLib" (93, [macho-lc, filepath, framework, rpath])

Note: Preserve @vars, fat binary support, error handling. Reference Apple/goblin docs.

Refer to macho.rs.

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

The codebase uses goblin for parsing Mach-O in `src/container/macho.rs`, extracting sections, imports, and exports into `ContainerInfo` from `src/types.rs`. `StringSource` already includes `LoadCommand`, but `Tag` needs Mach-O specifics. `ContainerInfo` requires a new `load_command_strings` field. ELF and PE parsers in `src/container/` must initialize it empty. CLI in `src/main.rs` is basic; add flag. Integration tests in `tests/integration_macho.rs` use `test_binary_macho` fixture. Docs in `docs/src/` cover formats and architecture.

### Approach

Extend `MachoParser` to parse load commands via goblin, extracting strings from dylibs, rpaths, versions into `FoundString`s with tags like `MachOLoadCommand`, `RPath`, `Framework`, scores 85-95. Preserve @variables. Update `ContainerInfo` with `load_command_strings`. Initialize empty in ELF/PE. Add CLI `--macho-load-commands` flag for filtering. Implement tests for extraction accuracy using fixtures. Update docs with examples, supported commands, and integration details.

### Reasoning

I listed project directories to map structure, focusing on src/container and tests. I read `macho.rs` to analyze current parsing flow for sections/imports. I examined `types.rs` for enums and structs to plan extensions. I reviewed `elf.rs` and `pe.rs` for consistency. I checked `main.rs` for CLI integration. I inspected test fixtures and integration tests for validation strategy. I browsed docs for update points.

## Proposed File Changes

### src/types.rs(MODIFY)

References: 

- src/container/macho.rs(MODIFY)

# Extend `Tag` enum:

Add variants: `MachOLoadCommand` (#[serde(rename = "macho-lc")]), `RPath`, `Framework`.

# Update `ContainerInfo`:

Add `pub load_command_strings: Vec<FoundString>` after `exports`.

Refer to `macho.rs` for usage in Mach-O parsing; ELF/PE will use empty vec.

### src/container/macho.rs(MODIFY)

References: 

- src/types.rs(MODIFY)

# Add `extract_load_commands` method:

Take `&MachO`, compute base offset. Iterate `macho.load_commands`:
- Dylib commands (LC_LOAD_DYLIB etc.): Extract `name` as `text`, tags `MachOLoadCommand` + `FilePath`; if `.framework`, add `Framework`. Preserve @vars. Offset: command offset + name offset. Score: 85 +5 for @rpath +3 framework.
- LC_RPATH: Extract `path`, tags `MachOLoadCommand` + `RPath`, score 90 +5 @rpath.
- Version (LC_VERSION_MIN_MACOSX etc.): Format version, tags `MachOLoadCommand` + `Version`, score 85.

Set `source: LoadCommand`, `encoding: Utf8`, `section: None`, `rva: None`, `length: text.len() as u32`.

Handle fat binaries by adjusting offsets per arch.

# Update `parse_single_macho`:

Call `extract_load_commands` after `extract_imports`, add to `ContainerInfo { ..., load_command_strings }`.

# Update `parse_fat_binary`:

Pass arch offset to `extract_load_commands` for accurate positioning.

Refer to `types.rs` for `FoundString` fields.

### src/container/elf.rs(MODIFY)

References: 

- src/types.rs(MODIFY)

# Update `parse` method:

In `ContainerInfo` creation, add `load_command_strings: vec![]` to maintain compatibility.

Refer to updated `ContainerInfo` in `types.rs`.

### src/container/pe.rs(MODIFY)

References: 

- src/types.rs(MODIFY)

# Update `parse` method:

In `ContainerInfo` creation, add `load_command_strings: vec![]` to maintain compatibility.

Refer to updated `ContainerInfo` in `types.rs`.

### src/main.rs(MODIFY)

References: 

- src/types.rs(MODIFY)
- src/container/macho.rs(MODIFY)

# Extend `Cli`:

Add `#[arg(long, short = 'l', help = "Filter to Mach-O load commands only")] pub macho_load_commands: bool`.

# Update `main`:

Read input file, detect format, parse with appropriate parser. If MachO and flag set, output only `load_command_strings` as JSON/table. Else, basic output all strings.

Implement simple JSON serialization for `FoundString` using serde.

Refer to `types.rs` for structs.

### tests/integration_macho.rs(MODIFY)

References: 

- src/container/macho.rs(MODIFY)
- tests/fixtures/test_binary_macho

# Add `test_load_commands_extraction`:

Read `fixtures/test_binary_macho`, parse with `MachoParser`. Assert `container_info.load_command_strings` non-empty. Verify specific `FoundString`s: dylib paths with `FilePath`/`Framework`, rpaths with `RPath`, versions with `Version`. Check scores, preserved @vars, offsets. For fat binary, verify multi-arch if applicable.

Use `serde_json` for assertions if needed.

Refer to `macho.rs` and fixture.

### docs/src/architecture.md(MODIFY)

References: 

- src/container/macho.rs(MODIFY)

# Update Container Module:

Add Mach-O load commands extraction into `load_command_strings` via goblin. Describe flow: parse commands before sections, tag/score for dependency analysis.

Update formats table: Mach-O includes "Load Commands (dylibs, rpaths, versions)".

Refer to `macho.rs`.

### docs/src/binary-formats.md(MODIFY)

References: 

- src/container/macho.rs(MODIFY)

# Add Mach-O Load Commands section:

List supported: LC_LOAD_DYLIB (tags: macho-lc, filepath, framework), LC_RPATH (rpath), LC_VERSION_MIN (version). Examples:
- "/usr/lib/libSystem.B.dylib" (score 88, tags [macho-lc, filepath])
- "@rpath/Frameworks/MyLib.framework/MyLib" (93, [macho-lc, filepath, framework, rpath])

Note: Preserve @vars, fat binary support, error handling. Reference Apple/goblin docs.

Refer to `macho.rs`.

---

Developer Humor

> Why did the dylib go to therapy?\n> It had too many unresolved dependencies! 🔗😅\n> Now with load commands, we're linking it all up. 🚀

---

Execution Information

Branch: main
Commit: 37cfc7c

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.