Rev·Deck – KI-gestütztes Reverse Engineering mit Ghidra

Rev·Deck ist eine lokale Workstation zur statischen Analyse für einen einzelnen Benutzer. Sie kombiniert eine evidenzorientierte Web-UI mit einem LLM-Copilot für Binärdateien, die von einem Headless-Ghidra-Dienst analysiert werden: Durchsuchen Sie deterministische Evidenz (Funktionen, Strings, Importe, Querverweise, einen begrenzten Aufrufgraph) direkt oder stellen Sie dem Assistenten begrenzte Fragen, deren Tatsachenbehauptungen überprüfbare Evidenz zitieren müssen.

Analysierte Binärdateien werden niemals ausgeführt. Der Browser kommuniziert nur mit dieser Flask-App; die App leitet validierte, typisierte Anfragen an den Ghidra-Dienst weiter.

Demo

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

Schnellstart (Docker)

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

Docker Compose liest .env automatisch zur Interpolation. Es bricht vor dem Start ab, wenn API_BASE oder MODEL_NAME fehlt; API_KEY=not-used bleibt für lokale/schlüssellose Anbieter gültig. Der Stack startet beide Dienste. Öffnen Sie http://127.0.0.1:5000.

Um nur den Ghidra-Dienst auszuführen:

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

Um einen Stand reproduzierbar zu fixieren, verwenden Sie den getesteten Release-Digest anstelle von 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

Voraussetzungen

• Docker und Docker Compose (für den Schnellstart-Pfad) oder Python 3.10+ und Node.js 18+ (für die Ausführung aus dem Quellcode).
• Ein OpenAI-kompatibler LLM-Endpunkt (lokal oder gehostet) und ein Modellname.
• Das öffentliche Ghidra-Image: biniamfd/ghidra-headless-rest:latest.

Wichtige Umgebungsvariablen

Kopieren Sie .env.example zu .env und füllen Sie diese aus; die vollständige Liste und Standardwerte finden Sie in dieser Datei.

LLM-Anbieter

