Rev·Deck — Ghidra를 이용한 AI 지원 리버스 엔지니어링

Rev·Deck은 로컬 단일 사용자 정적 분석 워크스테이션입니다. 헤드리스 Ghidra 서비스가 분석한 바이너리 위에서 증거 우선(evidence-first) 웹 UI와 LLM 코파일럿을 결합합니다: 결정적 증거(함수, 문자열, 임포트, 교차 참조, 제한된 호출 그래프)를 직접 탐색하거나, 사실적 주장이 검사 가능한 증거를 인용해야 하는 제한된 질문을 어시스턴트에게 할 수 있습니다.

분석된 바이너리는 절대 실행되지 않습니다. 브라우저는 이 Flask 앱과만 통신하며, 앱은 검증된 타입 요청을 Ghidra 서비스로 프록시합니다.

데모

https://github.com/user-attachments/assets/fba14dc5-7ad5-4137-9349-ed824da64fbe

빠른 시작 (Docker)

cp .env.example .env      # set API_BASE and MODEL_NAME; set API_KEY if required
docker compose up --build

Docker Compose는 값 보간을 위해 .env를 자동으로 읽습니다. API_BASE 또는 MODEL_NAME이 없으면 시작 전에 실패합니다. API_KEY=not-used는 로컬/키 없는 제공업체에서 유효합니다. 이 스택은 두 서비스를 모두 시작합니다. http://127.0.0.1:5000을 엽니다.

Ghidra 서비스만 실행하려면:

docker pull biniamfd/ghidra-headless-rest:latest   # ensure the newest image

docker run --rm \
  -p 127.0.0.1:9090:9090 \
  -v "$(pwd)/data:/data/ghidra_projects" \
  --security-opt no-new-privileges:true \
  biniamfd/ghidra-headless-rest:latest

재현 가능한 고정을 위해 latest 대신 테스트된 릴리스 다이제스트를 사용하세요:

docker run --rm \
  -p 127.0.0.1:9090:9090 \
  -v "$(pwd)/data:/data/ghidra_projects" \
  --security-opt no-new-privileges:true \
  biniamfd/ghidra-headless-rest:1.2.1@sha256:971591a3a8448d8ed969079b452306e806f36079c3ddd298f4a618d6e2f1442d

사전 요구 사항

• Docker 및 Docker Compose(빠른 시작 경로용), 또는 Python 3.10+ 및 Node.js 18+(소스에서 실행용).
• OpenAI 호환 LLM 엔드포인트(로컬 또는 호스팅)와 모델 이름.
• 공개 Ghidra 이미지: biniamfd/ghidra-headless-rest:latest.

필수 환경 변수

.env.example을 .env로 복사하여 입력하세요. 전체 목록과 기본값은 해당 파일을 참조하세요.

LLM 제공업체

