Rev·Deck — Rétro-ingénierie assistée par IA avec Ghidra

Rev·Deck est une station de travail d'analyse statique locale, mono-utilisateur. Elle associe une interface web orientée preuves à un copilote LLM s'appuyant sur un binaire analysé par un service Ghidra sans tête : parcourez directement les preuves déterministes (fonctions, chaînes, imports, références croisées, graphe d'appels borné), ou posez à l'assistant des questions bornées dont les affirmations factuelles doivent citer des preuves vérifiables.

Les binaires analysés ne sont jamais exécutés. Le navigateur ne communique qu'avec cette application Flask ; l'application relaie des requêtes validées et typées vers le service Ghidra.

Démo

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

Démarrage rapide (Docker)

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

Docker Compose lit .env automatiquement pour l'interpolation. Il échoue avant de démarrer si API_BASE ou MODEL_NAME est absent ; API_KEY=not-used reste valable pour les fournisseurs locaux/sans clé. La pile démarre les deux services. Ouvrez http://127.0.0.1:5000.

Pour exécuter uniquement le service 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

Pour un épinglage reproductible, utilisez le digest de la version testée au lieu de 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

Prérequis

• Docker et Docker Compose (pour le parcours de démarrage rapide), ou Python 3.10+ et Node.js 18+ (pour exécuter depuis les sources).
• Un point de terminaison LLM compatible OpenAI (local ou hébergé) et un nom de modèle.
• L'image publique Ghidra : biniamfd/ghidra-headless-rest:latest.

Variables d'environnement essentielles

Copiez .env.example vers .env et remplissez ces champs ; consultez ce fichier pour la liste complète et les valeurs par défaut.

Fournisseur LLM

Rev·Deck communique avec tout point de terminaison Chat Completions compatible OpenAI via le SDK OpenAI, configuré entièrement par API_BASE / API_KEY / MODEL_NAME. Il n'y a ni en-tête, ni paramètre, ni logique de modèle spécifique à un fournisseur : un serveur local Ollama (API_BASE=http://127.0.0.1:11434/v1), un point de terminaison auto-hébergé vLLM/llama.cpp/LM Studio, OpenAI lui-même, ou une passerelle comme OpenRouter fonctionnent tous de la même manière.

Exemples de réglages fournisseur dans .env (utilisez des espaces réservés, ne commettez jamais de vraies clés) :

# 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

Par défaut (LLM_STREAM=auto), l'assistant demande une réponse en streaming et relaie les jetons vers le navigateur au fur et à mesure. Le streaming offre aussi une meilleure garantie d'annulation : lorsque vous arrêtez une réponse (ou fermez l'onglet), Rev·Deck ferme rapidement le flux du fournisseur sous-jacent et n'effectue plus aucun cycle d'outil ou de modèle ; la génération en amont est ainsi interrompue plutôt que laissée s'exécuter jusqu'au bout en arrière-plan.

Mises en garde :

• Facturation. L'annulation ferme immédiatement le flux de notre côté, mais certains fournisseurs hébergés facturent quand même les jetons déjà générés (ou la totalité de la complétion), indépendamment d'une déconnexion anticipée du client. La garantie porte sur ne pas faire plus de travail, pas sur la politique de facturation d'un fournisseur.
• Compatibilité. Tous les points de terminaison compatibles OpenAI n'acceptent pas le streaming avec outils. En mode auto, si le fournisseur rejette la requête en streaming avec une erreur de compatibilité (HTTP 400/404/405/422) avant tout contenu ou sortie d'appel d'outil, Rev·Deck retombe une seule fois sur un appel bloquant et s'en souvient pour le reste du processus. Les erreurs d'authentification (401/403), de limite de débit (429) et de serveur (5xx) ne sont pas traitées comme des problèmes de compatibilité et sont remontées comme erreurs plutôt que réessayées en silence. Définissez LLM_STREAM=false pour ignorer complètement le streaming, ou LLM_STREAM=true pour l'exiger (sans repli).

Comment utiliser

Ouvrez l'application et téléversez un binaire pour démarrer une tâche d'analyse. Tout contenu manifestement en texte brut demande confirmation avant d'être envoyé à Ghidra ; n'utilisez la dérogation explicite binaire brut que lorsque le contenu est intentionnellement du firmware/des données plutôt qu'un format exécutable. Une fois l'analyse terminée, basculez entre deux onglets de l'espace de travail :

• Analyse — vues de preuves déterministes : résumé, fonctions (filtre/pagination), imports, chaînes, une vue de requête, un inspecteur de fonction (pseudocode, références croisées, graphe d'appels borné, hexdump), et — lorsque le service Ghidra connecté les prend en charge — types, globales, annotations sidecar, export d'archive, et un classement déterministe de la surface d'attaque avec signaux positifs/atténuants explicables et couverture des preuves.
• Chat — l'assistant, selon l'un de deux modes :
  • Copilote (défaut) : un pas/appel d'outil borné par message, pour les questions ponctuelles.
  • Autonome : lancez un workflow nommé et budgété qui exécute plusieurs étapes bornées tout seul et affiche une chronologie d'activité en direct pendant qu'il travaille.

Les deux modes acceptent un budget d'étapes par tâche, ainsi qu'une option Sans limite d'étapes qui s'exécute jusqu'à la fin de la tâche (toujours plafonnée par MAX_STEP_BUDGET pour qu'un modèle en boucle ne puisse pas s'emballer). Si une exécution atteint son budget, elle rapporte des résultats partiels et propose Continuer — ce qui reprend la même conversation en utilisant les preuves déjà récupérées, sans refaire les appels d'outils terminés. Le coût augmente avec le nombre d'appels d'outils/modèle, donc des budgets plus élevés coûtent plus cher.

Workflows disponibles :

Sous-investigations ciblées

Chaque tâche d'analyse dispose d'un chat Principal plus de sous-fils de discussion ciblés facultatifs. Choisissez Nouvelle sous-investigation, saisissez un brief d'une ligne, et travaillez avec un contexte de conversation neuf sur le même binaire et les mêmes outils en lecture seule. Les historiques des fils restent isolés, et un seul fil diffuse en streaming à la fois.

Lorsque le travail ciblé est prêt, choisissez Renvoyer la conclusion au parent. Rev·Deck effectue un seul appel de modèle borné sur ce sous-fil uniquement, valide ses citations de preuves et ajoute une carte de conclusion marquée par provenance au parent. La branche complète reste rouvrable, tandis que le contexte parent ne reçoit que la conclusion compacte—pas la transcription de la branche. Une carte renvoyée sans aucune citation validée est explicitement marquée non vérifiée.

Les réponses de l'assistant citent les preuves en ligne comme [function:0xADDR], [string:0xADDR], ou [import:name]. Les citations sont vérifiées par rapport à ce qui a réellement été récupéré pendant le tour ; une citation qui ne correspond pas est signalée « (non vérifiée) » et doit être traitée comme une affirmation non confirmée, pas comme un fait.

Les diagrammes Mermaid dans la sortie de l'assistant (par ex. esquisses de graphe d'appels) s'affichent dans un cadre sandbox sans accès réseau externe.

Architecture

Le navigateur ne communique qu'avec l'application web Rev·Deck. Rev·Deck coordonne le LLM configuré et le service Ghidra sans tête, puis présente les preuves résultantes et l'activité de l'agent dans un seul espace de travail.

Exécution depuis les sources

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

Ouvrez http://127.0.0.1:5000. Docker Compose lit .env automatiquement ; l'exécution depuis les sources nécessite de l'exporter comme indiqué ci-dessus. Le serveur de développement Flask convient pour un usage local ; l'image Docker exécute Gunicorn.

Sécurité / limite locale uniquement

Cet outil est conçu pour un analyste de confiance sur sa propre machine — pas pour un hébergement multi-utilisateur ou public. Par défaut, l'application et le service Ghidra n'écoutent que sur 127.0.0.1, le mode débogage est désactivé, les binaires téléversés ne sont jamais exécutés, et la clé du fournisseur LLM reste côté serveur.

Tests

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

Dépannage

• « Service hors ligne » / /readyz renvoie 503 — le service Ghidra est injoignable sur GHIDRA_API_BASE, ou API_BASE/MODEL_NAME n'est pas défini.
• Types/Globales/Annotations affichent « nécessite v1 » — le service Ghidra connecté n'annonce pas cette capacité ; attendu sur les services plus anciens.
• Erreur immédiate du chat — vérifiez API_BASE/API_KEY/MODEL_NAME et que le fournisseur est joignable dans les limites de LLM_TIMEOUT.
• Téléversement rejeté car trop volumineux — augmentez MAX_UPLOAD_BYTES.
• Le téléversement ressemble à du texte brut — Rev·Deck demande confirmation avant de l'envoyer à Ghidra ; continuez en binaire brut uniquement lorsque c'est intentionnel.
• L'analyse volumineuse expire — augmentez ANALYSIS_TIMEOUT du conteneur Ghidra (par exemple 5400 pour les binaires C++/Android de plus de 10 000 fonctions) et re-téléversez. n'est pas lié.