Analizzatore headless di Ghidra: cos’è e quando usarlo
L’analizzatore headless di Ghidra è il punto di ingresso da riga di comando per eseguire analisi senza aprire l’applicazione desktop. Può creare o completare un progetto, analizzare programmi importati o già presenti ed eseguire script senza interfaccia per cartelle di campioni, triage del firmware, report programmati o pipeline controllate.
Headless non è un server remoto e non rende automatiche tutte le conclusioni. Il launcher dipende comunque dall’installazione di Ghidra, dal percorso del progetto, dai loader, dagli analizzatori, dagli script e dalle normali regole del progetto. Registra release, input, opzioni, progetto di output e log e analizza solo materiale per cui hai l’autorizzazione.
La documentazione ufficiale e il launcher support/analyzeHeadless della release installata definiscono le opzioni disponibili. Questa pagina descrive un flusso prudente, ma non sostituisce l’aiuto incluso nella tua versione di Ghidra.
Prepara installazione, progetto e file di input
Inizia con lo ZIP ufficiale di Ghidra e un JDK a 64 bit compatibile. La versione verificata per questo sito è Ghidra 12.1.3, pubblicata il 18 agosto 2026, e l’archivio include il launcher in support/. Se l’applicazione desktop non si avvia, consulta la guida all’installazione di Ghidra; un JDK non funzionante o un’estrazione incompleta blocca anche le esecuzioni headless.
Tieni separati applicazione, progetto e cartelle di input e report. Non modificare un progetto attivo da un job batch e non sovrascrivere una copia nota come corretta prima di controllare la nuova esecuzione. Usa un nome di progetto nuovo mentre provi script o opzioni di analisi.
- 1
Conferma il launcher
Nell’installazione di Ghidra, verifica che esista il launcher della tua piattaforma e che possa mostrare l’aiuto. Windows usa il file batch; macOS e Linux usano il launcher shell.
support/analyzeHeadless.bat OPPURE support/analyzeHeadless - 2
Scegli una radice di progetto scrivibile
Prevedi spazio sufficiente per programmi importati, database, cache e report. Evita una cartella sincronizzata mentre indaghi su blocchi o scritture concorrenti.
D:\analysis\projects /srv/ghidra/projects - 3
Registra gli input
Annota nomi dei file, hash, architetture previste e data di raccolta. Un percorso di directory non è un input riproducibile se non ne registri il contenuto.
samples/firmware-a.bin samples/firmware-b.bin - 4
Fai un backup prima di elaborare
Copia il progetto prima di eseguire uno script che rinomini simboli, modifichi tipi di dati, elimini programmi o salvi cambiamenti.
ProjectName.gpr + ProjectName.rep/
Scegli tra -import e -process
La scelta centrale dell’analizzatore headless è capire se il comando deve creare o completare un progetto da file, oppure riaprire programmi che si trovano già in un progetto. Usa -import quando un file o una directory deve diventare un insieme di programmi del progetto. Usa -process quando il progetto contiene già il programma.
Non aggiungere entrambe le modalità solo perché un esempio online le mostra insieme. Parti da un job spiegabile, specifica loader o processore solo quando serve e salva il comando riuscito in uno script versionato.
| Attività | Modalità | Input tipico | Cosa verificare |
|---|---|---|---|
| Creare un progetto dai binari | -import | File o directory | Loader, linguaggio e nome del progetto |
| Analizzare programmi già salvati | -process | Progetto esistente | Nomi dei programmi e copia del progetto |
| Eseguire uno script durante l’import | -import + -postScript | Nuovo set di input | Percorso dello script e output salvato |
| Elaborare un albero di programmi | -process + -recursive | Albero del progetto | Ambito e log per ogni esecuzione |
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.exeUsa gli script senza perdere la ripetibilità
I job headless sono più utili quando uno script trasforma lo stato dell’analisi in un risultato piccolo e verificabile. Un pre-script può preparare un’azione del progetto; un post-script può esaminare il programma analizzato e scrivere un report. Mantieni gli script mirati: stampare funzioni, stringhe, import o un campo di metadati è più facile da testare che rinominare silenziosamente un progetto grande.
Metti gli script in una directory versionata e passala con -scriptPath. Usa -preScript e -postScript e conserva i log. Se ti serve CPython fuori da Ghidra, consulta la guida PyGhidra.
- Inizia con un’attività di sola lettura o di generazione report e un piccolo campione autorizzato.
- Fissa la revisione dello script accanto al comando e alla release di Ghidra.
- Scrivi i report fuori dalla directory del progetto, salvo che lo script debba salvare dati del progetto.
- Prova un risultato vuoto, un campo mancante e una seconda esecuzione.
- Confronta il progetto di backup prima di accettare modifiche a simboli o tipi di dati.
Directory batch, log e job CI
Per un flusso basato su directory, decidi se i file devono condividere un progetto o usare progetti isolati. Un progetto unico facilita la navigazione tra file; progetti separati riducono il rischio di mescolare dati. Usa -recursive solo quando le cartelle annidate fanno parte dell’ambito, perché un percorso ampio può importare più dati del previsto.
Registra comando, versioni, manifesto, revisione dello script, stato di uscita, log e risultati inattesi. In CI archivia i report e segnala un errore se launcher o post-script rilevano un problema.
Lo stesso comando può produrre conclusioni diverse se cambiano cartella di input, profilo del progetto, estensioni, revisione dello script o release di Ghidra. Registra questi confini accanto al report.
./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.logLeggi il risultato e verificalo in Ghidra
Dopo un’esecuzione headless, controlla lo stato di uscita e il log prima di aprire il progetto. Verifica messaggi del loader, linguaggio o compilatore scelto, completamento dell’analisi, eccezioni degli script, file saltati ed errori di scrittura. Poi apri una copia nella GUI e controlla un piccolo campione in Listing, riferimenti, Decompiler o simboli. La guida alla ricerca in Ghidra e la guida al Decompiler descrivono questi controlli.
Un report è un artefatto, non una prova da solo. Se non trovi stringhe, controlla linguaggio, ambito e oggetto API.
| Sintomo | Primo controllo | Passo successivo sicuro |
|---|---|---|
| Non compare alcun programma | Modalità di import, percorso e loader | Esegui un file con un nuovo nome di progetto |
| Lo script non viene trovato | Percorso e nome del file | Usa una directory assoluta e uno script di prova minimo |
| L’analisi è incompleta | Log, timeout, memoria e messaggi | Ripeti un campione e confronta la copia del progetto |
| L’output differisce dalla GUI | Release, linguaggio, opzioni e fase dello script | Verifica lo stesso programma e le stesse impostazioni in entrambi i percorsi |
Analizzatore headless, Script Manager e PyGhidra
L’analizzatore headless è il confine dei job CLI. Script Manager esegue script nell’applicazione Ghidra visibile. PyGhidra collega un processo CPython esterno all’API di Ghidra. Possono comparire nella stessa indagine, ma appartengono a runtime diversi.
Usa la GUI per un programma con feedback visivo, l’analizzatore headless per import o job di progetto ripetibili e PyGhidra quando il requisito principale è un processo Python esterno.
| Confine dello strumento | Uso migliore | Precauzione principale |
|---|---|---|
| Analizzatore headless | Import CLI e job batch | Registra progetto, release, script e log |
| Script Manager | Script nell’applicazione visibile | Contesto e progetto correnti sono importanti |
| PyGhidra | Automazione con CPython esterno | Verifica la compatibilità tra Python e Ghidra |
FAQ dell’analizzatore headless di Ghidra
Dove si trova analyzeHeadless in Ghidra?
Si trova nella directory support/ dell’installazione di Ghidra. Windows include analyzeHeadless.bat; Linux e macOS usano il launcher shell. Usa il launcher della release installata.
Qual è la differenza tra -import e -process?
Usa -import quando il job parte da file o directory e deve creare o completare un progetto. Usa -process quando i programmi sono già nel progetto e devono essere elaborati.
Ghidra può analizzare molti file senza la GUI?
Sì. L’analizzatore headless può importare o elaborare una directory e opzioni come -recursive possono estendere l’ambito. Inizia con un set piccolo e autorizzato e registra il manifesto per controllare il risultato.
Posso eseguire uno script con analyzeHeadless?
Sì. Usa le opzioni per percorso script, pre-script e post-script supportate dalla release installata. Versiona gli script, provali su una copia e conserva log e report accanto al registro del comando.
L’analizzatore headless richiede un progetto Ghidra?
Il launcher usa una posizione e un nome di progetto. Un job di import può creare o completare i dati, mentre un job process si aspetta programmi già presenti. Mantieni il percorso scrivibile e separato dalla directory dell’applicazione.
L’analizzatore headless è uguale a PyGhidra?
No. L’analizzatore headless è il launcher CLI per import, elaborazione di progetti e script Ghidra. PyGhidra collega un processo CPython esterno all’API Ghidra. Scegli il confine adatto alla tua automazione.