Headless Binary Ninja MCP server — fornendo agli agenti AI profonde capacità di reverse engineering tramite 180 strumenti.
Un server Binary Ninja headless che parla MCP (Model Context Protocol), fornendo agli agenti AI pieno accesso a flussi di lavoro complessi di reverse engineering — disassemblaggio, IL, patching, tipi, xref e altro — senza GUI.
Progettato per funzionare nello stesso container Docker del runtime dell'agente. Niente sidecar, niente servizi aggiuntivi.
L'intero progetto — codice, test e documentazione — è realizzato al 100% con vibe coding.
I server MCP per Binary Ninja esistenti sono legati alla GUI o espongono una superficie strumentale limitata. Questo server è solo headless e progettato per flussi di lavoro guidati da agenti in ambienti VM/container sandbox: l'agente ha il pieno controllo del sistema di analisi, automatizzando gran parte del reverse engineering mentre tu interagisci e guidi il processo in modo interattivo.
L'obiettivo è un'interfaccia in cui gli agenti possano ispezionare, perfezionare ed estendere un'analisi nel tempo — aggiornando tipi, simboli e metadati, migliorando incrementalmente il database di analisi, applicando patch e iterando in modo sicuro con undo/redo, ed eseguendo script personalizzati quando un flusso di lavoro necessita di qualcosa di ad hoc.
binja.eval e binja.call per tutto ciò che il catalogo strumenti non copre.3.11+binaryninja importabile nel tuo runtime (per analisi reali)git clone https://github.com/mrphrazer/binary-ninja-headless-mcp.git
cd binary-ninja-headless-mcp
pip install .
Oppure installa direttamente dalla root del repository senza clonare:
pip install git+https://github.com/mrphrazer/binary-ninja-headless-mcp.git
Trasporto Stdio (default):
python3 binary_ninja_headless_mcp.py
Trasporto TCP:
python3 binary_ninja_headless_mcp.py --transport tcp --host 127.0.0.1 --port 8765
Modalità backend fittizio (nessun Binary Ninja richiesto):
python3 binary_ninja_headless_mcp.py --fake-backend
Questo server parla MCP standard su stdio (default) o tcp, quindi qualsiasi host agente compatibile con MCP può utilizzarlo.
claude mcp add binary_ninja_headless_mcp -- python3 /path/to/binary-ninja-headless-mcp/binary_ninja_headless_mcp.py
Oppure aggiungilo al .mcp.json del tuo progetto:
{
"mcpServers": {
"binary_ninja_headless_mcp": {
"command": "python3",
"args": ["binary_ninja_headless_mcp.py"],
"cwd": "/path/to/binary-ninja-headless-mcp"
}
}
}
codex mcp add binary_ninja_headless_mcp -- python3 binary_ninja_headless_mcp.py
binary_ninja_headless_mcp.python3 con argomenti ["binary_ninja_headless_mcp.py"] quando cwd è la root del repository, oppure usa un percorso assoluto dello script in args.cwd sul percorso del repo se vuoi che percorsi relativi come samples/ls vengano risolti correttamente.--fake-backend.health.ping, poi session.open.Modello di deployment consigliato: esegui il processo agente e questo server MCP nella stessa immagine container.
Esempio base:
FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN python -m pip install --upgrade pip && pip install ruff pytest
CMD ["python3", "binary_ninja_headless_mcp.py"]
Se hai bisogno di analisi reale con Binary Ninja all'interno del container, aggiungi il tuo runtime Binary Ninja + configurazione licenza nella stessa immagine e avvia l'agente con questo server MCP configurato.
initializepingtools/listtools/callshutdownComportamento di tools/list:
offset o limit, usa output paginato (offset=0, limit=50 di default in modalità paginata).prefix (ad esempio binary.)query (corrispondenza parziale su nome/descrizione dello strumento)offset, limit, total, has_more.has_more=true), include next_offset e un suggerimento notice.Comportamento della risposta alle chiamate strumento:
structuredContent è il payload completo canonico.content[0].text è una stringa riassuntiva compatta (non una duplicazione JSON completa).Questo repository è ben testato e ha gate di qualità obbligatori.
pytest --collect-only -q per il conteggio corrente dei test raccolti.ruff format --check .ruff check .pytestBINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 in modo che i controlli vengano eseguiti senza richiedere l'installazione di Binary Ninja.read_only=true).binary.basic_blocks_at e function.basic_blocks sono paginati (offset/limit).memory.read ha un limite massimo di risposta: length <= 65536.stdio/tcp) non è autenticata di default.binja.eval e ampio accesso API tramite binja.call.ruff format --check .
ruff check .
BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pytest -q
## Fuzzer di Funzionalità
Usa il fuzzer MCP integrato per testare un'ampia superficie strumentale su `samples/ls`.
Backend Binary Ninja reale:
```bash
python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --iterations 120 --seed 1337
Esecuzione di prova con backend fittizio:
python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --fake-backend --iterations 20
Scrivi un report di copertura JSON:
python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --report-json /tmp/mcp-fuzzer-report.json
Flag utili:
--min-success-tools N: esce con codice diverso da zero se meno di N strumenti hanno successo.--verbose: stampa ogni chiamata strumento durante il fuzzing.--update-analysis: apre la sessione seed con update_analysis=true.Il server espone attualmente 181 strumenti in 36 gruppi di funzionalità.
analysis.status: Ottieni stato dell'analisi.analysis.progress: Ottieni snapshot del progresso dell'analisi.analysis.update: Attiva aggiornamento asincrono dell'analisi.analysis.update_and_wait: Esegui aggiornamento analisi e attendi il completamento.analysis.abort: Interrompi analisi.analysis.set_hold: Metti in attesa/rilascia coda di analisi.annotation.rename_function: Rinomina una funzione.annotation.rename_symbol: Rinomina simbolo all'indirizzo.annotation.undefine_symbol: Annulla definizione simbolo utente all'indirizzo.annotation.define_symbol: Definisci simbolo all'indirizzo.annotation.rename_data_var: Rinomina variabile dati.annotation.define_data_var: Definisci variabile dati.annotation.undefine_data_var: Annulla definizione variabile dati.annotation.set_comment: Imposta commento all'indirizzo.annotation.get_comment: Ottieni commento all'indirizzo.annotation.add_tag: Aggiungi tag dati utente all'indirizzo.annotation.get_tags: Ottieni tag all'indirizzo.arch.info: Ottieni metadati architettura e piattaforma.arch.disasm_bytes: Disassembla byte con architettura selezionata.arch.assemble: Assembla testo istruzioni con architettura selezionata.baseaddr.detect: Esegui rilevamento indirizzo base.baseaddr.reasons: Ottieni motivi rilevamento indirizzo base.baseaddr.abort: Interrompi rilevamento indirizzo base.binary.summary: Ottieni riepilogo binario/sessione.binary.save: Salva la vista binaria corrente in un percorso file.binary.functions: Elenca funzioni con paginazione.binary.strings: Elenca stringhe scoperte con paginazione.binary.search_text: Cerca testo/byte grezzi in una sessione.binary.sections: Elenca sezioni con paginazione.binary.segments: Elenca segmenti con paginazione.binary.symbols: Elenca simboli con paginazione.binary.data_vars: Elenca variabili dati con paginazione.binary.get_function_at: Trova funzione per indirizzo.binary.get_function_disassembly_at: Ottieni disassemblaggio completo per la funzione contenente un indirizzo.binary.get_function_il_at: Ottieni IL completo per la funzione contenente un indirizzo.binja.info: Restituisci versione/info installazione Binary Ninja.binja.call: Ponte API generico: chiama percorso target bn.* o bv.*.binja.eval: Valuta codice Python con bn, sessions e bv opzionale.data.typed_at: Ottieni variabile dati tipizzata a un indirizzo.database.create_bndb: Crea .bndb dalla sessione.database.save_auto_snapshot: Salva snapshot automatico.database.info: Ottieni stato database per sessione.database.snapshots: Elenca snapshot database.database.read_global: Leggi chiave stringa globale database.database.write_global: Scrivi chiave stringa globale database.debug.parsers: Elenca parser info debug validi per questa vista.debug.parse_and_apply: Analizza info debug e applicale alla vista.disasm.linear: Ottieni righe di disassemblaggio lineare.disasm.function: Ottieni disassemblaggio completo per funzione contenente un indirizzo.disasm.range: Righe di disassemblaggio per intervallo di indirizzi.external.library_add: Aggiungi libreria esterna.external.library_list: Elenca librerie esterne.external.library_remove: Rimuovi libreria esterna.external.location_add: Aggiungi mappatura posizione esterna.external.location_get: Ottieni mappatura posizione esterna.external.location_remove: Rimuovi mappatura posizione esterna.function.basic_blocks: Elenca blocchi di base in una funzione con paginazione.function.callers: Chiamanti di una funzione.function.callees: Chiamati di una funzione.function.variables: Elenca variabili funzione.function.var_refs: Elenca riferimenti a variabili in MLIL/HLIL.function.var_refs_from: Elenca riferimenti variabili originati da un indirizzo.function.ssa_var_def_use: Ottieni definizione e usi variabile SSA.function.ssa_memory_def_use: Ottieni definizione e usi memoria SSA per versione memoria.function.metadata_store: Archivia metadati funzione per chiave.function.metadata_query: Interroga metadati funzione per chiave.function.metadata_remove: Rimuovi metadati funzione per chiave.health.ping: Controllo di integrità.il.function: Elenco IL funzione.il.instruction_by_addr: Ottieni istruzione IL per indirizzo sorgente.il.address_to_index: Mappa indirizzo a indice/indici IL.il.index_to_address: Mappa indice IL a indirizzo sorgente.il.rewrite.capabilities: Elenca supporto riscrittura IL per una funzione e livello IL.il.rewrite.noop_replace: Esegui sostituzione espressione IL con NOP.il.rewrite.translate_identity: Traduci IL con callback mappatura identità.loader.rebase: Cambia base di BinaryView.loader.load_settings_types: Elenca nomi tipi impostazioni loader.loader.load_settings_get: Ottieni valori impostazioni loader.loader.load_settings_set: Imposta un valore impostazione loader.memory.read: Leggi byte dalla vista (length <= 65536).memory.write: Scrivi byte (hex) nella vista.memory.insert: Inserisci byte (hex) nella vista.memory.remove: Rimuovi byte dalla vista.memory.reader_read: Leggi valori interi tramite BinaryReader.memory.writer_write: Scrivi valori interi tramite BinaryWriter.mcp.response_format: Spiega campi risultato strumento (structuredContent payload completo, content[0].text riepilogo).metadata.store: Archivia metadati per chiave.metadata.query: Interroga metadati per chiave.metadata.remove: Rimuovi metadati per chiave.patch.assemble: Assembla e applica patch byte istruzione all'indirizzo.patch.status: Ispeziona disponibilità patch all'indirizzo.patch.convert_to_nop: Applica patch all'istruzione in NOP quando supportato.patch.always_branch: Applica patch al salto condizionale per saltare sempre quando supportato.patch.never_branch: Applica patch al salto condizionale per non saltare mai quando supportato.patch.invert_branch: Applica patch al salto condizionale invertendolo quando supportato.patch.skip_and_return_value: Applica patch all'istruzione per saltare e restituire valore quando supportato.plugin.valid_commands: Elenca comandi plugin validi per contesto.plugin.execute: Esegui un comando plugin valido per contesto.plugin_repo.status: Elenca repository plugin e stati plugin.plugin_repo.check_updates: Controlla aggiornamenti repository plugin.plugin_repo.plugin_action: Esegui azione installa/disinstalla/abilita/disabilita su plugin del repository.project.create: Crea progetto.project.open: Apri progetto.project.close: Chiudi progetto tracciato.project.list: Elenca cartelle/file progetto.project.create_folder: Crea cartella progetto.project.create_file: Crea file progetto da dati base64.project.metadata_store: Archivia metadati progetto.project.metadata_query: Interroga metadati progetto.project.metadata_remove: Rimuovi metadati progetto.search.data: Cerca pattern byte grezzi (stringa hex).search.next_text: Trova corrispondenza testo successiva.search.all_text: Trova tutte le corrispondenze testo nell'intervallo (regex opzionale).search.next_data: Trova corrispondenza dati/pattern byte successiva.search.all_data: Trova tutte le corrispondenze dati/pattern byte nell'intervallo.search.next_constant: Trova occorrenza costante successiva.search.all_constant: Trova tutte le occorrenze costanti nell'intervallo.section.add_user: Aggiungi sezione utente.section.remove_user: Rimuovi sezione utente.segment.add_user: Aggiungi segmento utente.segment.remove_user: Rimuovi segmento utente.session.open: Apri un binario e crea una sessione.session.open_bytes: Apri una sessione binaria da byte codificati in base64.session.open_existing: Apri un'altra sessione dal file di una sessione esistente.session.close: Chiudi una sessione aperta.session.list: Elenca sessioni aperte.session.mode: Ottieni modalità sicurezza/determinismo sessione.session.set_mode: Aggiorna modalità sicurezza/determinismo sessione.task.analysis_update: Avvia task asincrono di aggiornamento analisi.task.search_text: Avvia task asincrono di ricerca.task.status: Ottieni stato task.task.result: Ottieni risultato task.task.cancel: Annulla task (best-effort).transform.inspect: Ispeziona/elabora pipeline di estrazione trasformazione.type.parse_string: Analizza una singola stringa di tipo.type.parse_declarations: Analizza dichiarazioni C per tipi/variabili/funzioni.type.define_user: Definisci tipo utente da sorgente tipo.type.rename: Rinomina un tipo.type.undefine_user: Annulla definizione tipo utente.type.import_library_type: Importa tipo da libreria tipi.type.import_library_object: Importa tipo oggetto da libreria tipi.type.export_to_library: Esporta tipo in una libreria tipi.type_archive.create: Crea e opzionalmente allega un archivio tipi.type_archive.open: Apri e opzionalmente allega un archivio tipi.type_archive.list: Elenca archivi tipi allegati.type_archive.get: Ottieni un archivio tipi tracciato.type_archive.pull: Estrai tipi da un archivio tipi.type_archive.push: Invia tipi a un archivio tipi.type_archive.references: Interroga riferimenti entranti/uscenti dell'archivio per un tipo.type_library.create: Crea e opzionalmente allega una libreria tipi.type_library.load: Carica e opzionalmente allega una libreria tipi.type_library.list: Elenca librerie tipi allegate alla vista.type_library.get: Ottieni una libreria tipi tracciata.uidf.parse_possible_value: Analizza stringa set valori possibili fornita dall'utente.uidf.set_user_var_value: Imposta valore variabile utente funzione.uidf.clear_user_var_value: Cancella valore variabile utente funzione.uidf.list_user_var_values: Elenca tutti i valori variabili utente per una funzione.undo.begin: Inizia transazione undo.undo.commit: Conferma transazione undo.undo.revert: Annulla transazione undo.undo.undo: Esegui undo.undo.redo: Esegui redo.value.reg: Ottieni valore registro a/dopo un indirizzo.value.stack: Ottieni contenuto stack a/dopo un indirizzo.value.possible: Ottieni set valori possibili IL a un indirizzo.value.flags_at: Ottieni stato lettura/scrittura flag IL sollevati a un indirizzo.workflow.list: Elenca flussi di lavoro registrati.workflow.describe: Descrivi topologia e impostazioni flusso di lavoro.workflow.clone: Clona flusso di lavoro.workflow.insert: Inserisci attività prima di un'attività.workflow.insert_after: Inserisci attività dopo un'attività.workflow.remove: Rimuovi attività dal flusso di lavoro.workflow.graph: Riepiloga grafo del flusso di lavoro.workflow.machine.status: Ottieni stato macchina del flusso di lavoro.workflow.machine.control: Controlla runtime della macchina del flusso di lavoro.xref.code_refs_to: Riferimenti codice a un indirizzo.xref.code_refs_from: Riferimenti codice da un indirizzo.xref.data_refs_to: Riferimenti dati a un indirizzo.xref.data_refs_from: Riferimenti dati da un indirizzo.Per maggiori informazioni, contatta Tim Blazytko (@mr_phrazer).
binary.functions_at: Elenca funzioni a un indirizzo.binary.basic_blocks_at: Elenca blocchi di base a un indirizzo con paginazione.