numbat is an open-source Go tool that gives defenders endpoint-local visibility into AI agent activity, combining live hook monitoring, CEL-based detection, and forensic reconstruction from on-disk session artifacts.
| Tool | perplexityai/numbat — single-binary endpoint visibility and detection for AI agent activity, written in Go under Apache-2.0 |
| Category | AI agent security monitoring, endpoint detection, and forensic analysis |
| Primary Use | Observing and auditing AI agents (Codex, Claude Code, gateways) on workstations via hooks, OTLP/HTTP logs, and on-disk session artifacts, evaluated by a local CEL rule engine |
| Safe Use | Intended for defenders and authorized security teams monitoring AI agents on endpoints they own or administer — detection runs locally, blocking is opt-in, and all shipped rules are monitor-only |
| Telemetry Note | numbat writes versioned NDJSON records (events, findings, enforcement decisions) to stdout, local files like ~/.numbat/records.ndjson, or configured HTTP sinks; records retain sensitive endpoint and agent context even after redaction, and outbound requests go only to configured sinks |
As AI coding agents proliferate on developer workstations, security teams face a visibility gap that traditional EDR was never designed to close: autonomous tool calls, MCP sessions, and sub-agent activity that look like ordinary user processes from the OS perspective. perplexityai/numbat, released under Apache-2.0 and already past a thousand stars, is Perplexity's answer — a single-binary Go tool that observes supported desktop, CLI, IDE, and gateway agents through local hooks and plugins, OTLP/HTTP log exporters, and on-disk session artifacts. What makes the architecture notable is the unification: live and at-rest activity are normalized into one event model and evaluated by the same CEL rule engine, so a rule developed against live hook traffic also runs during forensic scans of persisted sessions.
The design philosophy is deliberately defensive-first. Detection runs entirely locally; records can go to stdout or a local file and are optionally delivered over HTTP to a configured sink — nothing phones home by default. The README is explicit that numbat makes outbound requests only to configured HTTP sinks and never executes agents or commands found in artifacts. This is a monitoring and reconstruction tool, not an interception framework, and the scope section is refreshingly honest about limits: at-rest reconstruction is not disk or memory acquisition and cannot recover activity an agent did not persist, and findings are rule matches, not proof of compromise.
Live capture works through agent-native hook and plugin mechanisms. Installing monitoring is a two-step affair: numbat hook install --agent codex --emit all wires the hook in monitor-only mode with --emit all writing events, findings, indicators, and enforcement decisions to ~/.numbat/records.ndjson, and numbat hook status --agent codex verifies configuration. The README's hook-trust callout is worth reading closely: for Codex user hooks, operators are told to review and trust the hook definition in /hooks or Settings > Hooks, including after changes such as --enforce, because hook status verifies configuration, not execution or delivery. That distinction between configuration and delivery is the kind of operational subtlety that separates mature tooling from demos.
The detection layer combines built-in CEL rules, multi-step sequence rules, and custom YAML rules. The shipped rule catalog targets behaviors that will feel familiar to anyone modeling agentic threats: the README shows a high-severity cloud-metadata rule matching a proposed browser request to 169.254.169.254 IAM credential paths, and a sequence rule chain.secret_read_then_egress correlating secret-file access followed by a data-bearing upload in one session — complete with ATT&CK-style tags like attack.t1048, attack.t1552, and attack.t1567 and cited_event_ids linking the finding back to its source events. Sequence semantics matter here because single-event detection misses the characteristic shape of agent abuse, which is usually a benign-looking chain of steps.
Blocking exists but is aggressively opt-in. Enforce mode is disabled by default, applies only to supported synchronous pre-action hooks, and only fires on rules explicitly marked enforce: true — every shipped rule is monitor-only. To actually enforce a detection, an operator must copy the shipped YAML into a controlled directory, keep the same rule id, add enforce: true, and bump the version, then validate with numbat rules check --rules-dir ./numbat-policy and install with --enforce. The example enforcement decision shows a Codex create_file pre-action matching persistence.ssh_authorized_keys and receiving an agent-specific deny response, with a full decision record capturing the model, tool call, and cited finding. The friction is intentional: the safe-by-default posture forces a deliberate human decision before any agent action is blocked.
Forensic reconstruction is arguably the most interesting capability for incident responders. numbat scan performs read-only artifact scanning across discovered parser-backed agents — --agent codex limits discovery to one — without prior numbat instrumentation, meaning you can deploy it to a workstation after the fact and still reconstruct what an agent did from its persisted session files. The timeline command produces per-session views, and case build assembles portable case bundles with SHA-256 manifests that case verify can check. The README carefully notes that manifests establish internal consistency, not source authenticity — unsigned bundles do not prove where the artifacts came from or that they are complete.
Privacy handling is more considered than in most security tooling. Read-only scanning applies secret redaction, normal record output never includes a complete raw transcript, and attaching raw evidence files to a case bundle is an explicit opt-in. That said, the Security section is candid that records can still retain sensitive endpoint and agent context after redaction — usernames, project paths, execution context — so anyone shipping records off-host should think hard about where they land and who can read the sink. There is a SECURITY.md with a documented threat model and private vulnerability reporting, which is a good sign for a tool that will sit on developer machines.
The wire format is worth praising independently of the tool. Records are versioned NDJSON across five types — events, findings, enforcement decisions, indicators, and scan summaries — with published JSON Schemas at docs/schema/v0.4.0/, and events retain source references (artifact_type, source_type, tool_call_id) so findings remain traceable to evidence. For a blue team building pipelines, a stable, schema-defined record contract with schema_version fields makes numbat output ingestible by SIEMs without bespoke parsers, and the ship command handles delivery separately from generation.
Operationally, the CLI decomposes cleanly: inventory and investigation (agents, scan, timeline), live capture (hook install, hook status, hook uninstall, collect), delivery (ship), rule development (rules check, rules list, rules test), and case bundles (case build, case verify). Most operational commands accept repeatable --rules-dir DIR to layer operator rules over or replace embedded ones by id, with --no-builtin-rules available for an operator-only catalog. The rules test subcommand in particular suggests a sane workflow for iterating on detections against recorded fixtures before fleet rollout, and docs/deployment.md covers install scope and fleet patterns.
Distribution is a single static binary for macOS, Linux, and Windows on amd64 and arm64, built without cgo (CGO_ENABLED=0 go build -trimpath), with release artifacts shipped alongside SHA-256 checksums. Installation is a standard go install github.com/perplexityai/numbat/cmd/numbat@latest with Go 1.26.6 or newer, or a plain release download. The coverage matrix in docs/agent-coverage.md is declared authoritative for per-agent support and known gaps — including deferred stores, fidelity limits, and Windows AppData path quirks versus WSL's separate Linux home — so integrators should treat that document, not the README, as the source of truth.
For defenders, numbat sits in a genuinely new niche: agent-activity monitoring at the endpoint, where the unit of analysis is a tool call or a session rather than a process or a network flow. Its honest scoping, monitor-only defaults, schema-defined output, and local-first detection model make it a credible foundation for authorized monitoring programs — red teams will also find the record stream useful for documenting agent behavior during sanctioned engagements, though the tool itself is oriented toward observation, not offense. The main caveats are coverage-dependence on per-agent hook and artifact support, and the residual sensitivity of redacted records; both are documented rather than hidden, which is exactly what you want from infrastructure you would deploy on developer workstations.
perplexityai/numbat.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.