TL;DR

re-agent는 Ghidra 디컴파일과 근접 소스 검색을 결합해 함수 단위 역공학을 자동화하고 LLM 기반 reverser/checker 루프를 통해 후보 코드를 생성한다. 생성된 후보는 보수적 Objective Verifier와 11개 휴리스틱 신호로 구성된 Parity Engine으로 검증되어 RED/YELLOW/GREEN 등급을 받으며 명확한 구조적 불일치만 자동 차단한다. 구성은 YAML과 환경변수를 통해 제어되며 Claude, OpenAI 호환 API, 로컬 Codex CLI를 공급자로 사용할 수 있다. 안전 설계는 자동 커밋 금지와 반복 라운드 상한(README 예시에서 4회)을 포함해 허위 긍정과 파괴적 작업을 방지한다. 이 조합은 대규모 바이너리에서 관련 함수부터 우선적으로 역공학을 시도하고 수동 검토 없이 명백한 오류를 필터링하는 워크플로우를 제공한다.

주요 기능

• 함수 단위 역공학을 자동화한다. Function Picker가 호출 수 기반으로 우선순위를 매기고 완료된 항목을 필터링해 처리 대상을 선정한다. 이 선정 과정은 대규모 바이너리에서 관심 있는 함수부터 단계적으로 역공학을 시도하도록 설계되어 효율성을 높인다.
• Ghidra와 연동해 디컴파일, xrefs, 구조체와 열거형 정보를 수집한다. re-agent는 ghidra-ai-bridge를 통해 디컴파일 결과와 교차 참조 데이터를 가져와 LLM 입력 컨텍스트를 구성한다. 수집된 구조 정보는 생성된 후보 코드의 일관성 검증과 패리티 신호 계산에 직접 사용된다.
• LLM 기반의 reverser→checker→fix 루프를 실행한다. 루프는 Claude, OpenAI 호환 API, 로컬 Codex CLI 같은 공급자를 지원하고 사용자 정의 프롬프트 템플릿을 적용한다. 체크 단계가 실패하면 최대 라운드 수만큼 수정 요청을 반복해 후보를 개선한다.
• 보수적 구조 검증과 패리티 엔진으로 허위 긍정 위험을 줄인다. Objective Verifier가 호출 횟수와 제어 흐름 차이를 탐지하며 Parity Engine은 11개의 휴리스틱 신호로 GREEN/YELLOW/RED 등급을 산정한다. 이들 검증은 자동 수락 이전에 명확한 불일치를 차단하도록 설계되어 잘못된 역공학 결과의 기록을 방지한다.

어떻게 동작하는가

re-agent는 Orchestrator가 Function Picker로 처리 우선순위를 정하고 Context Gatherer가 디컴파일, xrefs, 구조체 정보를 수집해 LLM에 전달하는 방식으로 동작한다. LLM 기반 Agent Loop는 reverser가 후보 코드를 생성하면 checker가 검증하고 필요시 fix를 요청하는 순환을 최대 설정 라운드만큼 반복한다. 반복 후 Objective Verifier와 Parity Engine이 구조적 불일치와 11개의 휴리스틱 신호를 검사해 최종 수락 여부를 결정한다.

해결 문제

바이너리 함수의 소스 코드를 다시 작성하는 과정을 자동화해 수작업으로 일일이 디컴파일과 추론을 결합하던 워크플로우를 대체한다. re-agent는 프로젝트 소스와 디컴파일 컨텍스트를 결합해 LLM의 제안이 바이너리 구조와 일치하는지를 사전 검증한다. 이를 통해 역공학 시도에서 발생하는 허위 긍정과 불필요한 수작업 검증을 감소시킨다.

차별점

