re-agent

Автономный агент для реверс-инжиниринга — цикл реверс/проверка с учётом исходного кода, верификатор целей, механизм паритета и бэкенд на Ghidra.

Обзор

Демо: YouTube

re-agent автоматизирует рабочий процесс реверс-инжиниринга, объединяя цикл реверс/проверка с декомпиляцией Ghidra через ghidra-ai-bridge. Текущий конвейер также извлекает контекст исходного кода из соседних файлов проекта во время генерации и запускает консервативный структурный верификатор перед принятием результатов проверки.

re-agent reverse --class CTrain
    │
    ├── Config (re-agent.yaml + env + CLI)
    │   └── project_profile (stub_markers, hook_patterns, source_layout)
    │
    ├── Orchestrator (single / class runner)
    │   ├── Function Picker (ranks by caller count, filters completed)
    │   ├── Context Gatherer (decompile + xrefs + structs + source retrieval)
    │   │
    │   ├── Agent Loop (reverser → checker → fix, max N rounds)
    │   │   ├── LLM Providers: Claude | OpenAI-compatible APIs | Codex CLI
    │   │   └── Prompt Templates (customizable .md files)
    │   │
    │   ├── Objective Verifier (call-count + control-flow sanity checks)
    │   │
    │   ├── Parity Engine (GREEN/YELLOW/RED verification gate)
    │   │   ├── Source Indexer (C++ body parser)
    │   │   ├── 11 Heuristic Signals (all configurable/toggleable)
    │   │   └── Semantic Rules + Manual Approvals
    │   │
    │   └── Session State (JSON progress file)
    │
    └── RE Backend: ghidra-ai-bridge
        └── Capability flags → graceful degradation

Требования

• Python 3.10+
• ghidra-ai-bridge — re-agent использует его как бэкенд для декомпиляции функций, получения перекрёстных ссылок, чтения структур/перечислений и запросов к Ghidra. Установите его и укажите ваш проект Ghidra перед запуском re-agent reverse.
• Один из поддерживаемых LLM:
  • ANTHROPIC_API_KEY для Claude
  • OPENAI_API_KEY для API, совместимых с OpenAI
  • локальный вход в 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: set via RE_AGENT_LLM_API_KEY env var
  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 (SDK Anthropic) — установите ANTHROPIC_API_KEY
• OpenAI / совместимые с OpenAI — установите OPENAI_API_KEY, при необходимости укажите base_url
• Codex CLI — использует локальный codex exec с учётными данными ChatGPT; ключ API не требуется

Механизм проверки паритета

Механизм паритета запускает 11 настраиваемых эвристических сигналов для проверки соответствия реверсированного кода исходному бинарнику:

Проверка целей

Цикл реверсинга также запускает консервативный структурный верификатор после прохождения проверки LLM. Он блокирует принятие только при сильных несоответствиях, таких как:

• разрыв в количестве вызовов между кандидатом и декомпиляцией/ASM
• разрывы в управлении потоком, когда в кандидате явно отсутствуют ветвления или циклы

Это намеренно более узкая проверка, чем полное доказательство эквивалентности, но она перехватывает очевидные ложные срабатывания до того, как они будут зафиксированы как успешные реверсинги.

Это важно на практике, потому что проверяющий 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