Analyseur headless de Ghidra : définition et cas d’usage
L’analyseur headless de Ghidra est le point d’entrée en ligne de commande pour exécuter une analyse sans ouvrir le bureau. Il peut créer ou compléter un projet, analyser des programmes importés ou déjà présents et exécuter des scripts sans interface pour des dossiers d’échantillons, le triage de firmware, des rapports planifiés ou des pipelines contrôlés.
Le mode headless n’est pas un serveur distant et ne rend pas toutes les conclusions automatiques. Le lanceur dépend toujours de l’installation de Ghidra, de l’emplacement du projet, des chargeurs, des analyseurs, des scripts et des règles habituelles du projet. Notez la version, les entrées, les options, le projet produit et le journal, et analysez uniquement des éléments pour lesquels vous avez une autorisation.
La documentation officielle et le lanceur support/analyzeHeadless correspondant à la version installée définissent les options disponibles. Cette page décrit un flux prudent, mais ne remplace pas l’aide fournie avec votre version de Ghidra.
Préparer l’installation, le projet et les fichiers d’entrée
Commencez avec le ZIP officiel de Ghidra et un JDK 64 bits compatible. La version vérifiée pour ce site est Ghidra 12.1.3, publiée le 18 août 2026, et son archive contient le lanceur dans support/. Consultez le guide d’installation de Ghidra si l’application graphique ne démarre pas ; un JDK défectueux ou une extraction incomplète fera également échouer les tâches headless.
Séparez l’application, le projet et les dossiers d’entrées ou de rapports. Ne modifiez pas un projet actif depuis une tâche par lots et n’écrasez pas une copie connue avant d’avoir inspecté la nouvelle exécution. Utilisez un nouveau nom de projet pendant les essais de scripts ou d’options d’analyse.
- 1
Vérifier le lanceur
Dans l’installation Ghidra, vérifiez que le lanceur de votre système existe et peut afficher l’aide. Windows utilise le fichier batch ; macOS et Linux utilisent le lanceur shell.
support/analyzeHeadless.bat OU support/analyzeHeadless - 2
Choisir une racine de projet accessible en écriture
Prévoyez assez d’espace pour les programmes importés, les bases de données, les caches et les rapports. Évitez un dossier synchronisé lors du diagnostic de verrous ou d’écritures concurrentes.
D:\analysis\projects /srv/ghidra/projects - 3
Consigner les entrées
Notez les noms de fichiers, les hashes, les architectures supposées et la date de collecte. Un chemin de dossier ne constitue pas une entrée reproductible si son contenu n’est pas enregistré.
samples/firmware-a.bin samples/firmware-b.bin - 4
Sauvegarder avant le traitement
Copiez le projet avant d’exécuter un script qui renomme des symboles, modifie des types de données, supprime des programmes ou enregistre des changements.
ProjectName.gpr + ProjectName.rep/
Choisir entre -import et -process
La décision centrale de l’analyseur headless consiste à déterminer si la commande doit créer ou compléter un projet à partir de fichiers, ou rouvrir des programmes déjà présents dans un projet. Utilisez -import lorsqu’un fichier ou un dossier doit devenir des programmes du projet. Utilisez -process lorsque le projet contient déjà le programme.
N’ajoutez pas les deux modes simplement parce qu’un exemple en ligne les montre ensemble. Commencez par une tâche explicable, ne précisez un chargeur ou un processeur que si nécessaire et enregistrez la commande qui fonctionne dans un script versionné.
| Tâche | Mode | Entrée habituelle | À vérifier |
|---|---|---|---|
| Créer un projet à partir de binaires | -import | Fichier ou dossier | Chargeur, langage et nom du projet |
| Analyser des programmes déjà enregistrés | -process | Projet existant | Noms des programmes et copie du projet |
| Exécuter un script pendant l’import | -import + -postScript | Nouvelles entrées | Chemin du script et sortie enregistrée |
| Traiter un arbre de programmes | -process + -recursive | Arbre du projet | Périmètre et journal par exécution |
cd C:\ghidra_12.1.3_PUBLIC\support
analyzeHeadless.bat D:\analysis\projects HeadlessDemo -import D:\analysis\samples\demo.exe./support/analyzeHeadless /srv/ghidra/projects HeadlessDemo -process demo.exeUtiliser des scripts sans perdre la reproductibilité
Les tâches headless sont plus utiles lorsqu’un script transforme l’état de l’analyse en un résultat court et vérifiable. Un pre-script peut préparer une opération de projet ; un post-script peut examiner le programme analysé et écrire un rapport. Gardez les scripts ciblés : afficher des fonctions, des chaînes, des imports ou un champ de métadonnées est plus simple à tester que de renommer silencieusement un grand projet.
Placez les scripts dans un dossier versionné et transmettez-le avec -scriptPath. Utilisez -preScript et -postScript et conservez les journaux. Si vous avez besoin de CPython en dehors de Ghidra, consultez le guide PyGhidra.
- Commencer par une tâche en lecture seule ou de rapport et un petit échantillon autorisé.
- Figer la révision du script à côté de la commande et de la version de Ghidra.
- Écrire les rapports hors du dossier du projet, sauf si le script doit enregistrer des données du projet.
- Tester un résultat vide et une seconde exécution.
Dossiers par lots, journaux et tâches CI
Pour un flux basé sur un dossier, décidez si les fichiers doivent partager un projet ou utiliser des projets isolés. Un projet unique facilite la navigation entre fichiers ; des projets séparés réduisent les mélanges accidentels. N’utilisez -recursive que lorsque les dossiers imbriqués font partie du périmètre, car un chemin trop large peut importer plus de données que prévu.
Consignez la commande, les versions, le manifeste, la révision du script, le code de sortie, les journaux et les sorties inattendues. En CI, archivez les rapports et échouez si le lanceur ou le post-script signale un problème.
La même commande peut produire des conclusions différentes si le dossier d’entrée, le profil du projet, les extensions, la révision du script ou la version de Ghidra changent. Notez ces limites à côté du rapport.
./support/analyzeHeadless /srv/ghidra/projects BatchSet -import /srv/ghidra/samples -recursive -scriptPath /srv/ghidra/scripts -postScript export_summary.pyrelease=12.1.3 input_manifest=sha256.csv script=export_summary.py@abc123 project=BatchSet log=run-2026-09-16.logLire le résultat et le vérifier dans Ghidra
Après une exécution headless, examinez le code de sortie et le journal avant d’ouvrir le projet. Vérifiez les messages du chargeur, le langage ou compilateur choisi, la fin de l’analyse, les exceptions de scripts, les fichiers ignorés et les échecs d’écriture. Ouvrez ensuite une copie dans l’interface graphique et vérifiez un petit échantillon dans Listing, les références, Decompiler ou les symboles. Le guide de recherche Ghidra et le guide Decompiler décrivent ces contrôles.
Un rapport est un artefact, pas une preuve suffisante. Si aucune chaîne n’est trouvée, confirmez le langage, le périmètre et l’objet d’API.
| Symptôme | Premier contrôle | Étape suivante prudente |
|---|---|---|
| Aucun programme n’apparaît | Mode d’import, chemin et chargeur | Exécuter un fichier avec un nouveau nom de projet |
| Script introuvable | Chemin et nom du fichier | Utiliser un dossier de scripts absolu et un script minimal |
| Analyse incomplète | Journal, délai, mémoire et messages | Réessayer un échantillon et comparer la copie du projet |
| Sortie différente de la GUI | Version, langage, options et phase du script | Vérifier le même programme et les mêmes réglages dans les deux voies |
FAQ de l’analyseur headless de Ghidra
Où se trouve analyzeHeadless dans Ghidra ?
Il se trouve dans le dossier support/ de l’installation Ghidra. Windows fournit analyzeHeadless.bat ; Linux et macOS utilisent le lanceur shell. Utilisez le lanceur correspondant à la version installée.
Quelle est la différence entre -import et -process ?
Utilisez -import lorsque la tâche commence avec des fichiers ou dossiers et doit créer ou compléter un projet. Utilisez -process lorsque les programmes sont déjà dans le projet et doivent être traités.
Ghidra peut-il analyser beaucoup de fichiers sans la GUI ?
Oui. L’analyseur headless peut importer ou traiter un dossier, et des options comme -recursive peuvent étendre le périmètre. Commencez par un petit ensemble autorisé et conservez le manifeste des entrées pour contrôler le résultat.
Puis-je exécuter un script avec analyzeHeadless ?
Oui. Utilisez les options de chemin de script, pre-script et post-script prises en charge par votre version. Versionnez les scripts, testez-les sur une copie et gardez journaux et rapports avec la commande.