1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
//! # darwinscope: Mach-O / Objective-C / Swift binary parser
//!
//! A Rust library for statically analyzing Mach-O binaries - the
//! container format used by macOS, iOS, watchOS, tvOS, visionOS, and
//! Mac Catalyst - and the rich Apple-runtime metadata they embed.
//!
//! Given an arbitrary byte slice, `darwinscope` decodes:
//!
//! - The Mach-O container itself: header, load commands, segments,
//! sections, nlist symbol table, bind / export tries, fat-binary
//! slices, dylib graph, `LC_FUNCTION_STARTS`, and the data ranges
//! `LC_DATA_IN_CODE` declares inside code sections.
//! - The embedded **code-signature SuperBlob**: CodeDirectory
//! identifier and Team ID, signing flags, CodeDirectory hash type,
//! embedded CMS signature size, entitlements XML plist (key /
//! value pairs).
//! - The **Objective-C runtime tables**: classes, metaclasses,
//! methods (legacy and small-method-list), instance variables,
//! properties, protocols, categories, and the cross-section
//! reference tables (`__objc_selrefs`, `__objc_classrefs`,
//! `__objc_superrefs`, `__objc_protorefs`).
//! - The **Swift 5 type metadata**: type descriptors
//! (`__swift5_types`), protocol descriptors (`__swift5_protos`),
//! field descriptors (`__swift5_fieldmd`), protocol conformances
//! (`__swift5_proto`), and class vtable entries.
//! - **CoreFoundation constant strings** (`__cfstring`) - both
//! ASCII / UTF-8 (`__TEXT,__cstring`) and UTF-16 LE
//! (`__TEXT,__ustring`) bodies.
//! - **Apple Blocks-runtime metadata** - bind sites for
//! `_NSConcrete{Global,Stack}Block` plus the full
//! `Block_descriptor_{1,2,3}` decode for global block literals
//! (invoke pointer, signature, layout string).
//!
//! The crate handles arm64e pointer authentication (PAC) by
//! canonicalising signed pointers before every dereference, and
//! supports both the legacy bind-opcode pointer format and
//! `LC_DYLD_CHAINED_FIXUPS` chains.
//!
//! ## Motivation
//!
//! Apple binaries are unusually rich static-analysis targets.
//! Stripped Mach-O dylibs and executables still carry:
//!
//! - **Obj-C class hierarchy + selectors** - required at runtime for
//! message dispatch.
//! - **Swift type names + field layouts** - required for runtime
//! reflection, generic specialization, and protocol witness lookup.
//! - **Code-signing identity** - Team ID and bundle identifier,
//! embedded for system-wide code-signing enforcement.
//! - **Entitlements XML** - explicit list of every privileged API
//! the binary requested.
//! - **Function entry points** - `LC_FUNCTION_STARTS` ULEB128 table,
//! used by `dyld` for the unwinder.
//!
//! This metadata survives stripping because the OS depends on it for
//! linking, dispatch, and code-signing enforcement.
//!
//! ## Architecture
//!
//! The crate is organised in layers:
//!
//! - **Container** ([`binary`]): wraps `goblin::mach::MachO` and
//! exposes typed views over the structural layer (`Header`,
//! `Segment`, `Section`, `Symbol`, `Import`, `Export`, `Dylib`,
//! `LoadCommand`).
//! - **Code signing** ([`codesign`]): SuperBlob walker, CodeDirectory
//! parser, entitlements plist decoder.
//! - **Objective-C** ([`objc`]): aggregate [`ObjcRuntime`] walker
//! with `class_t` / `class_ro_t` / `method_list_t` (legacy +
//! small) / `ivar_list_t` / `property_list_t` / `protocol_t` /
//! `category_t` decoders, cross-section reference readers, and
//! class ↔ protocol conformance edges.
//! - **Swift** ([`swift`]): type / protocol / field / conformance /
//! vtable descriptor walkers.
//! - **Support** ([`ptrauth`], [`util`]): pointer-authentication
//! stripping, ULEB128 decoding, virtual-to-file-offset translation.
//!
//! ## Quick start
//!
//! ```no_run
//! use darwinscope::MachoBinary;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let bytes = std::fs::read("/usr/bin/codesign")?;
//! let binary = MachoBinary::parse(&bytes)?;
//!
//! let header = binary.header();
//! println!("cputype=0x{:x} ncmds={}", header.cputype(), header.ncmds());
//! if let Some(uuid) = header.uuid() {
//! println!("uuid={:02x?}", uuid);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## Status
//!
//! v0.1 is under active development. The public API will remain
//! unstable until v0.1 ships.
// The `missing_docs`, `unsafe_code`, `clippy::unwrap_used`,
// `clippy::expect_used`, `clippy::panic`,
// `clippy::arithmetic_side_effects`, and `clippy::indexing_slicing` lints
// are declared in `Cargo.toml` under `[lints]` so they enforce on every
// build regardless of the consuming workspace. darwinscope is used in
// malware-analysis pipelines where every input byte is adversarial and
// the parser must not panic.
pub use MachoBinary;
pub use ;
// CFString constants re-exports.
pub use ;
// Apple Blocks runtime re-exports.
pub use ;
// Objective-C runtime re-exports. Visible at the crate root for
// ergonomic consumers; the full surface lives in [`crate::objc`].
pub use ;
// Swift 5 type-metadata re-exports. Visible at the crate root for
// ergonomic consumers; the full surface lives in [`crate::swift`].
pub use ;