Ghidra Headless Analyzer: Was er ist und wann er passt
Der Ghidra Headless Analyzer ist der Kommandozeilen-Einstiegspunkt für Ghidra-Analysen ohne Desktop-Oberfläche. Er kann ein Projekt anlegen oder ergänzen, importierte oder vorhandene Programme analysieren und GUI-freie Skripte für Sample-Ordner, Firmware-Triage, geplante Berichte oder kontrollierte Build-Pipelines ausführen.
Headless ist kein Remote-Server und macht nicht jede Schlussfolgerung automatisch. Der Starter hängt weiterhin von der Ghidra-Installation, dem Projektpfad, Loadern, Analyzern, Skripten und den normalen Projektregeln ab. Notieren Sie Release, Eingaben, Optionen, Ausgabeprojekt und Log und analysieren Sie nur Material, für das Sie berechtigt sind.
Die offizielle Dokumentation und der zur installierten Version gehörende support/analyzeHeadless-Starter bestimmen die verfügbaren Optionen. Diese Seite beschreibt einen sicheren Ablauf, ersetzt aber nicht die Hilfe Ihrer Ghidra-Version.
Installation, Projekt und Eingabedateien vorbereiten
Beginnen Sie mit dem offiziellen Ghidra-ZIP und einem passenden 64-Bit-JDK. Die für diese Website geprüfte Version ist Ghidra 12.1.3, veröffentlicht am 18. August 2026; das Archiv enthält den Starter unter support/. Falls die Desktop-Anwendung nicht startet, hilft der Ghidra-Installationsleitfaden. Ein fehlerhaftes JDK oder eine unvollständige Extraktion stört auch Headless-Läufe.
Halten Sie Anwendung, Projekt sowie Eingabe- und Berichtsordner getrennt. Bearbeiten Sie kein Live-Projekt aus einem Batch-Job heraus und überschreiben Sie keine bekannte funktionierende Kopie, bevor Sie den neuen Lauf geprüft haben. Verwenden Sie beim Testen von Skripten oder Analyzer-Optionen einen neuen Projektnamen.
- 1
Starter prüfen
Prüfen Sie in der Ghidra-Installation, ob der Starter für Ihre Plattform vorhanden ist und Hilfe ausgeben kann. Windows verwendet die Batch-Datei, macOS und Linux den Shell-Starter.
support/analyzeHeadless.bat ODER support/analyzeHeadless - 2
Schreibbaren Projektpfad wählen
Planen Sie ausreichend Platz für importierte Programme, Datenbanken, Caches und Berichte ein. Vermeiden Sie beim Untersuchen von Sperren oder parallelen Schreibvorgängen zunächst synchronisierte Ordner.
D:\analysis\projects /srv/ghidra/projects - 3
Eingaben protokollieren
Halten Sie Dateinamen, Hashes, angenommene Architekturen und das Sammeldatum fest. Ein Verzeichnispfad ist ohne Inhaltsmanifest keine reproduzierbare Eingabe.
samples/firmware-a.bin samples/firmware-b.bin - 4
Vor der Verarbeitung sichern
Kopieren Sie das Projekt, bevor ein Skript Symbole umbenennt, Datentypen ändert, Programme löscht oder Projektänderungen speichert.
ProjectName.gpr + ProjectName.rep/
-import oder -process auswählen
Die wichtigste Headless-Entscheidung lautet, ob der Befehl aus Eingabedateien ein Projekt erstellen oder ergänzen soll oder ob Programme verarbeitet werden, die bereits in einem Projekt liegen. Verwenden Sie -import für eine Datei oder ein Verzeichnis, das zu Projektprogrammen werden soll. Verwenden Sie -process, wenn das Projekt das Programm bereits enthält.
Fügen Sie nicht beide Modi hinzu, nur weil ein Online-Beispiel sie gemeinsam zeigt. Beginnen Sie mit einem nachvollziehbaren Job, geben Sie Loader oder Prozessor nur bei Bedarf an und speichern Sie den erfolgreichen Befehl in einem versionierten Skript.
| Aufgabe | Modus | Typische Eingabe | Zu prüfen |
|---|---|---|---|
| Projekt aus Binärdateien erstellen | -import | Datei oder Verzeichnis | Loader, Sprache und Projektname |
| Vorhandene Programme analysieren | -process | Vorhandenes Projekt | Programmnamen und Projektkopie |
| Skript während des Imports ausführen | -import + -postScript | Neue Eingabemenge | Skriptpfad und gespeicherte Ausgabe |
| Projektbaum verarbeiten | -process + -recursive | Vorhandener Projektbaum | Geltungsbereich und Log je Lauf |
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.exeSkripte einsetzen, ohne die Wiederholbarkeit zu verlieren
Headless-Jobs werden nützlicher, wenn ein Skript den Analysezustand in ein kleines, prüfbares Ergebnis überführt. Ein Pre-Skript kann eine Projektaktion vorbereiten; ein Post-Skript kann das analysierte Programm untersuchen und einen Bericht schreiben. Halten Sie Skripte eng begrenzt: Funktionen, Strings, Imports oder ein Metadatenfeld auszugeben ist leichter zu testen, als ein großes Projekt unbemerkt umzubenennen.
Legen Sie Skripte in einem versionierten Verzeichnis ab und übergeben Sie es mit -scriptPath. Verwenden Sie -preScript und -postScript, um die Hooks klar zu machen, und sichern Sie die unterstützten Logs. Wenn Sie CPython außerhalb von Ghidra brauchen, lesen Sie den PyGhidra-Leitfaden; die Automatisierungsgrenzen hängen zusammen, sind aber unterschiedliche Laufzeiten.
- Mit einer lesenden oder berichtenden Aufgabe und einem kleinen autorisierten Sample beginnen.
- Skript-Revision neben Befehl und Ghidra-Release festhalten.
- Berichte außerhalb des Projektverzeichnisses schreiben, außer das Skript muss Projektdaten speichern.
- Leeres Ergebnis, fehlendes Feld, nicht unterstützten Programmtyp und einen zweiten Lauf testen.
- Das gesicherte Projekt vergleichen, bevor Änderungen an Symbolen oder Datentypen übernommen werden.
Batch-Verzeichnisse, Logs und CI-Jobs
Entscheiden Sie bei einem Verzeichnis-Workflow, ob Dateien ein Projekt teilen oder in isolierten Projekten verarbeitet werden. Ein Projekt erleichtert die Navigation zwischen Dateien; getrennte Projekte verringern versehentliche Vermischung. Verwenden Sie -recursive nur, wenn verschachtelte Ordner wirklich zum Umfang gehören, denn ein weiter Pfad kann mehr Daten importieren als beabsichtigt.
Protokollieren Sie Befehl, Ghidra-Release, Java-Version, Eingabemanifest, Skript-Revision, Exit-Status, Logs, Projektpfad und Dateien mit unerwarteten Ergebnissen. Archivieren Sie in CI Logs und Berichte und lassen Sie den Job fehlschlagen, wenn Starter oder Post-Skript einen Fehler melden. Ein erfolgreicher Prozess beweist nicht, dass jede erwartete Funktion oder Zeichenkette gefunden wurde.
Dasselbe Kommando kann andere Schlussfolgerungen liefern, wenn Eingabeordner, Projektprofil, Erweiterungen, Skript-Revision oder Ghidra-Release wechseln. Halten Sie diese Grenzen neben dem Bericht fest.
./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.logErgebnis lesen und in Ghidra verifizieren
Prüfen Sie nach einem Headless-Lauf Exit-Status und Log, bevor Sie das Projekt öffnen. Achten Sie auf Loader-Meldungen, gewählte Sprache oder Compiler, abgeschlossene Analyse, Skript-Ausnahmen, übersprungene Dateien und Schreibfehler. Öffnen Sie anschließend eine Kopie in der GUI und prüfen Sie eine kleine Auswahl in Listing, Referenzen, Decompiler oder Symbolen. Der Ghidra-Suchleitfaden und der Decompiler-Leitfaden helfen bei diesen Kontrollen.
Ein Bericht ist ein Ausgabe-Artefakt, aber allein kein Beweis. Wenn ein Skript keine Strings findet, prüfen Sie Sprache, Umfang und API-Objekt. Bewahren Sie Eingabemanifest und exakten Laufdatensatz neben den gespeicherten Projektdaten auf.
| Symptom | Erste Prüfung | Sicherer nächster Schritt |
|---|---|---|
| Kein Programm erscheint | Importmodus, Pfad und Loader | Eine Datei mit neuem Projektnamen ausführen |
| Skript wird nicht gefunden | Skriptpfad und Dateiname | Absoluten Skriptordner und kleines Testskript verwenden |
| Analyse bleibt unvollständig | Log, Timeout, Speicher und Meldungen | Ein Sample erneut ausführen und Projektkopie vergleichen |
| Ausgabe weicht von der GUI ab | Release, Sprache, Optionen und Skriptphase | Dasselbe Programm und dieselben Einstellungen in beiden Wegen prüfen |
Headless Analyzer, Script Manager und PyGhidra im Vergleich
Der Headless Analyzer ist die CLI-Grenze für Jobs. Script Manager führt Skripte in der sichtbaren Ghidra-Anwendung aus. PyGhidra verbindet einen externen CPython-Prozess mit der Ghidra-API. Die Werkzeuge können in einer Untersuchung zusammen vorkommen, sind aber unterschiedliche Laufzeitgrenzen.
Nutzen Sie die GUI für ein Programm mit visueller Rückmeldung, den Headless Analyzer für wiederholbare Imports oder Projektjobs und PyGhidra, wenn ein externer Python-Prozess das eigentliche Ziel ist.
| Werkzeuggrenze | Geeignet für | Wichtigste Vorsicht |
|---|---|---|
| Headless Analyzer | CLI-Batch-Imports und Projektjobs | Projekt, Release, Skripte und Logs dokumentieren |
| Script Manager | Skripte in der sichtbaren Anwendung | Aktueller Kontext und aktuelles Projekt sind entscheidend |
| PyGhidra | Automatisierung mit externem CPython | Python- und Ghidra-Kompatibilität prüfen |
Ghidra Headless Analyzer FAQ
Wo befindet sich analyzeHeadless in Ghidra?
Der Starter liegt im support/-Verzeichnis der Ghidra-Installation. Windows enthält analyzeHeadless.bat; Linux und macOS verwenden den Shell-Starter. Verwenden Sie den Starter aus dem installierten Release.
Was ist der Unterschied zwischen -import und -process?
Verwenden Sie -import, wenn ein Job mit Dateien oder Verzeichnissen beginnt und ein Projekt erstellen oder ergänzen soll. Verwenden Sie -process, wenn Programme bereits im Projekt vorhanden sind.
Kann Ghidra viele Dateien ohne GUI analysieren?
Ja. Der Headless Analyzer kann ein Verzeichnis importieren oder verarbeiten; Optionen wie -recursive können den geplanten Umfang erweitern. Beginnen Sie mit einer kleinen autorisierten Menge und dokumentieren Sie das Manifest.
Kann ich mit analyzeHeadless ein Skript ausführen?
Ja. Nutzen Sie die von Ihrem Release unterstützten Optionen für Script-Pfad, Pre-Skript und Post-Skript. Versionieren Sie die Skripte, testen Sie sie an einer Kopie und speichern Sie Logs und Berichte neben dem Laufdatensatz.
Benötigt der Headless Analyzer ein Ghidra-Projekt?
Der Starter verwendet einen Projektpfad und Projektnamen. Ein Import-Job kann Projektdaten erstellen oder ergänzen, während ein Process-Job vorhandene Programme erwartet. Der Pfad muss beschreibbar und von der Anwendung getrennt sein.
Ist der Headless Analyzer dasselbe wie PyGhidra?
Nein. Der Headless Analyzer ist der CLI-Starter für Imports, Projektverarbeitung und Ghidra-Skripte. PyGhidra verbindet einen externen CPython-Prozess mit der API. Wählen Sie die Grenze passend zu Ihrer Automatisierung.