re-agent

Agente autónomo de ingeniería inversa: bucle reversor/verificador consciente del código fuente, verificador de objetivos, motor de paridad y backend Ghidra.

Descripción general

Demo: YouTube

re-agent automatiza un flujo de trabajo de ingeniería inversa combinando un bucle reversor/verificador con descompilación de Ghidra a través de ghidra-ai-bridge. El pipeline actual también recupera el contexto del código fuente del proyecto cercano durante la generación y ejecuta un verificador estructural conservador antes de aceptar los pases del verificador.

re-agent reverse --class CTrain
    │
    ├── Config (re-agent.yaml + env + CLI)
    │   └── project_profile (stub_markers, hook_patterns, source_layout)
    │
    ├── Orchestrador (ejecutor único / de clase)
    │   ├── Selector de funciones (ordena por número de llamantes, filtra completadas)
    │   ├── Recolector de contexto (descompilar + xrefs + structs + recuperación de fuente)
    │   │
    │   ├── Bucle del agente (reversor → verificador → corrección, máximo N rondas)
    │   │   ├── Proveedores LLM: Claude | APIs compatibles con OpenAI | Codex CLI
    │   │   └── Plantillas de prompt (archivos .md personalizables)
    │   │
    │   ├── Verificador de objetivos (recuento de llamadas + comprobaciones de cordura de flujo de control)
    │   │
    │   ├── Motor de paridad (puerta de verificación VERDE/AMARILLO/ROJO)
    │   │   ├── Indexador de fuente (analizador de cuerpo C++)
    │   │   ├── 11 Señales heurísticas (todas configurables/activables)
    │   │   └── Reglas semánticas + Aprobaciones manuales
    │   │
    │   └── Estado de sesión (archivo de progreso JSON)
    │
    └── Backend RE: ghidra-ai-bridge
        └── Banderas de capacidad → degradación gradual

Requisitos

• Python 3.10+
• ghidra-ai-bridge — re-agent lo utiliza como backend para descompilar funciones, obtener xrefs, leer structs/enums y consultar Ghidra. Instálalo y apúntalo a tu proyecto de Ghidra antes de ejecutar re-agent reverse.
• Una configuración de LLM compatible:
  • ANTHROPIC_API_KEY para Claude
  • OPENAI_API_KEY para APIs compatibles con OpenAI
  • un inicio de sesión local de codex CLI para el proveedor Codex

Instalación

pip install auto-re-agent

Inicio rápido

# 1. Inicializar configuración del proyecto
re-agent init

# 2. Editar re-agent.yaml con la configuración de tu proyecto

# 3. Revertir una sola función
re-agent reverse --address 0x6F86A0

# 4. Revertir todas las funciones de una clase
re-agent reverse --class CTrain --max-functions 10

# 5. Ejecutar comprobaciones de paridad
re-agent parity --address 0x6F86A0

# 6. Verificar progreso
re-agent status

Configuración

re-agent utiliza un sistema de configuración en capas (prioridad de mayor a menor): banderas CLI > variables de entorno (RE_AGENT_*) > re-agent.yaml > valores predeterminados.

llm:
  provider: claude           # claude | openai | openai-compat | codex
  model: claude-sonnet-4-5-20250929
  # api_key: establecida mediante la variable de entorno 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 para todas las opciones.

Referencia CLI

Proveedores LLM

• Claude (SDK de Anthropic) — establece ANTHROPIC_API_KEY
• OpenAI / compatible con OpenAI — establece OPENAI_API_KEY, opcionalmente establece base_url
• Codex CLI — utiliza codex exec local con credenciales de inicio de sesión de ChatGPT; no requiere clave API

Motor de paridad

El motor de paridad ejecuta 11 señales heurísticas configurables para verificar que el código revertido coincida con el binario original:

Verificador de objetivos

El bucle de reversión también ejecuta un verificador estructural conservador después de que el verificador LLM pase. Solo bloquea la aceptación en discrepancias fuertes como:

• brechas en el recuento de llamadas entre el código candidato y la descompilación/ASM
• brechas en el flujo de control donde el candidato claramente carece de ramas o bucles

Esto es intencionalmente más estrecho que una verificación de equivalencia completa, pero detecta falsos positivos evidentes antes de que se registren como reversiones exitosas.

Esto es importante en la práctica porque un verificador LLM puede dar falsos positivos en código que parece plausible pero que omite la estructura real de ramas o llamadas del binario.

Seguridad

• Sin auto-commit: re-agent escribe código pero nunca hace commit ni push
• Reintentos limitados: Límite máximo en iteraciones del bucle de corrección (predeterminado: 4)
• Registros deterministas: Cada llamada LLM registrada con marcas de tiempo
• Sin operaciones destructivas: Nunca elimina archivos, modifica git ni ejecuta compilaciones
• Aislamiento de sesión: El progreso se añade, nunca se sobrescribe

Desarrollo

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/

Licencia

MIT