ShadowClaw Universal shadow-AI detector

Detection for the AI nobody approved.

ShadowClaw correlates what a process is computing, where it is talking, and what it does to the machine — then writes a hash-chained local record and ships scored findings over OpenTelemetry into DefenseClaw, Grafana, or Splunk. Standard-library Python, no third-party dependencies, and no process or domain that can be configured into silence. Runs on macOS, Linux, and Windows — containers and cloud hosts included.

Quickstart How detection works DefenseClaw integration
Detection planes A · B · C
Known providers 59 · 92 domains
Detection matrix 31 / 31
Dependencies 0
License Apache-2.0 · open source
Console output sudo python3 -m shadowclaw --esf 
ShadowClaw 1.5.1   host mba-m3.local
ledger  /Library/Application Support/ShadowClaw

[critical] python3 [pid 41207] user alice
  shadow_ai_egress              api.anthropic.com (Anthropic) via dns
  gateway_bypass                ai-gateway.corp.example declared, bypassed
  inference_heartbeat           sustained CPU over consecutive polls
  agent_credential_access       claude -> sh -> cat ~/.aws/credentials
  agent_kill_chain              credential_access -> identity_creation
                                -> exfiltration, in order, in one session

  weights and thresholds are withheld from the public documentation
Severity critical
Attribution dns (exact)
Action taken recorded

Correlation, not a single signal

Three planes, one finding.

Any one of these observations has an innocent explanation. A build server burns CPU. A developer machine holds TLS connections open. An engineer runs sudo. Nothing here fires on a single weak observation, which is what keeps the false-positive rate liveable.

Signals are additive, the sum is capped at 100, and the bands are fixed: critical at 75, high at 50, medium at 30, low at 15.

Plane A

Inference heartbeat

Sustained CPU in a scriptable runtime, resident memory large enough to hold model weights, and the local model runtimes themselves. Answers is this process doing AI? without naming a vendor.

  • CPU-time deltas, not ps %cpu averages
  • 12 known local runtimes
  • No privilege required
Plane B

Shadow egress

Per-process sockets attributed to a provider by DNS capture, catalog resolution, or PTR — plus the inference-shaped endpoints that are in no catalog yet. Answers who is it talking to?

  • 59 providers across 7 categories
  • Gateway-bypass contrast
  • Root widens socket visibility
Plane C

Agent actions

Credential reads, identity creation, privilege escalation, persistence, dead drops between agent sessions, and uploads to anonymous drop sites — every one of them gated on an AI agent in the process lineage. Answers what did the agent then do?

  • 6 ordered tactics, mapped to ATT&CK
  • Kill-chain bonus for progression
  • Dead-drop handoffs between sessions
  • Needs root and Full Disk Access

Available now

Seven things you can do today.

Nothing below needs an LLM key, a cloud account, or a virtualenv. The sensor runs on the python3 that ships with macOS.

  1. Inventory the AI already running on a host One poll loop, no configuration, no privilege.
  2. Attribute egress to a provider, per process The thing host-wide OTel metrics cannot do on macOS.
  3. Catch a gateway bypass Declare the approved path; the contrast becomes the signal.
  4. Reconstruct an agent kill chain Credential read, then identity, then upload — as one session.
  5. Catch agents handing off through a dead drop A local file or public paste site read by a different agent session than the one that wrote it.
  6. Keep tamper-evident local evidence Hash-chained SQLite, written before any network export.
  7. Ship findings to the stack you already run OTLP into DefenseClaw's Grafana, Loki direct, or Splunk HEC.

Scope, stated plainly

It detects. It does not enforce.

ShadowClaw observes, scores, and records. It does not block processes, terminate agents, quarantine hosts, or honour policy exceptions — and there is no allowlist, with a test that fails the build if anyone adds one back.

That split is deliberate. A detector whose blind spots are configurable is a detector you cannot reason about, and the first thing anyone evading the control would do is get themselves added to the list. Enforcement — and therefore exceptions — belongs downstream, in DefenseClaw and Cisco AI Defense, with the finding in hand.

Local ledger, first Every finding lands in hash-chained SQLite and a raw JSONL stream before anything is exported, so a collector outage can never cost you the record. Five OTLP event shapes finding.recorded, provider.reached, agent.activity, ktp.risk_factors, and ktp.envelope — flat JSON, no nested objects. Degraded state is stated A sensor that could not look never reports a clean host. Missing coverage is named in the banner, and esf.running is exported on every poll. Kinetic Trust Protocol Four Risk Factor inputs and a per-action Kinetic Envelope receipt. Reporting only — nothing derived from a receipt re-enters detection. Provable, not demonstrable 31 synthetic detection paths including 13 benign cases that must stay quiet, plus a coordinated test scored against ground truth you declare first. Known limitations, in writing Sampling, probabilistic IP attribution, DNS-over-HTTPS, shared CDNs, pid reuse, and the blind spot that lineage gating buys.

Start with evidence

Run the detector against a rogue agent in five minutes.

./scripts/demo.sh starts a local model stub, a simulated unsanctioned agent, and the sensor, then prints what was caught from the local ledger. Nothing needs to be listening.

Install ShadowClaw First detection