Dryxio/auto-re-agent

# auto-re-agent [](https://pypi.org/project/auto-re-agent/) [](https://pypi.org/project/auto-re-agent/) [](https://github.com/Dryxio/auto-re-agent/actions/workflows/ci.yml) [](LICENSE) `auto-re-agent` 是一个开源的 AI 逆向工程 agent，它使用 Ghidra 和 LLM（包括 Claude、Codex 和 OpenAI 兼容模型）来重构 并验证编译后二进制文件中的 C/C++ 函数。它在一个自主工作流中结合了独立的 reverser/checker 模型、agent 式的证据收集、候选项构建与测试 门控、结构验证以及 parity 分析。 0.2 版本之前的原始演示：[YouTube](https://youtu.be/zBQJYMKmwAs?si=emi1kDsJ81-2-tc3) ## 功能说明 ``` re-agent reverse --class CTrain │ ├── Configuration (YAML + supported environment overrides + CLI flags) ├── Function selection (dependency-order | easiest-first | high-impact) ├── Source and binary context │ ├── decompile, xrefs, structs, enums, vtables, globals, and strings │ └── normalized high P-code, CFG, assembly, and nearby project source ├── Reverser → checker → fix loop (bounded rounds and investigations) ├── Conservative structural verifier ├── Candidate overlay │ └── configured build, test, and runtime gates ├── Candidate parity gate (GREEN | YELLOW | RED) └── Reports, per-round logs, session history, and knowledge graph ``` 该工具生成候选的 C/C++ 实现；它不会自动修补 原始源码树。一次成功的逆向可能需要满足四个 独立条件： 1. LLM checker 返回 `PASS`； 2. 客观验证器未发现强烈的结构不匹配； 3. 候选验证满足配置的验收策略； 4. parity 未被配置的 RED/YELLOW 策略阻止。 这是保守的验证，而不是语义等价性的证明。 ## 环境要求 - Python 3.10+ - Git，用于当前的源码安装 - Ghidra 以及一个配置好的 [ghidra-ai-bridge](https://github.com/Dryxio/ghidra-ai-bridge) - 至少设置一个 LLM： - Claude API：`ANTHROPIC_API_KEY` - OpenAI 兼容 API：`OPENAI_API_KEY` - Claude CLI：一个经过身份验证的本地 `claude` 命令 - Codex CLI：一个经过身份验证的本地 `codex` 命令 ## 安装说明 从 PyPI 安装该 agent 及其 Ghidra 查询 bridge： ``` python3 -m pip install --upgrade "auto-re-agent[ghidra-bridge]>=0.2.0" ``` 对于 headless Ghidra 导出，请安装带有 PyGhidra 扩展的 bridge： ``` python3 -m pip install --upgrade "auto-re-agent[headless]>=0.2.0" ``` 如果要直接从 GitHub 安装最新的开发版本： ``` python3 -m pip install --upgrade \ "ghidra-ai-bridge @ git+https://github.com/Dryxio/ghidra-ai-bridge.git@main" \ "auto-re-agent @ git+https://github.com/Dryxio/auto-re-agent.git@main" ``` ## 设置 Ghidra 证据 在你要进行逆向的项目中运行以下命令： ``` # 创建 ghidra-bridge.yaml，然后编辑其 Ghidra 项目/程序路径 ghidra-bridge init # 需要 bridge headless extra 和本地 Ghidra 安装 ghidra-bridge export all # 当有逆向的源码/hook 模式时可用，可选但推荐 ghidra-bridge build-map # 确认 exports 和配置可见 ghidra-bridge info ``` 请参阅 [bridge 文档](https://github.com/Dryxio/ghidra-ai-bridge) 了解其 Ghidra、导出和 source-map 配置。 ## 快速开始 在目标项目中创建配置： ``` # 推荐的 portable 默认值 re-agent init --profile generic-cpp # 其他可用的 profiles # re-agent init --profile windows-x64 # re-agent init --profile gta-reversed # re-agent init --profile openrct2 ``` 在不使用 `--profile` 的情况下运行 `re-agent init` 将保留原始的 GTA-reversed 默认设置。对于新项目，建议指定明确的 profile。 然后编辑 `re-agent.yaml`。至少需要选择一个 LLM，将 backend 指向 已安装的 bridge 可执行文件，设置源码路径，并配置验证。 ``` llm: provider: claude-cli model: sonnet # 可选：使用不同的 provider/model 进行检查。 agents: checker: provider: codex model: gpt-5.4 backend: type: ghidra-bridge cli_path: ghidra-bridge project_profile: name: generic-cpp language_standard: C++20 source_root: src hooks_csv: null orchestrator: max_review_rounds: 4 investigation_enabled: true max_investigations: 8 selection_strategy: dependency-order max_attempts_per_function: 3 validation: enabled: true copy_project: true project_root: . build_commands: - cmake -S . -B build - cmake --build build test_commands: - ctest --test-dir build --output-on-failure require_build: true require_tests: true require_verified: true # This explicitly attests that the project-owned shell commands above are # meaningful validation gates. Leave false for untrusted commands. trust_configured_commands: true keep_project_copy: false parity_fail_on_red: true parity_fail_on_yellow: false ``` 验证被刻意设置得很严格：在生成的默认配置下，没有任何配置的 命令会产生 `UNKNOWN`，并且 `require_verified: true` 会拒绝该结果。 如果要在不进行构建验证的情况下进行探索，请显式设置 `validation.enabled: false`；此类结果未经过构建验证。 在启动类级别的运行之前，先从单个函数开始： ``` re-agent reverse --address 0x401000 re-agent reverse --class CTrain --max-functions 10 re-agent status ``` ## LLM 提供商 ### Claude API ``` llm: provider: claude model: claude-sonnet-4-5-20250929 ``` 设置 `ANTHROPIC_API_KEY` 或 `RE_AGENT_LLM_API_KEY`。 ### Claude CLI 首先验证本地 Claude Code CLI，然后进行配置： ``` llm: provider: claude-cli model: sonnet cli_path: claude effort: high max_budget_usd: 1.0 ``` Claude CLI 支持真实的会话恢复，并会报告使用量/成本元数据。即使 其 auth-status 命令报告了活动会话，过期的 CLI 登录 可能仍需要重新进行身份验证。 ### OpenAI 兼容 API ``` llm: provider: openai # or openai-compat model: your-model base_url: https://your-endpoint.example/v1 # optional ``` 设置 `OPENAI_API_KEY` 或 `RE_AGENT_LLM_API_KEY`。 ### Codex CLI ``` llm: provider: codex model: gpt-5.4 ``` Codex 使用经过身份验证的本地 `codex exec` 命令。CLI 提供商的 `max_tokens` 值是规划允许量，而不是硬性输出限制。 省略 `agents.reverser` 或 `agents.checker` 可以为该角色复用顶层的 `llm` 配置。角色块是完整的角色配置， 而不是与 `llm` 进行逐字段合并。 ## 证据与调查 在 backend 支持的情况下，reverser 会预加载有界证据包， 并可以请求额外的只读操作： - `decompile`、`xrefs_from` 和 `xrefs_to` - `struct` 和 `enum` - `vtable`、`global` 和 `strings` - `context`、规范化的 `pcode` 和 `cfg` 证据包数据也会被摄取到 `reports/re-agent/knowledge-graph.json` 中，将函数、调用、全局变量 和字符串连接起来。不支持的 bridge 功能会优雅降级。 ## 候选验证 生成的代码会被写入 overlay。在设置 `copy_project: true` 时，项目 会被复制到一个临时目录，候选项会在那里替换匹配的函数体， 命令将从该副本运行。`.git`、`.venv`、`build`、`reports` 和 Python 缓存文件不会被复制。除非设置 `keep_project_copy: true`，否则临时的项目副本将被删除。 命令可以使用： - `{candidate_file}`、`{overlay_root}` 和 `{source_file}` 占位符； - `RE_AGENT_CANDIDATE_FILE`、`RE_AGENT_OVERLAY_ROOT` 和 `RE_AGENT_SOURCE_FILE` 环境变量。 配置的构建/测试/运行时命令是项目所有的任意 shell 命令。agent 无法仅从它们的文本证明它们确实验证了 候选项，因此只有当显式设置 `trust_configured_commands: true` 时，它们才会成为验收证据。 如果多个 C++ 定义匹配一个重载方法，且无法对源码进行 明确区分，则 overlay 将被拒绝，而不是随意替换某个函数体。 ## 验证与 parity 客观验证器在每一轮审查中运行。它会将生成的代码 与可用的 decompile、assembly、CFG 和规范化的 high P-code 证据进行比较。 它仅在存在强烈不匹配时返回 `FAIL`；证据不足时返回 `UNKNOWN`。 逆向 pipeline 会对生成的候选函数体运行 11 个内置的启发式 parity 信号。 默认情况下，RED 是阻断性的；可以通过 `validation.parity_fail_on_yellow` 将 YELLOW 设置为阻断性。 独立命令则有所不同：`re-agent parity` 会分析现有源码树中的函数。 它还支持语义规则文件和手动检查 覆盖。除非使用 `--strict-exit`，否则即使在 RED 情况下，其进程退出代码 仍保持为零。 11 个内置信号包括： | 信号 | 级别 | 描述 | |---|---|---| | 缺少源码 | RED | 未找到源码主体 | | Stub 标记 | RED | 源码包含配置的 stub 标记 | | 简单 stub | RED | 主体小且大量调用插件，没有控制流 | | ASM 庞大，源码极小 | RED | 反汇编代码庞大，而源码主体非常小 | | 大量调用插件 | YELLOW | 插件调用占据了源码主体的主要部分 | | 主体过短 | YELLOW | 主体少于六行 | | 调用次数少 | YELLOW | 反编译的被调用者数量远超源码调用数量 | | FP 敏感 | YELLOW | 汇编中包含 FP 敏感操作，但源码中没有数学 token | | 调用次数不匹配 | YELLOW | 源码与汇编的调用次数差异超出了配置的阈值 | | NaN 逻辑 | YELLOW | 反编译显示存在源码中缺失的 NaN 敏感行为 | | 内联 wrapper | INFO | 源码直接转发给内部实现 | 该信号集在 `0.2.0` 版本中是固定的；配置开放了特定的阈值、 内联 wrapper 行为、语义规则和手动覆盖，而不是为每个 信号提供单独的开关。 ## CLI 参考 全局选项必须位于子命令之前，例如 `re-agent --config custom.yaml status`。 | 命令 | 用途 | |---|---| | `re-agent init --profile generic-cpp` | 从 profile 创建 `re-agent.yaml` | | `re-agent reverse --address ADDR` | 逆向单个函数 | | `re-agent reverse --class CLASS --max-functions N` | 逆向一个有界类批次 | | `re-agent reverse --class CLASS --dry-run` | 在不调用 LLM 的情况下显示目标计划 | | `re-agent reverse ... --max-rounds N --skip-parity` | 覆盖循环/parity 行为 | | `re-agent parity --address ADDR --strict-exit` | 分析现有的源码函数 | | `re-agent parity --filter REGEX --limit N --output report.json` | 过滤并导出 parity 结果 | | `re-agent parity ... --skip-ghidra` | 仅运行源码 parity 信号 | | `re-agent status --class CLASS --format text` | 显示会话进度 | | `re-agent estimate --address ADDR` | 估算单个函数 | | `re-agent estimate --class CLASS --limit N` | 估算一个类批次 | 使用 `re-agent --help` 获取准确的选项列表。 ## 配置优先级 有效顺序为 CLI 运行时覆盖、支持的环境变量、 `re-agent.yaml`，然后是 dataclass 默认值。当前支持的环境 变量包括： - `RE_AGENT_LLM_PROVIDER` - `RE_AGENT_LLM_API_KEY` - `RE_AGENT_LLM_MODEL` - `RE_AGENT_LLM_BASE_URL` - `RE_AGENT_BACKEND_CLI_PATH` - `RE_AGENT_BACKEND_TIMEOUT` 特定于角色的 `agents.*` 配置、验证、项目 profile、parity 和输出路径应在 YAML 中配置。 完整的 schema 请参阅 [docs/configuration.md](docs/configuration.md)。 ## Profile - `generic-cpp`：通用的 C/C++ 默认配置 - `windows-x64`：面向 Microsoft x64 的提示词规则 - `gta-reversed`：GTA-reversed 的 hook、stub、源码路径和项目规则 - `openrct2`：面向 OpenRCT2 的 hook/stub 模式 Profile 用于初始化项目配置；它们不会替换 bridge 导出 或特定于项目的验证命令。 ## 输出 默认产出物包括： - `reports/re-agent/code/`：每个函数最终生成的代码 - `reports/re-agent/logs/`：每轮 reverser/checker 的提示词、响应和提供商元数据 - `reports/re-agent/candidates/`：非隔离的候选 overlay - `reports/re-agent/knowledge-graph.json`：持久化证据图 - `re-agent-progress.json`：每个函数的当前状态以及运行历史记录 会话文件在保存时以原子方式重写。其 `functions` 映射存储 每个地址的最新状态，而其 `runs` 列表则保留记录的尝试。 ## 方案对比 | 方案 | 主要用途 | 证据与验证 | 工作流 | |---|---|---|---| | 传统反编译器 | 将机器代码转换为分析师可读的伪代码 | 反编译器分析；手动评估正确性 | 逐个函数进行分析 | | 交互式 Ghidra AI 或 MCP 助手 | 让分析师提问并请求 Ghidra 操作 | 取决于分析师、提示词和连接的工具 | 人工引导的对话 | | `auto-re-agent` | 生成并验证候选的 C/C++ 实现 | Ghidra 证据、独立 checker、结构检查、配置的构建/测试以及 parity 信号 | 带有持久化报告的有界自主 reverser/checker pipeline | `auto-re-agent` 是对 Ghidra 的补充，而不是取代它：Ghidra 提供 程序分析，而 agent 负责协调证据收集、 实现、审查、验证和报告。它专为 可重复的项目级工作流而设计，而不仅仅是一次性的反编译器对话。 ## 常见问题 ### auto-re-agent 是反编译器吗？ 从传统意义上讲不是。Ghidra 负责执行反汇编、反编译 和程序分析。`auto-re-agent` 利用该证据以及项目源码 上下文和 LLM 来生成并验证候选的 C/C++ 实现。 ### 它需要 Ghidra 吗？ 完整的二进制支持逆向工作流目前通过 `ghidra-ai-bridge` 使用 Ghidra。现有的源码可以通过 `re-agent parity --skip-ghidra` 进行仅源码 parity 检查，但该模式的证据 较少。 ### 支持哪些 LLM 提供商？ 支持 Claude API、Claude CLI、OpenAI 兼容 API 和 Codex CLI。 reverser 和 checker 可以使用不同的提供商或模型。 ### 它会修改原始源码树吗？ 不会。生成的实现会被写入报告和候选 overlay 中。 当启用隔离验证时，构建和测试将在项目的临时副本 中运行。 ### 它能证明生成的源码与二进制文件等价吗？ 不能checker、结构验证器、配置的构建/测试门控和 parity 信号提供的是保守的证据，而不是语义或 二进制等价性的正式证明。 ### 它能分析哪些二进制文件和项目？ 它可以处理 Ghidra 能够导入且 bridge 能够导出的程序。 有效的重构还取决于特定项目的源码上下文、类型、 符号、验证命令以及目标二进制文件中可用的证据。 ### 如何控制 LLM 成本和运行时长？ 审查轮次、调查和每个函数的尝试次数在 配置中都是有界的。提供商日志会记录可用的使用量和成本元数据；实际 成本取决于所选的模型、证据数量和目标复杂度。 ## 安全性与局限性 - re-agent 不会提交或推送生成的代码； - 候选生成不会覆盖原始源码树； - 审查轮次、证据操作和每个函数的尝试次数都是有界的； - 提示词/响应日志是按审查轮次写入的，而不是为每个内部 证据循环调用写入； - 配置的验证命令通过 `/bin/sh` 执行，只有在 由项目所有者控制时才应被信任； - 结构和 parity 检查能捕获有用的不匹配，但不能证明二进制 等价性； - 真正的 Ghidra/PyGhidra 集成取决于本地的 Ghidra 项目，并且 必须在该环境中进行测试。 ## 为什么 ghidra-ai-bridge 保持独立 `ghidra-ai-bridge` 仍然是一个独立的软件包，提供带有版本控制的 JSON/CLI 证据接口。auto-re-agent 通过基于能力的 backend 来使用它，为未来支持 IDA、Binary Ninja 或其他 backend 留出了空间。 ## 开发 ``` git clone https://github.com/Dryxio/auto-re-agent.git git clone https://github.com/Dryxio/ghidra-ai-bridge.git cd auto-re-agent python3 -m venv .venv source .venv/bin/activate python3 -m pip install -e "../ghidra-ai-bridge[headless]" python3 -m pip install -e ".[dev]" pytest -q ruff check src tests mypy src ``` ## 许可证 MIT

标签：C2, DLL 劫持, Ghidra, Petitpotam, 二进制分析, 云安全运维, 云资产清单, 人工智能, 代码重构, 大语言模型, 用户模式Hook绕过, 网络调试, 自动化, 逆向工具, 逆向工程