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 avant action pris en charge ; voir le guide d'application.

Fonctionnalités

• Surveillance en direct via des hooks, plugins et 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 avant 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 mode surveillance uniquement.
• 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, constats, décisions d'application, indicateurs et résumés d'analyse. Les événements et constats conservent les références sources ; les schémas JSON définissent le format d'échange.
• Analyse d'artefacts en lecture seule avec rédaction 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.6 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 des agents :

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

Surveillance et application

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

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

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. Voir 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 avant 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.4.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/"
}