• 프로젝트 근접 소스 컨텍스트를 자동으로 검색해 LLM 입력으로 포함한다. 단순한 바이너리-기반 추론 대신 디컴파일 주변의 실제 소스 코드와 연계해 후보의 정확도를 높인다. 이 접근은 소스와 바이너리 간 일관성을 평가하는 데 유리한 근거를 제공한다.
• 11개 구성 가능한 휴리스틱 신호를 사용하는 Parity Engine을 통해 등급 기반 검증을 수행한다. 신호들은 Missing source, Stub markers, Call count mismatch 등 다양한 구조적 차이를 포착하도록 설계되어 있다. 각 신호는 토글 가능하고 수동 승인 플로우와 연동되어 자동화와 사람의 판단을 결합한다.
• Objective Verifier가 보수적 제어 흐름·호출 수 검사를 수행해 LLM 체커의 오탐을 제한한다. 완전 동치 검증 대신 명확한 불일치만 차단하는 좁은 범위 검사를 적용해 오탐으로 인한 작업 중단을 줄인다. 이 설계는 LLM의 유효한 제안이 지나치게 배제되지 않도록 균형을 맞춘다.
• Ghidra 백엔드와 능동적 graceful degradation을 통해 환경 차이에 따라 기능을 조정한다. ghidra-ai-bridge가 제공하는 기능에 따라 디컴파일·xref·구조체 조회가 가능해지고 일부 기능이 없을 때는 차선 동작으로 대체한다. 이로 인해 다양한 Ghidra 설정과 프로젝트 레이아웃에서 동작 유연성이 확보된다.

사용 사례

• 특정 주소나 함수 하나를 빠르게 역공학해 후보 소스를 확보하는 데 사용된다. re-agent는 re-agent reverse --address ADDRESS 명령으로 단일 함수를 디컴파일하고 LLM을 통해 소스 후보를 생성한다. 생성된 후보는 checker와 패리티 검증을 거쳐 수락 가능 여부가 결정된다.
• 클래스 단위로 연속된 함수들을 자동 역공학해 전체 코드 흐름을 복원하는 데 활용된다. re-agent reverse --class CLASS와 max-functions 조합으로 클래스 내부 여러 함수를 우선순위에 따라 자동 처리한다. 이 과정은 호출 빈도 기반 우선순위 지정과 세션 상태 파일로 진행 상황을 추적한다.
• 바이너리-소스 일치성 감사를 위해 패리티 검증을 실행하는 데 적합하다. re-agent parity 명령은 특정 함수의 패리티 신호를 산정해 RED/YELLOW/GREEN 상태를 제공하므로 수동 검토나 추가 테스트 지점을 식별한다. 이 워크플로우는 소스 리포지토리와 바이너리 간 회귀나 불일치 조사에 유용하다.

시작하기

먼저 pip install auto-re-agent로 패키지를 설치하고 re-agent init으로 기본 설정 파일을 생성한다. 생성된 re-agent.yaml에서 project_profile과 LLM/백엔드 자격 증명(예: ANTHROPIC_API_KEY 또는 OPENAI_API_KEY, 또는 로컬 codex CLI)을 설정하고 ghidra-ai-bridge를 Ghidra 프로젝트에 연결한다. 준비가 완료되면 re-agent reverse --address 또는 --class 명령으로 역공학을 실행하고 re-agent status로 진행 상태를 확인한다.

요구사항

• Python 3.10 이상이 필요하다. README의 requirements 섹션에 Python 3.10+가 명시되어 있어 런타임 호환성을 확보해야 한다. 가상환경에서 실행하는 것을 권장한다.
• ghidra-ai-bridge와 Ghidra 프로젝트 연결이 필요하다. re-agent는 ghidra-ai-bridge를 통해 함수 디컴파일, xrefs, 구조체 정보를 조회하므로 해당 브리지를 설치하고 Ghidra 프로젝트를 가리키도록 설정해야 한다. 백엔드가 정상 연결되지 않으면 주요 분석 기능이 제한된다.
• 하나 이상의 지원되는 LLM 자격증명 또는 로컬 Codex CLI가 요구된다. Claude를 사용하려면 ANTHROPIC_API_KEY가 필요하고 OpenAI 호환 API를 사용하려면 OPENAI_API_KEY 또는 base_url을 설정해야 한다. 로컬 환경에 Codex CLI가 구성되어 있으면 API 키 없이도 Codex 공급자를 사용할 수 있다.