re-agent

स्वायत्त रिवर्स-इंजीनियरिंग एजेंट — स्रोत-जागरूक रिवर्सर/चेकर लूप, उद्देश्य सत्यापनकर्ता, समता इंजन, और Ghidra बैकएंड।

अवलोकन

डेमो: YouTube

re-agent एक रिवर्सर/चेकर लूप को ghidra-ai-bridge के माध्यम से Ghidra डीकंपाइलेशन के साथ जोड़कर रिवर्स-इंजीनियरिंग वर्कफ़्लो को स्वचालित करता है। वर्तमान पाइपलाइन जनरेशन के दौरान पास के प्रोजेक्ट स्रोत संदर्भ को भी पुनर्प्राप्त करती है और चेकर पास स्वीकार करने से पहले एक रूढ़िवादी संरचनात्मक सत्यापनकर्ता चलाती है।

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 इसे अपने बैकएंड के रूप में उपयोग करता है ताकि फ़ंक्शन को डीकंपाइल किया जा सके, xrefs प्राप्त किए जा सकें, structs/enums पढ़े जा सकें, और Ghidra से क्वेरी की जा सके। re-agent reverse चलाने से पहले इसे इंस्टॉल करें और इसे अपने Ghidra प्रोजेक्ट पर इंगित करें।
• एक समर्थित LLM सेटअप:
  • ANTHROPIC_API_KEY Claude के लिए
  • OPENAI_API_KEY OpenAI-संगत API के लिए
  • Codex प्रदाता के लिए एक स्थानीय codex CLI लॉगिन

स्थापना

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 (Anthropic SDK) — ANTHROPIC_API_KEY सेट करें
• OpenAI / OpenAI-संगत — OPENAI_API_KEY सेट करें, वैकल्पिक रूप से base_url सेट करें
• Codex CLI — ChatGPT लॉगिन क्रेडेंशियल के साथ स्थानीय codex exec का उपयोग करता है; किसी 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