Rev·Deck spricht mit jedem OpenAI-kompatiblen Chat-Completions-Endpunkt über das OpenAI-SDK, vollständig konfiguriert über API_BASE / API_KEY / MODEL_NAME. Es gibt keine anbieterspezifische Header-, Parameter- oder Modelllogik: Ein lokaler Ollama-Server (API_BASE=http://127.0.0.1:11434/v1), ein selbst gehosteter vLLM/llama.cpp/LM-Studio-Endpunkt, OpenAI selbst oder ein Gateway wie OpenRouter funktionieren alle auf dieselbe Weise.

Beispiele für .env-Anbietereinstellungen (Platzhalter verwenden, niemals echte Schlüssel einchecken):

# 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

Standardmäßig (LLM_STREAM=auto) fordert der Assistent eine gestreamte Antwort an und leitet Token weiter, sobald sie eintreffen. Streaming bietet außerdem eine stärkere Abbruchgarantie: Wenn Sie eine Antwort stoppen (oder den Tab schließen), schließt Rev·Deck den zugrunde liegenden Anbieterstream umgehend und führt keine weiteren Tool- oder Modellrunden aus, sodass die vorgelagerte Generierung abgebrochen wird, statt im Hintergrund bis zum Abschluss weiterzulaufen.

Hinweise:

• Abrechnung. Durch Abbrechen wird der Stream auf unserer Seite sofort geschlossen, aber einige gehostete Anbieter rechnen weiterhin Token ab, die sie bereits generiert haben (oder die gesamte Antwort), ungeachtet einer vorzeitigen Client-Trennung. Die Garantie bezieht sich darauf, keine weitere Arbeit zu verrichten, nicht auf die Abrechnungspolitik eines Anbieters.
• Kompatibilität. Nicht jeder OpenAI-kompatible Endpunkt akzeptiert Streaming mit Tools. Unter auto, wenn der Anbieter die gestreamte Anfrage mit einem Kompatibilitätsfehler (HTTP 400/404/405/422) ablehnt, bevor Inhalte oder Tool-Call-Ausgaben vorliegen, fällt Rev·Deck einmal auf einen einzelnen blockierenden Aufruf zurück und merkt sich das für den Rest des Prozesses. Authentifizierungsfehler (401/403), Ratenbegrenzung (429) und Serverfehler (5xx) werden nicht als Kompatibilitätsprobleme behandelt, sondern als Fehler angezeigt, statt stillschweigend erneut versucht zu werden. Setzen Sie LLM_STREAM=false, um Streaming vollständig zu überspringen, oder LLM_STREAM=true, um es zu erzwingen (kein Fallback).

Verwendung

Öffnen Sie die App und laden Sie eine Binärdatei hoch, um einen Analyseauftrag zu starten. Offensichtliche Klartextinhalte lösen eine Bestätigungsabfrage aus, bevor sie an Ghidra gesendet werden; verwenden Sie die explizite Rohbinary-Übersteuerung nur, wenn der Inhalt absichtlich Firmware/Daten und kein ausführbares Format ist. Sobald die Analyse abgeschlossen ist, wechseln Sie zwischen zwei Arbeitsbereichs-Registerkarten:

• Analyse – deterministische Evidenzansichten: Zusammenfassung, Funktionen (filtern/paginieren), Importe, Strings, eine Abfrageansicht, ein Funktionsinspektor (Pseudocode, Querverweise, begrenzter Aufrufgraph, Hexdump) und – sofern der verbundene Ghidra-Dienst sie unterstützt – Typen, Globale, Sidecar-Annotationen, Archivexport und ein deterministisches Attack-Surface-Ranking mit erklärbaren positiven/mildernden Signalen und Evidenzabdeckung.
• Chat – der Assistent in einem von zwei Modi:
  • Copilot (Standard): ein begrenzter Schritt/Tool-Aufruf pro Nachricht für Ad-hoc-Fragen.
  • Autonom: einen benannten, budgetierten Workflow starten, der mehrere begrenzte Schritte eigenständig ausführt und während der Arbeit eine Live-Aktivitätszeitleiste anzeigt.

Beide Modi akzeptieren ein taskspezifisches Schrittbudget sowie eine Option Ohne Schrittlimit, die läuft, bis die Aufgabe abgeschlossen ist (weiterhin durch MAX_STEP_BUDGET begrenzt, sodass ein sich wiederholendes Modell nicht davonlaufen kann). Wenn ein Lauf sein Budget erreicht, meldet er Teilergebnisse und bietet Weiter an – das setzt dieselbe Konversation unter Verwendung der bereits abgerufenen Evidenz fort, ohne abgeschlossene Tool-Aufrufe zu wiederholen. Die Kosten steigen mit der Anzahl der Tool-/Modellaufrufe; höhere Budgets kosten also mehr.

Verfügbare Workflows:

Fokussierte Teiluntersuchungen

Jeder Analyseauftrag hat einen Haupt-Chat plus optionale fokussierte Unterthreads. Wählen Sie Neue Teiluntersuchung, geben Sie eine einzeilige Kurzbeschreibung ein und arbeiten Sie mit einem frischen Konversationskontext über dieselbe Binärdatei und dieselben schreibgeschützten Tools. Thread-Verläufe bleiben isoliert, und es streamt jeweils nur ein Thread.

Wenn die fokussierte Arbeit fertig ist, wählen Sie Schlussfolgerung an übergeordneten Thread zurückgeben. Rev·Deck führt genau einen begrenzten Modellaufruf auf diesem Unterthread aus, validiert seine Evidenzzitate und fügt dem übergeordneten Thread eine mit Herkunftsnachweis versehene Schlussfolgerungskarte hinzu. Der vollständige Zweig lässt sich erneut öffnen, während der übergeordnete Kontext nur die kompakte Schlussfolgerung erhält – nicht das Transkript des Zweigs. Eine zurückgegebene Karte ohne validierte Zitate wird ausdrücklich als nicht verifiziert markiert.

Antworten des Assistenten zitieren Evidenz inline als [function:0xADDR], [string:0xADDR] oder [import:name]. Zitate werden mit dem abgeglichen, was während des Turns tatsächlich abgerufen wurde; ein Zitat, das nicht übereinstimmt, wird als „(unverified)“ markiert und sollte als unbestätigte Behauptung behandelt werden, nicht als Tatsache.

Mermaid-Diagramme in der Assistentenausgabe (z. B. Aufrufgraph-Skizzen) werden in einem Sandbox-Frame ohne externen Netzwerkzugriff gerendert.

Architektur

Der Browser kommuniziert nur mit der Rev·Deck-Webanwendung. Rev·Deck koordiniert das konfigurierte LLM und den Headless-Ghidra-Dienst und präsentiert die resultierende Evidenz und Agentenaktivität in einem Arbeitsbereich.

Ausführung aus dem Quellcode

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

Öffnen Sie http://127.0.0.1:5000. Docker Compose liest .env automatisch; bei der Ausführung aus dem Quellcode muss es wie oben gezeigt exportiert werden. Der Flask-Entwicklungsserver ist für die lokale Nutzung geeignet; das Docker-Image verwendet Gunicorn.

Sicherheit / ausschließlich lokale Nutzung

Dies ist für eine vertrauenswürdige Analystin bzw. einen vertrauenswürdigen Analysten am eigenen Rechner konzipiert – nicht für Mehrbenutzer- oder öffentliches Hosting. Standardmäßig binden die App und der Ghidra-Dienst nur an 127.0.0.1, der Debug-Modus ist deaktiviert, hochgeladene Binärdateien werden niemals ausgeführt und der LLM-Anbieterschlüssel bleibt serverseitig.

Testen

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

Fehlerbehebung

• „Service offline“ / /readyz gibt 503 zurück – der Ghidra-Dienst ist unter GHIDRA_API_BASE nicht erreichbar, oder API_BASE/MODEL_NAME ist nicht gesetzt.
• Types/Globals/Annotations zeigen „requires v1“ – der verbundene Ghidra-Dienst weist diese Fähigkeit nicht aus; bei älteren Diensten zu erwarten.
• Chat bricht sofort mit einem Fehler ab – prüfen Sie API_BASE/API_KEY/MODEL_NAME und dass der Anbieter innerhalb von LLM_TIMEOUT erreichbar ist.
• Upload wird als zu groß abgelehnt – erhöhen Sie MAX_UPLOAD_BYTES.
• Upload sieht nach Klartext aus – Rev·Deck fragt nach, bevor es an Ghidra gesendet wird; nur bei Absicht als Rohbinary fortfahren.
• Große Analyse läuft in einen Timeout – erhöhen Sie ANALYSIS_TIMEOUT des Ghidra-Containers (z. B. 5400 für C++/Android-Binärdateien mit 10.000+ Funktionen) und laden Sie erneut hoch. steht damit in keinem Zusammenhang.