Agent Security with Numbat

CoWork OS can inspect live agent actions and endpoint agent artifacts with a pinned build of Perplexity Numbat. The integration is disabled by default and is controlled by the organization admin policy.

Numbat is an additional restriction layer, not the access model. CoWork resolves the task's access profile and applies its sandbox, command-tool, filesystem, network, and approval boundaries before or alongside Numbat's bounded action check. Numbat can deny a profile-permitted action, but it cannot grant command tools, widen a profile, suppress an approval, or turn an unavailable profile into an executable one.

Security boundary

Numbat runs as a local child process with shell: false, a minimal environment, bounded stdin/stdout, a per-call timeout, and checksum verification. CoWork passes a minimal action projection—command, path, URL, MCP identity, and input key names—not the original arbitrary tool input or tool output.

The agent_security policy stage runs before user approval and tool execution. Its decision is monotonic:

• no_override continues into CoWork's existing permission and approval policy.
• deny blocks the action.
• Numbat can never grant an action, suppress an approval, or weaken a CoWork denial.

Enforcement failures follow runtime.agentSecurity.failurePolicy. open continues with a diagnostic. deny_high_risk blocks only high-risk actions while enforcement mode is active.

Runtime provenance

The release build downloads the exact source commit and Go SDK declared in resources/numbat/source-manifest.json, verifies both SHA-256 digests, applies the checksum-pinned CoWork adapter patch, runs adapter tests, compiles with CGO_ENABLED=0, and writes a runtime manifest containing the binary digest. Packaged and externally supplied binaries are verified again before execution.

Build or verify the current-platform runtime:

npm run numbat:build
npm run numbat:verify

For an approved external build, both variables are required:

export COWORK_NUMBAT_BINARY=/absolute/path/to/numbat
export COWORK_NUMBAT_SHA256=<sha256>

COWORK_AGENT_SECURITY_DISABLED=1 is an emergency local kill switch. It disables evaluation even when the admin policy is enabled and is reported as a disabled runtime.

Policy

Settings > System & Security > Admin Policies exposes:

• enabled state and monitor/enforce mode;
• built-in, CoWork-recommended, or custom rule profile;
• fail-open or deny-high-risk runtime failure handling;
• hook timeout and history retention;
• optional scheduled artifact scan.

Custom rule directories must be absolute, outside the active workspace, owned by the current user or root, and not group/world writable. Symlinks are rejected.

The recommended profile turns on enforcement only for nine high-confidence high/critical rules covering destructive deletion, disk wipe, fork bombs, reverse shells, runtime permission bypass, secret-manager egress, SSH persistence, container host escape, and sudoers tampering. All other built-in rules remain detection-only.

Policy defaults and accepted ranges are:

The full policy lives at runtime.agentSecurity in the active user-data directory's policies.json. See Admin Policies for the complete schema.

Operations

The desktop Agent Security panel exposes runtime health, recent findings, finding lifecycle, diagnostics, scans, rule checks, and external-agent inventory. Hook installation and removal always require an explicit confirmation and use a stable checksum-verified binary path.

Equivalent local CLI commands include:

cowork security status --refresh
cowork security findings
cowork security finding <finding-id> acknowledged
cowork security decisions
cowork security inventory --refresh
cowork security scan
cowork security check-rules
cowork security hooks status codex
cowork security hooks install codex --yes
cowork security hooks uninstall codex --yes
cowork security prune --yes

Add --remote to use the Control Plane. Read operations require read scope; mutating operations require admin scope.

Case bundles contain Numbat findings, decisions, and cited events without raw evidence by default:

cowork security case build incident-123 --task-id <task-id>
cowork security case verify <bundle-name>

Verification proves bundle self-consistency, not publisher authenticity.

Data and retention

Findings, enforcement decisions, diagnostics, and external-agent inventory are stored in additive SQLite tables. Per-task Numbat record and state files live under the active CoWork user-data directory with owner-only directory permissions. Records are redacted again before database ingestion.

Retention pruning preserves open findings. Resolved/acknowledged findings, decisions, and diagnostics older than the configured retention period are removed. Case bundles are not automatically pruned.

Troubleshooting

If status reports unavailable:

1. Run cowork security status --refresh and inspect the reported runtime error.
2. In a source checkout, run npm run numbat:build, followed by npm run numbat:verify.
3. For an offline verification, set COWORK_NUMBAT_OFFLINE=1; the command will fail if the checksum-pinned source or Go SDK is not already cached.
4. If using COWORK_NUMBAT_BINARY, also set the exact COWORK_NUMBAT_SHA256. Symlinks, writable binaries, ownership mismatches, and checksum mismatches are rejected.

Do not enable enforcement until runtime health is ok and the selected rules pass cowork security check-rules. The emergency COWORK_AGENT_SECURITY_DISABLED=1 switch disables evaluation locally; it does not edit the saved organization policy.