How perplexityai/numbat works
Numbat is an endpoint-local AI-agent activity monitor and forensic investigation CLI. Its main workflow captures live hook or OTLP events, or reconstructs events from discovered session artifacts; normalized events enter a shared evaluation path for CEL and sequence detections, then selected records are emitted locally or over HTTP. Separate CLI capabilities cover agent inventory, policy and hook management, timelines, and portable case bundles. The README and pipeline excerpt document shared processing; several sensor-to-pipeline and CLI-to-subsystem connections are not visible in the sampled callers and are marked unverified.
Main entry points: pipeline.go Event Pipeline · main.go Numbat CLI · hook.go Live Hooks · otel.go OTLP Receiver
Components 23
CLI and Setup
- Numbat CLI
cmd/numbat/main.go - Agent Inventory
cmd/numbat/agents.go - Hook Management
cmd/numbat/hook_install.go - Rule Commands
cmd/numbat/rules.go - Artifact Scan
cmd/numbat/scan.go
Activity Sources
- Live Hooks
internal/hook/hook.go - OTLP Receiver
internal/otel/otel.go - Artifact Discovery
internal/discover/discover.go - Session Extractors
internal/extract
Normalization and Detection
- Event Pipeline
internal/pipeline/pipeline.go - Normalized Events
internal/model/event.go - CEL Rule Engine
internal/rule/engine.go - Sequence Tracker
internal/sequence/sequence.go - Built-in Rules
rules/builtin.go
Records and Investigation
- Finding Renderer
internal/finding/finding.go - Record Emitter
internal/output/output.go - File and HTTP Sinks
internal/output - Indicator Analysis
internal/output/indicators.go - Case Bundles
internal/casebundle/build.go - Bundle Verification
internal/casebundle/verify.go - Session Timelines
cmd/numbat/timeline.go
Other components
- Operator
- HTTP Collector
Connections 28
- Operator → Numbat CLI: invokes
README.md - Numbat CLI → Agent Inventory: lists agents
- Numbat CLI → Hook Management: installs hooks
- Numbat CLI → Rule Commands: manages rules
- Numbat CLI → Artifact Scan: scans artifacts
- Numbat CLI → Session Timelines: builds timelines
- Operator → Live Hooks: enables capture
README.md - Operator → OTLP Receiver: exports logs
README.md - Operator → Artifact Scan: requests scan
README.md - Artifact Scan → Artifact Discovery: finds artifacts
- Artifact Discovery → Session Extractors: classifies for parsing
internal/discover/discover.go - Live Hooks → Normalized Events: normalizes payload
internal/hook/hook.go - OTLP Receiver → Normalized Events: maps log records
- Session Extractors → Normalized Events: reconstructs events
internal/extract/gemini_session.go - Live Hooks → Event Pipeline: feeds events
- OTLP Receiver → Event Pipeline: feeds events
- Session Extractors → Event Pipeline: feeds events
- Event Pipeline → CEL Rule Engine: evaluates events
internal/pipeline/pipeline.go - Event Pipeline → Sequence Tracker: tracks sequences
internal/pipeline/pipeline.go - CEL Rule Engine → Built-in Rules: loads policy
- Event Pipeline → Finding Renderer: renders matches
internal/pipeline/pipeline.go - Event Pipeline → Record Emitter: emits records
internal/pipeline/pipeline.go - Event Pipeline → Indicator Analysis: accumulates indicators
internal/pipeline/pipeline.go - Record Emitter → File and HTTP Sinks: routes records
- File and HTTP Sinks → HTTP Collector: delivers records
README.md - Operator → Case Bundles: creates bundle
README.md - Case Bundles → Bundle Verification: supports verification
- Operator → Session Timelines: investigates session
README.md