re-agent

Agente autonomo di reverse engineering — loop reverser/checker con consapevolezza del sorgente, verificatore obiettivo, motore di parità e backend Ghidra.

Panoramica

Demo: YouTube

re-agent automatizza un flusso di lavoro di reverse engineering combinando un loop reverser/checker con la decompilazione Ghidra tramite ghidra-ai-bridge. La pipeline corrente recupera anche il contesto del progetto sorgente vicino durante la generazione ed esegue un verificatore strutturale conservativo prima di accettare i passaggi del checker.

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

Requisiti

• Python 3.10+
• ghidra-ai-bridge — re-agent utilizza questo backend per decompilare funzioni, ottenere xref, leggere struct/enum e interrogare Ghidra. Installalo e puntalo al tuo progetto Ghidra prima di eseguire re-agent reverse.
• Una configurazione LLM supportata:
  • ANTHROPIC_API_KEY per Claude
  • OPENAI_API_KEY per API compatibili con OpenAI
  • un login codex CLI locale per il provider Codex

Installazione

pip install auto-re-agent

Avvio Rapido

# 1. Inizializza la configurazione del progetto
re-agent init

# 2. Modifica re-agent.yaml con le impostazioni del progetto

# 3. Reverse di una singola funzione
re-agent reverse --address 0x6F86A0

# 4. Reverse di tutte le funzioni in una classe
re-agent reverse --class CTrain --max-functions 10

# 5. Esegui controlli di parità
re-agent parity --address 0x6F86A0

# 6. Controlla lo stato
re-agent status

Configurazione

re-agent utilizza un sistema di configurazione a livelli (priorità decrescente): flag CLI > variabili d'ambiente (RE_AGENT_*) > re-agent.yaml > valori predefiniti.

llm:
  provider: claude           # claude | openai | openai-compat | codex
  model: claude-sonnet-4-5-20250929
  # api_key: impostata tramite la variabile d'ambiente 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"

Consulta docs/configuration.md per tutte le opzioni.

Riferimento CLI

Provider LLM

• Claude (Anthropic SDK) — imposta ANTHROPIC_API_KEY
• OpenAI / compatibile con OpenAI — imposta OPENAI_API_KEY, opzionalmente imposta base_url
• Codex CLI — utilizza codex exec locale con credenziali di accesso ChatGPT; nessuna chiave API richiesta

Motore di Parità

Il motore di parità esegue 11 segnali euristici configurabili per verificare che il codice reversato corrisponda al binario originale:

Verificatore Obiettivo

Il loop di reversal esegue anche un verificatore strutturale conservativo dopo che il checker LLM ha superato. Blocca l'accettazione solo in caso di forti discrepanze come:

• differenze nel conteggio delle chiamate tra il codice candidato e la decompilazione/ASM
• differenze nel flusso di controllo quando al candidato mancano chiaramente rami o cicli

Questo è intenzionalmente più ristretto di un controllo di equivalenza completo, ma cattura falsi positivi evidenti prima che vengano registrati come reversal riusciti.

Questo è importante nella pratica perché un checker LLM può comunque dare falsi positivi su codice che sembra plausibile ma che manca della vera struttura di rami o chiamate dal binario.

Sicurezza

• Nessun auto-commit: re-agent scrive codice ma non esegue mai commit o push
• Riprova limitate: Limite massimo di iterazioni del ciclo di correzione (predefinito: 4)
• Log deterministici: Ogni chiamata LLM viene registrata con timestamp
• Nessuna operazione distruttiva: Non cancella mai file, modifica git o esegue build
• Isolamento della sessione: I progressi vengono aggiunti, mai sovrascritti

Sviluppo

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/

Licenza

MIT