clawsec

ClawSec Monitor v3.0 — See what your AI agents are really doing.

A transparent HTTP/HTTPS proxy that intercepts, inspects, and logs all AI agent traffic. Detects secrets being leaked, sensitive files being read, and command injection — automatically, in both directions.

Source & verification

All code lives in this repository. Before running anything, clone and verify:

git clone https://github.com/chrisochrisochriso-cmyk/clawsec-monitor
cd clawsec-monitor

# Verify file integrity against published checksums
shasum -a 256 -c \x3C\x3C'EOF'
71038919afa9978e2c16a4c8113b842abd992a99bebc63f677365f16812950b0  clawsec-monitor.py
dfb2c3f145ec8713ffe7799088dda1d6c93deb9d26dbb5a999425f34c467abfc  run_tests.py
f899e2d640b59fdd46c52828c460d8d2a515d7e24220b91a0e87162923c99fda  Dockerfile.clawsec
a005a2c259d78c14caeb29553ad0be7287c0608aad8e794a7b687b1e44d3a956  docker-compose.clawsec.yml
f685c09ecf0ad8034b1fa1fbe7e610bbf838fcec373795d7afe56dd2055e0d25  requirements.clawsec.txt
EOF

All files must print OK. Do not proceed if any checksum fails.

Bundled files

Install

pip install cryptography

That is the only external dependency. No other packages are required.

Start

# Foreground — Ctrl-C or SIGTERM stops it cleanly
python3 clawsec-monitor.py start

# Without HTTPS interception (no CA needed)
python3 clawsec-monitor.py start --no-mitm

# Custom config
python3 clawsec-monitor.py start --config config.json

Route agent traffic

Set these environment variables in the specific process you want to monitor — not system-wide:

export HTTP_PROXY=http://127.0.0.1:8888
export HTTPS_PROXY=http://127.0.0.1:8888

This scopes interception to that process only.

HTTPS interception (optional)

ClawSec generates a local CA on first start at /tmp/clawsec/ca.crt.

Preferred: per-process trust (no system changes, no sudo)

export REQUESTS_CA_BUNDLE=/tmp/clawsec/ca.crt   # Python requests
export SSL_CERT_FILE=/tmp/clawsec/ca.crt         # httpx / httpcore
export NODE_EXTRA_CA_CERTS=/tmp/clawsec/ca.crt   # Node.js
export CURL_CA_BUNDLE=/tmp/clawsec/ca.crt         # curl

If system-wide trust is needed (requires sudo, review carefully):

# macOS
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain /tmp/clawsec/ca.crt

# Ubuntu / Debian
sudo cp /tmp/clawsec/ca.crt /usr/local/share/ca-certificates/clawsec.crt
sudo update-ca-certificates

The CA private key is stored at /tmp/clawsec/ca.key (mode 0600, directory 0700). It never leaves your machine. Treat it like any TLS private key. Use --no-mitm if you do not want HTTPS interception at all.

Commands

python3 clawsec-monitor.py stop              # graceful shutdown
python3 clawsec-monitor.py status            # running/stopped + last 5 threats
python3 clawsec-monitor.py threats           # last 10 threats as JSON
python3 clawsec-monitor.py threats --limit N

Detection patterns

EXFIL (data leaving the agent)

INJECTION (commands arriving at the agent)

Threat log format

/tmp/clawsec/threats.jsonl — one JSON object per line:

{
  "direction":   "outbound",
  "protocol":    "https",
  "threat_type": "EXFIL",
  "pattern":     "ai_api_key",
  "snippet":     "Authorization: Bearer sk-ant-api01-...",
  "source":      "127.0.0.1",
  "dest":        "api.anthropic.com:443",
  "timestamp":   "2026-02-19T13:41:59.587248+00:00"
}

• direction — outbound (agent → internet) or inbound (internet → agent)
• threat_type — EXFIL or INJECTION
• pattern — named rule that fired (see tables above)
• snippet — up to 200 chars of surrounding context

Deduplication: same (pattern, dest, direction) suppressed for 60 seconds. Rotating log also at /tmp/clawsec/clawsec.log (10 MB × 3 backups).

Config reference

{
  "proxy_host":          "127.0.0.1",
  "proxy_port":          8888,
  "log_dir":             "/tmp/clawsec",
  "log_level":           "INFO",
  "max_scan_bytes":      65536,
  "enable_mitm":         true,
  "dedup_window_secs":   60
}

Docker

docker compose -f docker-compose.clawsec.yml up -d
docker exec clawsec tail -f /tmp/clawsec/threats.jsonl
docker compose -f docker-compose.clawsec.yml down

The CA persists in the clawsec_data volume across restarts.

Test suite

python3 run_tests.py   # 28/28 tests, ~5 seconds

How to help the user

When /clawsec is invoked, work out what the user needs and assist accordingly:

1. First run — verify checksums, install cryptography, start the monitor, confirm port 8888 is listening
2. Interpreting threats — run threats, explain each finding: what pattern fired, which direction, what destination, severity assessment
3. HTTPS MITM not working — check status for MITM ON; verify the correct CA trust env var is set for the agent runtime; confirm HTTP_PROXY/HTTPS_PROXY are in the agent's environment
4. False positive — explain which pattern fired and the surrounding snippet; identify whether it is a genuine match or context noise
5. Docker deploy — verify checksums, build image, run compose, confirm healthcheck passes
6. No threats appearing — confirm HTTP_PROXY is set in the agent process, check clawsec.log for bind/TLS errors, verify threats.jsonl is being written
7. Stopping / cleanup — stop, optionally remove /tmp/clawsec directory and uninstall the CA from the trust store

Always run python3 clawsec-monitor.py status first before troubleshooting.

Author: Chris Alley (paperknight) Source: https://github.com/chrisochrisochriso-cmyk/clawsec-monitor License: MIT