re-agent

自主逆向工程代理 — 源码感知的反向/检查循环、目标验证器、一致性引擎以及 Ghidra 后端。

概述

re-agent 通过将反向/检查循环与 Ghidra 反编译（借助 ghidra-ai-bridge）相结合，自动化逆向工程工作流。当前流水线还会在生成时获取附近项目的源码上下文，并在接受检查通过之前运行保守的结构化验证器。

re-agent reverse --class CTrain
    │
    ├── 配置 (re-agent.yaml + env + CLI)
    │   └── 项目配置文件 (stub_markers, hook_patterns, source_layout)
    │
    ├── 编排器 (单函数/类运行器)
    │   ├── 函数选择器 (根据调用者数量排序，过滤已完成的)
    │   ├── 上下文收集器 (反编译 + 交叉引用 + 结构体 + 源码检索)
    │   │
    │   ├── 代理循环 (反向 → 检查 → 修复，最多 N 轮)
    │   │   ├── LLM 提供商: Claude | OpenAI 兼容 API | Codex CLI
    │   │   └── 提示模板 (可自定义的 .md 文件)
    │   │
    │   ├── 目标验证器 (调用计数 + 控制流健全性检查)
    │   │
    │   ├── 一致性引擎 (GREEN/YELLOW/RED 验证门)
    │   │   ├── 源码索引器 (C++ 函数体解析器)
    │   │   ├── 11 个启发式信号 (全部可配置/开关)
    │   │   └── 语义规则 + 手动审批
    │   │
    │   └── 会话状态 (JSON 进度文件)
    │
    └── RE 后端: ghidra-ai-bridge
        └── 能力标志 → 优雅降级

需求

Python 3.10+
ghidra-ai-bridge — re-agent 使用它作为后端来反编译函数、获取交叉引用、读取结构体/枚举以及查询 Ghidra。请先安装它并将其指向您的 Ghidra 项目，然后再运行 re-agent reverse。
一个受支持的 LLM 设置：
- ANTHROPIC_API_KEY 用于 Claude
- OPENAI_API_KEY 用于 OpenAI 兼容 API
- 本地 codex CLI 登录（用于 Codex 提供商）

安装

pip install auto-re-agent

快速开始

# 1. 初始化项目配置
re-agent init

# 2. 使用您的项目设置编辑 re-agent.yaml

# 3. 逆向单个函数
re-agent reverse --address 0x6F86A0

# 4. 逆向类中的所有函数
re-agent reverse --class CTrain --max-functions 10

# 5. 运行一致性检查
re-agent parity --address 0x6F86A0

# 6. 检查进度
re-agent status

配置

re-agent 使用分层配置系统（优先级从高到低）：CLI 标志 > 环境变量 (RE_AGENT_*) > re-agent.yaml > 默认值。

llm:
  provider: claude           # claude | openai | openai-compat | codex
  model: claude-sonnet-4-5-20250929
  # api_key: 通过环境变量 RE_AGENT_LLM_API_KEY 设置
  timeout_s: 1800

backend:
  type: ghidra-bridge
  cli_path: ~/ghidra-tools/ghidra

orchestrator:
  max_review_rounds: 4
  max_functions_per_class: 10
  objective_verifier_enabled: true

project_profile:
  source_root: ./source/game_sa
  hook_patterns:
    - 'RH_ScopedInstall\s*\(\s*(\w+)\s*,\s*(0x[0-9A-Fa-f]+)'
  stub_markers: ["NOTSA_UNREACHABLE"]
  stub_call_prefix: "plugin::Call"

有关所有选项，请参阅 docs/configuration.md。

CLI 参考

LLM 提供商

Claude (Anthropic SDK) — 设置 ANTHROPIC_API_KEY
OpenAI / OpenAI 兼容 — 设置 OPENAI_API_KEY，可选设置 base_url
Codex CLI — 使用本地 codex exec 和 ChatGPT 登录凭据；无需 API 密钥

一致性引擎

一致性引擎运行 11 个可配置的启发式信号，以验证逆向代码是否与原始二进制文件匹配：

目标验证器

逆向循环还会在 LLM 检查通过后运行一个保守的结构化验证器。它仅在出现强不匹配时阻止接受，例如：

候选代码与反编译/汇编之间的调用计数差距
控制流差距，即候选代码明显缺少分支或循环

这有意比完整的等价性检查更窄，但它能捕获明显的误报，防止它们被记录为成功的逆向结果。

这一点在实践中很重要，因为 LLM 检查器仍可能对看似合理但实际缺少二进制中真实分支或调用结构的代码产生误报。

安全性

不自动提交：re-agent 会写入代码，但从不提交或推送
有界重试：修复循环迭代次数有硬性上限（默认：4）
确定性日志：每次 LLM 调用均带有时间戳记录
无破坏性操作：从不删除文件、修改 git 或运行构建
会话隔离：进度以追加方式写入，从不覆盖

开发

git clone https://github.com/dryxio/auto-re-agent.git
cd auto-re-agent
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest tests/
ruff check src/
mypy src/re_agent/

许可证

MIT

`re-agent init`	生成 `re-agent.yaml` 配置文件
`re-agent reverse --address ADDR`	逆向单个函数
`re-agent reverse --class CLASS`	逆向类中的所有函数
`re-agent reverse --dry-run`	显示将要逆向的内容
`re-agent parity --address ADDR`	对函数运行一致性检查
`re-agent parity --filter REGEX`	根据模式运行一致性检查
`re-agent status`	显示逆向进度
`re-agent status --class CLASS`	显示特定类的进度

缺少源码	RED	未找到已挂钩函数的源码函数体
存根标记	RED	源码包含存根标记（例如 NOTSA_UNREACHABLE）
平凡存根	RED	插件调用密集，函数体极小且无控制流
大汇编小源码	RED	汇编 >= 80 条指令但源码 <= 12 行
插件调用密集	YELLOW	插件调用占据函数体主体
短函数体	YELLOW	函数体少于 6 行
低调用数	YELLOW	反编译显示大量被调用者，但源码中很少
FP 敏感性	YELLOW	汇编中有浮点运算，但源码中没有
调用计数不匹配	YELLOW	源码调用计数与汇编显著不同
NaN 逻辑	YELLOW	反编译中有 NaN 处理，但源码中没有
内联包装器	INFO	函数是简单的内联包装器

auto-re-agent

最受欢迎