HendrikReh/hopper_reverse_toolkit

# Hopper Reverse Toolkit **版本**: 1.5.0 **最后更新**: 2026-03-15 **维护者**: 本工具包将 [Hopper](https://www.hopperapp.com/) 分析转化为可复用的工件，用于架构恢复、安全分类、prompt 驱动的逆向工程以及注释回写。 ## 目录 - [关于 Hopper](#about-hopper) - [包含文件与版本](#included-files-and-versions) - [快速开始](#quick-start) - [工件指南](#artifact-guide) - [推荐工作流](#recommended-workflow) - [Prompt 包](#prompt-pack) - [在 Hopper 中应用注释](#applying-annotations-inside-hopper) - [文档](#documentation) - [注意事项](#notes) ## 关于 Hopper [Hopper](https://www.hopperapp.com/) 是一款原生 macOS 反汇编器和逆向工程工具，用于分析可执行代码。它支持 Mach-O、ARM 和 Windows 二进制文件，并提供： - 汇编反汇编以及反编译为类 C 伪代码 - 可导出 PDF 的交互式控制流图 - Objective-C 选择器提取和 Swift 名称还原 (demangling) - LLDB 和 GDB 调试器集成 - 用于自动化的 Python 脚本 API - 用于自定义加载器和 CPU 后端的可扩展 SDK - 通过 MCP 服务器进行的 AI 辅助分析 Hopper 需要 macOS 12.4 或更高版本。本工具包针对 Hopper v6 Python 脚本 API。 有关工具包工作流之外的 Hopper 脚本编写细节，请参阅 [`docs/hopper_6_2_1_python_api.md`](docs/hopper_6_2_1_python_api.md)。 ## 包含文件与版本 | 文件 | 版本 | 用途 | |---|---:|---| | `hopper_export_metadata.py` | 1.5.0 | 从 Hopper 导出段 (segments)、节 (sections)、字符串、过程、局部变量、标签和 CFG 元数据 | | `hopper_export_callgraph.py` | 1.5.0 | 导出包含调用点和调用类型元数据的过程调用图 | | `hopper_export_rust_analysis.py` | 1.5.0 | 导出面向 Rust 的函数数据，包括名称还原、签名和调用元数据 | | `hopper_apply_annotations.py` | 1.5.0 | 将标签、注释、标签、颜色和书签应用回当前的 Hopper 文档 | | `enrich_hopper_exports.py` | 1.5.0 | 将 Hopper 导出内容合并为富化 JSON，同时保留更丰富的调用元数据 | | `docs/hopper_6_2_1_python_api.md` | n/a | Hopper 6.2.1 Python 脚本编写的实用指南及参考 | | `export_graphml.py` | 1.4.0 | 将 `*.callgraph.json` 转换为 GraphML | | `generate_mermaid.py` | 1.4.0 | 生成子系统、热点和调用流 Mermaid 图表 | | `json_to_mermaid_architecture.py` | 1.4.0 | 合成更高层级的 Mermaid 架构图 | | `generate_c4_architecture.py` | 1.4.0 | 从富化 JSON 生成 C4 风格的 Mermaid 和 PlantUML 图表 | | `prompt_pack/` | 1.5.0 | 用于架构重构、安全分类、流程映射和注释生成的可复用 prompt | | `CHANGELOG.md` | n/a | 变更历史 | | `README.md` | n/a | 本文档 | ## 快速开始 ### 1. 在 Hopper 内部导出 通过 `Scripts → Run Script` 运行以下脚本： 1. `hopper_export_metadata.py` 2. `hopper_export_callgraph.py` 3. `hopper_export_rust_analysis.py`（可选） 在可执行文件旁生成的典型输出： - `.hopper_export.json` - `.callgraph.json` - `.analysis.json` 导出脚本会在收集数据前等待 Hopper 后台分析完成，因此您无需手动暂停以等待分析队列排空。 ### 2. 在 Hopper 外部进行富化与渲染 ``` python enrich_hopper_exports.py /path/to/binary.hopper_export.json /path/to/binary.callgraph.json --out-json enriched_analysis.json --out-md architecture_summary.md python generate_mermaid.py enriched_analysis.json --subsystems subsystems.mmd --hotspots hotspots.mmd --callflow callflow.mmd python json_to_mermaid_architecture.py enriched_analysis.json --out architecture_synthesized.mmd python generate_c4_architecture.py enriched_analysis.json --mermaid-out c4_architecture.mmd --plantuml-out c4_architecture.puml python export_graphml.py /path/to/binary.callgraph.json /path/to/binary.graphml ``` ### 3. 使用 Prompt 包进行分析 结合生成的 JSON、摘要、Mermaid、GraphML 和可选的 Rust 分析工件，使用 `prompt_pack/` 中的模板。 ### 4. 将注释回写到 Hopper 在 Hopper 内部运行 `hopper_apply_annotations.py`，并传入手动生成或通过 `prompt_pack/06_annotation_candidates.md` 生成的 JSON 载荷。 如果未传递文件路径，脚本将打开一个 Hopper 文件选择器。 ## 工件指南 | 工件 | 生成者 | 内容 | 典型下游用途 | |---|---|---|---| | `*.hopper_export.json` | `hopper_export_metadata.py` | 文档信息、段、节、字符串、符号、过程、局部变量、标签和 CFG 基础信息 | 用于富化和 prompt 驱动分析的主要结构导出 | | `*.callgraph.json` | `hopper_export_callgraph.py` | 过程及过程间边，包含调用点和调用类型元数据 | GraphML 导出、富化、流程映射、热点分类 | | `*.analysis.json` | `hopper_export_rust_analysis.py` | 面向 Rust 的函数元数据、还原后的名称、签名、标签计数和调用元数据 | Rust 密集型二进制文件、crate 推断、框架与应用分离 | | `enriched_analysis.json` | `enrich_hopper_exports.py` | 合并后的函数记录，包含子系统标签、度数、调用者/被调用者预览以及保留的调用元数据 | Mermaid 生成、prompt 包、架构合成 | | `architecture_summary.md` | `enrich_hopper_exports.py` | 人类可读的子系统分布和排名函数列表 | 分析师简报、prompt 上下文、快速分类 | | `*.mmd` / `*.puml` | Mermaid/C4 生成器 | 可视化架构和调用流图 | 审查、文档、prompt 上下文 | | `*.graphml` | `export_graphml.py` | GraphML 格式的调用图 | 外部图工具 | ## 推荐工作流 ### 在 Hopper 内部 - 从 `hopper_export_metadata.py` 和 `hopper_export_callgraph.py` 开始。 - 当符号质量或 crate 推断至关重要时，使用 `hopper_export_rust_analysis.py`。 - 仅在审查注释载荷后使用 `hopper_apply_annotations.py`；它会直接写入打开的文档。 ### 在 Hopper 外部 - 将 `enriched_analysis.json` 视为主要交接工件。 - 在富化之后而非之前生成 Mermaid 或 C4 视图。 - 当您希望使用外部图工具而非 prompt 驱动分析时，使用 GraphML。 ## Prompt 包 `prompt_pack/` 旨在与 LLM 及本套件生成的 Hopper 工件配合使用，采用复制粘贴方式。 推荐的 prompt 选择： - `01_architecture_reconstruction.md`：初步系统架构和信任边界 - `02_security_hotspots.md`：可能的认证、加密、解析器、存储和网络热点 - `03_request_flow_mapping.md`：从入口到效果或从请求到响应的流程重构 - `04_app_vs_framework.md`：从框架噪声中分离出可能属于应用的逻辑 - `05_c4_reconstruction.md`：叙述性的 C4 风格架构描述 - `06_annotation_candidates.md`：用于 `hopper_apply_annotations.py` 的保守 JSON 注释生成 ## 在 Hopper 中应用注释 `hopper_apply_annotations.py` 接受包含以下任意顶层键的 JSON 载荷： - `labels` - `comments` - `inline_comments` - `tags` - `colors` - `bookmarks` 载荷示例： ``` { "labels": [{"address": "0x1000", "name": "entry_main"}], "comments": [{"address": "0x1000", "comment": "Recovered entry point"}], "inline_comments": [{"address": "0x1004", "comment": "Calls helper"}], "tags": [{"address": "0x1000", "tag": "review"}], "colors": [{"address": "0x1000", "color": "#FF112233"}], "bookmarks": [{"address": "0x1000", "name": "main entry"}] } ``` 请使用保守的载荷。在 Hopper 中错误的标签或注释比没有注释更具破坏性。 ## 文档 `docs/` 目录包含工具包中每个脚本和模块的详细文档。 ### 脚本参考 | 文档 | 涵盖内容 | |---|---| | [`hopper_export_metadata.md`](docs/hopper_export_metadata.md) | 结构元数据导出 —— 段、过程、伪代码、基本块 | | [`hopper_export_callgraph.md`](docs/hopper_export_callgraph.md) | 带有调用点和调用类型元数据的调用图导出 | | [`hopper_export_rust_analysis.md`](docs/hopper_export_rust_analysis.md) | 特定于 Rust 的导出，包含名称还原和 crate 推断 | | [`hopper_apply_annotations.md`](docs/hopper_apply_annotations.md) | 注释回写 —— 标签、注释、标签、颜色、书签 | | [`enrich_hopper_exports.md`](docs/enrich_hopper_exports.md) | 合并和富化，包含有趣度评分和子系统分类 | | [`export_graphml.md`](docs/export_graphml.md) | Callgraph JSON 到 GraphML 的转换 | | [`generate_mermaid.md`](docs/generate_mermaid.md) | 子系统、热点和调用流 Mermaid 图表 | | [`json_to_mermaid_architecture.md`](docs/json_to_mermaid_architecture.md) | 高层合成的架构 Mermaid 图 | | [`generate_c4_architecture.md`](docs/generate_c4_architecture.md) | C4 风格的 Mermaid 和 PlantUML 图表 | | [`_hopper_utils.md`](docs/_hopper_utils.md) | 共享工具库 —— 所有辅助函数、子系统 token、调用类型代码 | ### Hopper 脚本参考 | 文档 | 涵盖内容 | |---|---| | [`hopper_6_2_1_python_api.md`](docs/hopper_6_2_1_python_api.md) | Hopper 6.2.1 Python 脚本 API 的实用指南及参考 | ## 注意事项 - Hopper 的 Python API 在不同版本间存在差异；本套件针对文档中公开的段、过程、基本块和调用引用 API。 - `rustfilt` 是可选的，但建议用于 Rust 二进制文件。 - 图表输出是启发式的起点，而非既定事实。 - 更丰富的导出保留了调用点元数据、局部变量、字符串、标签和基本块关系，以便下游自动化使用。

标签：AI辅助分析, API集成, Blacksmith Consulting, C4模型, CFG, CI/CD安全, CTF工具, DAST, DNS 反向解析, DNS 解析, GPT, GraphML, Homebrew安装, Hopper Disassembler, IP 地址批量处理, JSON导出, Llama, LLDB调试, Mach-O, macOS安全, Mermaid图表, Rust分析, Security, Security Triage, TLS抓取, Wayback Machine, 二进制分析, 二进制安全, 云安全监控, 云安全运维, 云资产清单, 代码可视化, 凭据导出, 反汇编, 可观测性, 大模型提示词, 恶意软件分析, 控制流图, 数据增强, 架构恢复, 注释回填, 漏洞搜索, 漏洞管理, 网络安全审计, 调用图, 软件安全, 逆向工具, 逆向工程, 静态分析