numbat

Visibilité sur les points de terminaison de l'activité des agents IA, avec détection locale, blocage optionnel avant action et reconstruction forensique.

numbat observe les agents pris en charge sur desktop, CLI, IDE et passerelle via des hooks et plugins locaux, des journaux OTLP/HTTP et des artefacts de session sur disque. L'activité en direct et au repos est normalisée dans un modèle d'événement unique et évaluée par le même moteur de règles CEL. La détection s'exécute localement ; les enregistrements peuvent être écrits sur stdout ou dans un fichier local et éventuellement transmis via HTTP.

La matrice de couverture fait autorité pour chaque hôte et surface. Le blocage est désactivé par défaut et limité aux hooks synchrones pré-action pris en charge ; voir le guide d'application.

Fonctionnalités

• Surveillance en direct via des hooks, des plugins et des exportateurs de journaux OTLP/HTTP.
• Détection locale au point de terminaison avec des règles CEL intégrées, des règles de séquence multi-étapes et des règles YAML personnalisées.
• Blocage opt-in via les hooks pré-action pris en charge. Le mode d'application est désactivé par défaut et ne s'applique qu'aux règles marquées enforce: true ; toutes les règles fournies sont en surveillance seule.
• Reconstruction forensique à partir des artefacts de session sur disque pris en charge, sans instrumentation préalable de numbat.
• Enregistrements NDJSON versionnés pour les événements, les constats, les décisions d'application, les indicateurs et les résumés d'analyse. Les événements et les constats conservent les références sources ; les schémas JSON définissent le format d'échange.
• Analyse d'artefacts en lecture seule avec masquage des secrets. La sortie normale des enregistrements n'inclut jamais une transcription brute complète ; l'ajout de fichiers de preuves brutes à un bundle de cas est opt-in.
• Outils d'inventaire et d'investigation pour la découverte d'agents en lecture seule, les chronologies par session et les bundles de cas portables avec manifestes SHA-256.
• Distribution en binaire unique pour macOS, Linux et Windows, compilé sans cgo.

Démarrage rapide

Installation

Téléchargez une version pour macOS, Linux ou Windows sur amd64 ou arm64. Chaque version inclut des sommes de contrôle SHA-256. Vous pouvez également installer avec Go 1.26.10 ou plus récent :

go install github.com/perplexityai/numbat/cmd/numbat@latest

CGO_ENABLED=0 go build -trimpath -o numbat ./cmd/numbat

$env:CGO_ENABLED = "0"
go build -trimpath -o numbat.exe ./cmd/numbat

Inventaire et analyse

Ces commandes en lecture seule n'installent pas de hooks et ne modifient pas la configuration de l'agent :

numbat agents
# scan all discovered parser-backed agents
numbat scan
# or limit automatic discovery to Codex
numbat scan --agent codex

scan émet des résultats par défaut. Utilisez numbat scan --emit all pour inclure les événements et les indicateurs. Consultez content capture pour les modes de sortie preview, full et raw.

Surveiller et appliquer

Installez la surveillance en direct pour tout agent avec live-capture support ; les commandes ci-dessous utilisent Codex comme exemple concret. Les hooks démarrent en mode monitor-only. --emit all écrit les événements, les résultats, les indicateurs et les décisions d'application applicables dans ~/.numbat/records.ndjson.

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

Après avoir mis à jour numbat, relancez hook install pour chaque agent installé avec les mêmes options. Cela met à jour les hooks et plugins générés ; vérifiez à nouveau la confiance de l'hôte si leurs définitions changent.

Confiance des hooks : Les exigences varient selon l'agent et la portée. Pour le hook utilisateur Codex ci-dessus, examinez et approuvez sa définition actuelle dans /hooks (CLI) ou Settings > Hooks (application), y compris après des modifications telles que --enforce. Les hooks Codex installés avec --managed sont approuvés par politique. hook status vérifie la configuration, pas l'exécution ni la livraison. Consultez le guide de déploiement pour les autres agents et portées.

Toutes les règles fournies sont en mode surveillance uniquement. Pour appliquer une détection, copiez son YAML fourni complet dans un répertoire opérateur contrôlé, conservez le même id, ajoutez enforce: true et incrémentez sa version. Validez et installez cette politique effective pour un hook pré-action pris en charge :

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

Exemple de sortie

{
  "actor": "assistant",
  "confidence": "medium",
  "content_preview": "http://169.254.169.254/latest/meta-data/iam/security-credentials/",
  "endpoint": {
    "hostname": "developer-workstation", "os": "linux", "arch": "arm64",
    "username": "node", "uid": "1000"
  },
  "event_id": "hook-run-20260724T151125.690671167-fa0a4148090fa1ba",
  "event_type": "network.indicator",
  "evidence": {"artifact_type": "hook"},
  "project_path": "/workspace/acme-api",
  "record_type": "event",
  "run_id": "run-20260724T151125.690671167-fa0a4148090fa1ba",
  "schema_version": "0.5.0",
  "session_id": "agent:research:metadata-review",
  "source_agent": "openclaw",
  "source_type": "hook",
  "sub_agent": "research",
  "tags": ["network"],
  "timestamp": "2026-07-24T15:20:00Z",
  "tool_call_id": "tool-cloud-metadata-01",
  "tool_name": "browser",
  "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials/"
}