From 7bbd310455694e31f87a810442ee78bbae66e59d Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 22 May 2026 23:51:42 +0000 Subject: [PATCH] Rewrite README: clearer structure, current features, cross-platform Reorganize both READMEs around features (structure/navigation, Apple binary internals, code & xref, dyld cache, UX, automation, robustness), add a table of contents, supported-formats and CLI option tables, badges (CI, release, platforms), and a cross-platform build section. Reflect capabilities added since the last revision: code signature / entitlements parsing, layout and opened-table search, off-thread parsing, Linux support, and the malformed-input hardening story. Keep the simplified Star History badge. https://claude.ai/code/session_013kBiVXftgoEsyGVyrvfGok --- README.md | 158 ++++++++++++++++++++++++++++++++++++------------ README.zh-CN.md | 151 ++++++++++++++++++++++++++++++++++----------- 2 files changed, 235 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 9633b10..e71a1d1 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,97 @@ # MachOExplorer -A focused desktop explorer for Mach-O binaries, archives, and dyld shared cache. +> A focused desktop explorer for Mach-O binaries, Fat/Universal binaries, `.a` archives, and the dyld shared cache — built for people who reverse engineer and inspect Apple binaries. Language: **English** | [简体中文](README.zh-CN.md) ![MachOExplorer Screenshot](image/screenshot.png) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) - -## Why MachOExplorer -- Open and inspect Mach-O / Fat Mach-O / `.a` archive / dyld shared cache in one UI. -- Drill from structure to code quickly: sections, symbols, disassembly, xref, call graph hints. -- Understand modern Apple binaries better: ObjC metadata, Swift metadata, dyld exports/fixups. -- Work safely on suspicious files with hardened parser checks and regression coverage. - -## Highlights -- Rich binary views: load commands, sections, symbols, relocations, strings. -- Optional Capstone disassembly for `__TEXT,__text`. -- Swift semantic graph (`__swift5_*`) and ObjC metadata browsing. -- Dyld shared cache image listing/extraction and direct drill-in workflow. -- Productive table UX: filter, copy row(s), CSV export, keyboard navigation. -- Built-in update check with reminder options and release-page guidance. - -## Install (macOS) -- Latest release: -- Homebrew: +[![Linux CI](https://github.com/everettjf/MachOExplorer/actions/workflows/linux.yml/badge.svg)](https://github.com/everettjf/MachOExplorer/actions/workflows/linux.yml) +[![Latest Release](https://img.shields.io/github/v/release/everettjf/MachOExplorer)](https://github.com/everettjf/MachOExplorer/releases/latest) +[![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#install) + +MachOExplorer turns an opaque Mach-O file into a navigable tree. Open a binary and drill from the +file structure all the way down to load commands, sections, symbols, disassembly, and Apple-specific +metadata (Objective-C, Swift, code signing) — in one window, or fully scripted from the command line. + +## Contents +- [Features](#features) +- [Supported formats](#supported-formats) +- [Install](#install) +- [Quick start](#quick-start) +- [CLI / automation mode](#cli--automation-mode) +- [Build from source](#build-from-source) +- [Docs](#docs) +- [Contributing](#contributing) +- [License](#license) + +## Features + +### Structure & navigation +- Layout tree: file → header → load commands → sections / symbols / link-edit data. +- Search box that filters the layout tree by node name **and** matches the contents of tables you have already opened. +- Hex view stays in sync with the selected node — jump from any table row to the exact bytes. + +### Apple binary internals +- Load commands, sections, symbol & string tables, relocations, indirect symbols, function starts, data-in-code. +- **Code signing**: parses the embedded-signature SuperBlob (Code Directory, Requirements, CMS) and decodes the **entitlements** plist. +- **Objective-C** metadata: classes, methods, ivars, properties, and protocols. +- **Swift** semantic graph over the `__swift5_*` sections. +- **dyld info**: rebase / bind / lazy-bind / exports trie and chained-fixups structures. + +### Code & cross-references +- Optional [Capstone](https://www.capstone-engine.org/) disassembly of `__TEXT,__text` (arm64, x86_64, arm, i386). +- Xref report that resolves call / jump targets and ties them back to symbols. + +### dyld shared cache +- List images, extract a single image or all of them, and drill straight into an extracted image. + +### Productivity & UX +- Parsing runs **off the UI thread**, so opening a large binary or a multi-gigabyte shared cache keeps the window responsive. +- Tables: per-column filter, copy row(s), CSV export, keyboard navigation. +- Built-in update check with reminder options. + +### Automation +- Headless `--cli` mode prints the full analysis as text or **stable JSON** — ideal for scripting, diffing, and CI. + +### Built for suspicious files +The parser is bounds- and alignment-checked throughout — LEB128 streams, load-command walking, +string tables, and code-signature blobs — and is covered by a malformed-input crash-regression +suite (run against truncated and fuzzed binaries). Opening a hostile or corrupted file degrades +gracefully instead of crashing. + +## Supported formats +| Format | Notes | +| --- | --- | +| Mach-O | 32-bit and 64-bit | +| Fat / Universal | Multiple architecture slices | +| Static archive | `.a` with Mach-O members | +| dyld shared cache | List, extract, and inspect images | + +## Install + +### macOS +- Download the latest release: +- Or install via Homebrew: ```bash brew update && brew tap everettjf/homebrew-tap && brew install --cask machoexplorer ``` -## Quick Start -1. Launch MachOExplorer. -2. Open a sample binary (`sample/simple` or `sample/complex`) or your own Mach-O file. -3. Navigate from `Layout` tree to sections/symbols/disassembly views. +### Linux / Windows +Prebuilt macOS releases are published on GitHub. On Linux and Windows, build from source +(see [Build from source](#build-from-source)). The Linux build and the full regression suite +run in CI on every change. + +## Quick start +1. Launch MachOExplorer, or open a file directly: `MachOExplorer `. +2. Open a bundled sample (`sample/simple`, `sample/complex`) or your own binary. +3. Walk the **Layout** tree; type in the search box to jump to a section, symbol, or value; select a + node to see its table and the matching bytes in the hex view. -## CLI Analysis Mode (No GUI) -Run full analysis in command-line mode and output to stdout or file: +## CLI / automation mode +Run a full analysis without the GUI and write the result to stdout or a file: ```bash ./build/MachOExplorer --cli sample/simple @@ -44,29 +99,56 @@ Run full analysis in command-line mode and output to stdout or file: ``` Common options: -- `--format text|json` output format (default `text`) -- `--output ` write analysis output to file -- `--max-rows ` limit rows per table (`0` means unlimited) -- `--max-depth ` limit tree depth (`0` means unlimited) -- `--root-path ` export only one matching analysis subtree -- `--name-filter ` keep nodes whose display names match the text -- `--table-mode ` control table payload size -- `--include-empty` include empty nodes -The JSON output is automation-friendly and now includes stable metadata such as `schemaVersion`, `summary`, node `path` / `kind` / `childIndex`, and row `cells` / `rowIndex`. +| Option | Description | +| --- | --- | +| `--format text\|json` | Output format (default `text`) | +| `--output ` | Write analysis output to a file | +| `--max-rows ` | Limit rows per table (`0` = unlimited) | +| `--max-depth ` | Limit tree depth (`0` = unlimited) | +| `--root-path ` | Export only one matching analysis subtree | +| `--name-filter ` | Keep nodes whose display names match the text | +| `--table-mode ` | Control table payload size | +| `--include-empty` | Include empty nodes | + +The JSON output is automation-friendly and stable: it includes `schemaVersion`, a `summary`, node +`path` / `kind` / `childIndex`, and row `cells` / `rowIndex`. String values are sanitized to valid +UTF-8 so output stays well-formed even on malformed input. See [CLI.md](CLI.md) for the full guide. + +## Build from source +Requirements: CMake ≥ 3.16, Qt 6 (Core, Gui, Widgets, Network, Concurrent), a C++14 compiler, and +optionally [Capstone](https://www.capstone-engine.org/) for disassembly. + +```bash +# macOS +cmake -S src -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="$HOME/Qt/6.x.x/macos" +cmake --build build -j8 + +# Linux (Debian/Ubuntu deps: qt6-base-dev libgl1-mesa-dev libcapstone-dev) +./build_linux.sh # or: cmake -S src -B build && cmake --build build -j"$(nproc)" + +# Windows +cmake -S src -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="C:/Qt/6.x.x/msvcXXXX_64" +cmake --build build --config Release +``` + +Run `./build/MachOExplorer` (or `MachOExplorer.app` on macOS). See [DEVELOP.md](DEVELOP.md) for the +full developer, testing, and release workflow. ## Docs -- Developer guide (build/test/release): [DEVELOP.md](DEVELOP.md) -- Packaging notes: [docs/release_packaging.md](docs/release_packaging.md) +- Developer guide (build / test / release): [DEVELOP.md](DEVELOP.md) - CLI guide: [CLI.md](CLI.md) +- Packaging notes: [docs/release_packaging.md](docs/release_packaging.md) ## Contributing -Issues and PRs are welcome: +Issues and pull requests are welcome: - Project: - Issues: +Before opening a PR, please build the project and run `tests/regression/run_all.sh`. + ## License MIT. See [LICENSE](LICENSE). ## Star History -[![Star History Chart](https://api.star-history.com/svg?repos=everettjf/MachOExplorer&type=Date)](https://star-history.com/#everettjf/MachOExplorer&Date) +[![Star History Chart](https://api.star-history.com/svg?repos=everettjf/MachOExplorer)](https://star-history.com/#everettjf/MachOExplorer) diff --git a/README.zh-CN.md b/README.zh-CN.md index 50bde83..76cb28a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,42 +1,94 @@ # MachOExplorer -一个聚焦于 Mach-O 生态的桌面分析工具，支持 Mach-O、Archive 与 dyld shared cache。 +> 一个聚焦 Apple 二进制的桌面分析工具——支持 Mach-O、Fat/Universal、`.a` Archive 与 dyld shared cache，为逆向与二进制审查而生。 语言：简体中文 | [English](README.md) ![MachOExplorer 截图](image/screenshot.png) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) - -## 项目特点 -- 一个界面查看 Mach-O / Fat Mach-O / `.a` Archive / dyld shared cache。 -- 从结构到代码快速钻取：section、symbol、反汇编、xref。 -- 面向 Apple 现代二进制：ObjC 元数据、Swift 元数据、dyld exports/fixups。 -- 解析边界校验与回归测试完善，处理异常样本更稳。 - -## 主要功能 -- Load commands、sections、symbols、relocations、strings 等视图。 -- 可选 Capstone 支持 `__TEXT,__text` 反汇编。 -- Swift 语义图（`__swift5_*`）与 ObjC 元数据浏览。 -- dyld shared cache 镜像列表/提取/一键钻取分析。 -- 表格交互增强：筛选、复制、CSV 导出、键盘导航。 -- 内置更新检查与提醒策略。 - -## 安装（macOS） -- 最新版本： -- Homebrew： +[![Linux CI](https://github.com/everettjf/MachOExplorer/actions/workflows/linux.yml/badge.svg)](https://github.com/everettjf/MachOExplorer/actions/workflows/linux.yml) +[![Latest Release](https://img.shields.io/github/v/release/everettjf/MachOExplorer)](https://github.com/everettjf/MachOExplorer/releases/latest) +[![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#安装) + +MachOExplorer 把一个晦涩的 Mach-O 文件变成可导航的树。打开一个二进制，从文件结构一路钻取到 +load command、section、符号、反汇编，以及 Apple 特有的元数据（Objective-C、Swift、代码签名）—— +在一个窗口里完成，也可以完全用命令行脚本化。 + +## 目录 +- [功能](#功能) +- [支持的格式](#支持的格式) +- [安装](#安装) +- [快速开始](#快速开始) +- [CLI / 自动化模式](#cli--自动化模式) +- [从源码构建](#从源码构建) +- [文档](#文档) +- [贡献](#贡献) +- [许可证](#许可证) + +## 功能 + +### 结构与导航 +- Layout 树：文件 → header → load commands → section / 符号 / link-edit 数据。 +- 搜索框：按节点名过滤布局树，**并且**能匹配你已打开过的表格里的内容。 +- Hex 视图与所选节点联动——从任意表格行跳到对应字节。 + +### Apple 二进制内部结构 +- Load commands、section、符号表与字符串表、重定位、间接符号、function starts、data-in-code。 +- **代码签名**：解析 embedded-signature SuperBlob（Code Directory、Requirements、CMS），并解码 **entitlements** plist。 +- **Objective-C** 元数据：类、方法、ivar、属性、协议。 +- **Swift** 语义图（基于 `__swift5_*` 段）。 +- **dyld 信息**：rebase / bind / lazy-bind / exports trie 与 chained-fixups 结构。 + +### 代码与交叉引用 +- 可选 [Capstone](https://www.capstone-engine.org/) 反汇编 `__TEXT,__text`（arm64、x86_64、arm、i386）。 +- Xref 报告：解析 call / jump 目标并关联回符号。 + +### dyld shared cache +- 列出镜像、提取单个或全部镜像，并直接钻入已提取的镜像分析。 + +### 体验与效率 +- 解析在 **UI 线程之外**进行，打开大型二进制或数 GB 的 shared cache 也不卡界面。 +- 表格：按列筛选、复制行、CSV 导出、键盘导航。 +- 内置更新检查与提醒。 + +### 自动化 +- 无界面的 `--cli` 模式以文本或**稳定 JSON** 输出完整分析——适合脚本、diff 与 CI。 + +### 为可疑文件而设计 +解析器全程做了边界与对齐校验——LEB128 流、load command 遍历、字符串表、代码签名 blob—— +并有针对畸形输入的崩溃回归套件（对截断和模糊后的二进制运行）。打开恶意或损坏文件时， +程序会优雅地降级而不是崩溃。 + +## 支持的格式 +| 格式 | 说明 | +| --- | --- | +| Mach-O | 32 位与 64 位 | +| Fat / Universal | 多架构 slice | +| 静态库 | 含 Mach-O 成员的 `.a` | +| dyld shared cache | 列出、提取并检视镜像 | + +## 安装 + +### macOS +- 下载最新版本： +- 或通过 Homebrew 安装： ```bash brew update && brew tap everettjf/homebrew-tap && brew install --cask machoexplorer ``` +### Linux / Windows +GitHub 上提供 macOS 预编译版本。在 Linux 与 Windows 上请从源码构建（见 +[从源码构建](#从源码构建)）。Linux 构建与完整回归套件会在每次改动时由 CI 运行。 + ## 快速开始 -1. 启动 MachOExplorer。 -2. 打开示例文件（`sample/simple` 或 `sample/complex`）或你自己的 Mach-O。 -3. 在左侧 Layout 树中进入 section/symbol/disassembly 等视图。 +1. 启动 MachOExplorer，或直接打开文件：`MachOExplorer <路径>`。 +2. 打开内置示例（`sample/simple`、`sample/complex`）或你自己的二进制。 +3. 浏览 **Layout** 树；在搜索框输入即可跳到某个 section、符号或数值；选中节点即可在 Hex 视图看到对应字节。 -## CLI 分析模式（无界面） -可直接以命令行方式执行完整分析，并输出到终端或文件： +## CLI / 自动化模式 +无需界面即可执行完整分析，并输出到终端或文件： ```bash ./build/MachOExplorer --cli sample/simple @@ -44,29 +96,56 @@ brew update && brew tap everettjf/homebrew-tap && brew install --cask machoexplo ``` 常用参数： -- `--format text|json` 输出格式（默认 `text`） -- `--output ` 输出到文件 -- `--max-rows ` 每个表最多输出 N 行（`0` 表示不限制） -- `--max-depth ` 限制分析树深度（`0` 表示不限制） -- `--root-path ` 仅导出某个分析子树 -- `--name-filter ` 仅保留名称匹配的节点 -- `--table-mode ` 控制表格载荷大小 -- `--include-empty` 包含空节点 -JSON 输出现在包含更稳定的自动化字段：`schemaVersion`、`summary`、节点级 `path` / `kind` / `childIndex`，以及表格行级 `cells` / `rowIndex`。 +| 参数 | 说明 | +| --- | --- | +| `--format text\|json` | 输出格式（默认 `text`） | +| `--output ` | 输出到文件 | +| `--max-rows ` | 每个表最多输出 N 行（`0` 表示不限制） | +| `--max-depth ` | 限制分析树深度（`0` 表示不限制） | +| `--root-path ` | 仅导出某个分析子树 | +| `--name-filter ` | 仅保留名称匹配的节点 | +| `--table-mode ` | 控制表格载荷大小 | +| `--include-empty` | 包含空节点 | + +JSON 输出便于自动化且稳定：包含 `schemaVersion`、`summary`、节点级 `path` / `kind` / `childIndex`， +以及行级 `cells` / `rowIndex`；所有字符串都会被净化为合法 UTF-8，即使输入畸形也能保证输出良构。 +完整说明见 [CLI.zh-CN.md](CLI.zh-CN.md)。 + +## 从源码构建 +依赖：CMake ≥ 3.16、Qt 6（Core、Gui、Widgets、Network、Concurrent）、C++14 编译器， +反汇编功能可选 [Capstone](https://www.capstone-engine.org/)。 + +```bash +# macOS +cmake -S src -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="$HOME/Qt/6.x.x/macos" +cmake --build build -j8 + +# Linux（Debian/Ubuntu 依赖：qt6-base-dev libgl1-mesa-dev libcapstone-dev） +./build_linux.sh # 或：cmake -S src -B build && cmake --build build -j"$(nproc)" + +# Windows +cmake -S src -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="C:/Qt/6.x.x/msvcXXXX_64" +cmake --build build --config Release +``` + +运行 `./build/MachOExplorer`（macOS 上为 `MachOExplorer.app`）。完整的开发、测试与发布流程见 +[DEVELOP.md](DEVELOP.md)。 ## 文档 -- 开发文档（构建/测试/发布）：[DEVELOP.md](DEVELOP.md) -- 打包说明：[docs/release_packaging.md](docs/release_packaging.md) +- 开发文档（构建 / 测试 / 发布）：[DEVELOP.md](DEVELOP.md) - CLI 文档：[CLI.zh-CN.md](CLI.zh-CN.md) +- 打包说明：[docs/release_packaging.md](docs/release_packaging.md) ## 贡献 欢迎提交 Issue 和 PR： - 项目地址： - 问题反馈： +提交 PR 前，请先构建项目并运行 `tests/regression/run_all.sh`。 + ## 许可证 MIT，详见 [LICENSE](LICENSE)。 ## Star History -[![Star History Chart](https://api.star-history.com/svg?repos=everettjf/MachOExplorer&type=Date)](https://star-history.com/#everettjf/MachOExplorer&Date) +[![Star History Chart](https://api.star-history.com/svg?repos=everettjf/MachOExplorer)](https://star-history.com/#everettjf/MachOExplorer)