Rev·Deck은 OpenAI SDK를 통해 모든 OpenAI 호환 Chat Completions 엔드포인트와 통신하며, 전적으로 API_BASE / API_KEY / MODEL_NAME으로 구성됩니다. 제공업체별 헤더, 매개변수 또는 모델 로직은 없습니다. 로컬 Ollama 서버(API_BASE=http://127.0.0.1:11434/v1), 자체 호스팅 vLLM/llama.cpp/LM Studio 엔드포인트, OpenAI 자체, 또는 OpenRouter 같은 게이트웨이 모두 동일한 방식으로 작동합니다.

.env 제공업체 설정 예시(자리 표시자를 사용하고 실제 키를 커밋하지 마세요):

# Ollama
API_BASE=http://127.0.0.1:11434/v1
API_KEY=not-used
MODEL_NAME=qwen3:8b

# OpenRouter
API_BASE=https://openrouter.ai/api/v1
API_KEY=replace-with-your-key
MODEL_NAME=anthropic/claude-opus-4.8

# OpenAI
API_BASE=https://api.openai.com/v1
API_KEY=replace-with-your-key
MODEL_NAME=replace-with-a-supported-model-id

# LM Studio, vLLM, or llama.cpp (adjust port/model to the server)
API_BASE=http://127.0.0.1:1234/v1
API_KEY=not-used
MODEL_NAME=replace-with-the-served-model-id

기본적으로(LLM_STREAM=auto) 어시스턴트는 스트리밍 응답을 요청하고 토큰이 도착하는 대로 브라우저에 전달합니다. 스트리밍은 또한 더 강력한 취소 보장을 제공합니다: 응답을 중지하거나(또는 탭을 닫으면) Rev·Deck이 기본 제공업체 스트림을 즉시 닫고 추가 도구 또는 모델 라운드를 수행하지 않으므로, 업스트림 생성이 백그라운드에서 완료될 때까지 남겨지지 않고 중단됩니다.

주의 사항:

• 요금 청구. 취소하면 즉시 우리 쪽에서 스트림이 닫히지만, 일부 호스팅 제공업체는 클라이언트의 조기 연결 해제와 관계없이 이미 생성한 토큰(또는 전체 완성)에 대해 여전히 청구합니다. 이 보장은 추가 작업을 수행하지 않는다는 것이지 제공업체의 청구 정책에 대한 것은 아닙니다.
• 호환성. 모든 OpenAI 호환 엔드포인트가 도구 포함 스트리밍을 허용하는 것은 아닙니다. auto 모드에서 제공업체가 콘텐츠나 도구 호출 출력이 전혀 나오기 전에 호환성 오류(HTTP 400/404/405/422)로 스트리밍 요청을 거부하면, Rev·Deck은 한 번만 블로킹 호출로 폴백하고 프로세스의 나머지 동안 이를 기억합니다. 인증(401/403), 속도 제한(429) 및 서버(5xx) 오류는 호환성 문제로 취급되지 않으며, 자동 재시도 대신 오류로 표시됩니다. 스트리밍을 완전히 건너뛰려면 LLM_STREAM=false를, 스트리밍을 필수로 하려면(폴백 없음) LLM_STREAM=true를 설정하세요.

사용 방법

앱을 열고 바이너리를 업로드하여 분석 작업을 시작합니다. 명백한 평문 콘텐츠는 Ghidra로 전송되기 전에 확인을 요청합니다. 콘텐츠가 의도적으로 실행 파일 형식이 아닌 펌웨어/데이터인 경우에만 명시적 원시 바이너리(raw-binary) 재정의를 사용하세요. 분석이 완료되면 두 개의 워크스페이스 탭을 전환합니다:

• 분석(Analysis) — 결정적 증거 보기: 요약, 함수(필터/페이지네이션), 임포트, 문자열, 쿼리 뷰, 함수 인스펙터(의사 코드, 교차 참조, 제한된 호출 그래프, 헥스덤프), 그리고 연결된 Ghidra 서비스가 지원하는 경우 — 타입, 전역 변수, 사이드카 주석, 아카이브 내보내기, 설명 가능한 긍정/완화 신호와 증거 커버리지를 갖춘 결정적 공격 표면(Attack Surface) 순위.
• 채팅(Chat) — 두 가지 모드 중 하나의 어시스턴트:
  • 코파일럿(Copilot) (기본값): 메시지당 하나의 제한된 단계/도구 호출로 임시 질문에 사용.
  • 자율(Autonomous): 여러 제한된 단계를 스스로 실행하고 작업 중 실시간 활동 타임라인을 표시하는 이름 지정된 예산 기반 워크플로우를 시작합니다.

두 모드 모두 작업별 단계 예산(step budget) 과 작업이 끝날 때까지 실행되는 단계 제한 없음(No step limit) 옵션이 있습니다(루프에 빠진 모델이 무한정 실행되지 않도록 여전히 MAX_STEP_BUDGET으로 제한됨). 실행이 예산에 도달하면 부분 결과를 보고하고 계속(Continue) 을 제안합니다. 이는 이미 검색된 증거를 사용하여 동일한 대화를 이어가며 완료된 도구 호출을 다시 수행하지 않습니다. 비용은 도구/모델 호출 수에 비례하여 증가하므로 예산이 높을수록 비용이 더 많이 듭니다.

사용 가능한 워크플로우:

집중 하위 조사

각 분석 작업에는 메인(Main) 채팅과 선택적인 집중 하위 스레드가 있습니다. 새 하위 조사(New sub-investigation) 를 선택하고 한 줄 브리핑을 입력한 후, 동일한 바이너리와 동일한 읽기 전용 도구를 사용하여 새로운 대화 컨텍스트로 작업합니다. 스레드 기록은 격리된 상태로 유지되며 한 번에 하나의 스레드만 스트리밍됩니다.

집중 작업이 완료되면 부모에게 결론 반환(Return conclusion to parent) 을 선택합니다. Rev·Deck은 해당 하위 스레드에 대해서만 한 번의 제한된 모델 호출을 수행하고, 증거 인용을 검증한 다음, 출처가 표시된 결론 카드 하나를 부모 스레드에 추가합니다. 전체 분기는 다시 열 수 있는 상태로 유지되며, 부모 컨텍스트는 분기 기록이 아닌 간결한 결론만 받습니다. 검증된 인용이 없는 반환 카드는 명시적으로 미검증으로 표시됩니다.

어시스턴트 답변은 [function:0xADDR], [string:0xADDR], [import:name] 형식으로 증거를 인라인 인용합니다. 인용은 턴 중에 실제로 검색된 내용과 대조하여 확인됩니다. 일치하지 않는 인용은 "(unverified)"로 표시되며 사실이 아닌 미확인 주장으로 취급해야 합니다.

어시스턴트 출력의 Mermaid 다이어그램(예: 호출 그래프 스케치)은 외부 네트워크 접근이 없는 샌드박스 프레임에서 렌더링됩니다.

아키텍처

브라우저는 Rev·Deck 웹 애플리케이션과만 통신합니다. Rev·Deck은 구성된 LLM과 헤드리스 Ghidra 서비스를 조정한 다음, 결과 증거와 에이전트 활동을 하나의 워크스페이스에 표시합니다.

소스에서 실행

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
npm ci && npm run vendor        # one-time: vendors the pinned Mermaid runtime

cp .env.example .env            # edit API_BASE / MODEL_NAME / API_KEY
set -a; source .env; set +a     # plain Python does not load .env automatically

# Start the separate Ghidra service, then:
python webui/app.py

http://127.0.0.1:5000을 엽니다. Docker Compose는 .env를 자동으로 읽습니다. 소스 실행은 위와 같이 내보내기(export)가 필요합니다. Flask 개발 서버는 로컬 사용에 적합하며, Docker 이미지는 Gunicorn을 실행합니다.

보안 / 로컬 전용 경계

이 도구는 개인 머신에서 작업하는 신뢰할 수 있는 단일 분석가를 위해 설계되었습니다 — 다중 사용자 또는 공개 호스팅용이 아닙니다. 기본적으로 앱과 Ghidra 서비스는 127.0.0.1에만 바인딩되고, 디버그 모드는 꺼져 있으며, 업로드된 바이너리는 절대 실행되지 않고, LLM 제공업체 키는 서버 측에 유지됩니다.

테스트

pip install -r requirements.txt -r requirements-dev.txt
python -m pytest
node --test "webui/static/js/tests/**/*.test.mjs"
npm ci && npm run vendor:verify   # verifies the vendored Mermaid bundle's integrity

문제 해결

• "서비스 오프라인(Service offline)" / /readyz가 503 반환 — GHIDRA_API_BASE에서 Ghidra 서비스에 연결할 수 없거나 API_BASE/MODEL_NAME이 설정되지 않았습니다.
• 타입/전역/주석에 "requires v1" 표시 — 연결된 Ghidra 서비스가 해당 기능을 광고하지 않습니다. 이전 버전 서비스에서 예상되는 현상입니다.
• 채팅이 즉시 오류 발생 — API_BASE/API_KEY/MODEL_NAME과 제공업체가 LLM_TIMEOUT 내에 연결 가능한지 확인하세요.
• 업로드가 너무 크다는 이유로 거부됨 — MAX_UPLOAD_BYTES를 높이세요.
• 업로드가 평문처럼 보임 — Rev·Deck이 Ghidra로 전송하기 전에 확인합니다. 의도적인 경우에만 원시 바이너리로 계속 진행하세요.
• 대규모 분석 시간 초과 — Ghidra 컨테이너의 ANALYSIS_TIMEOUT을 늘리고(예: 함수가 1만 개 이상인 C++/Android 바이너리의 경우 5400) 다시 업로드하세요. LLM_TIMEOUT과는 관련이 없습니다.