Clawsec 1.0.0

Intercept and inspect AI agent HTTP/HTTPS traffic with MITM proxy to detect and log exfiltration and injection threats in real time.

Security Scan

The skill's instructions describe a system-level MITM proxy that requires scripts, Docker artifacts, and CA installation, but the package contains only documentation (no code or install spec) and does not declare the elevated actions it guides the user to perform — the pieces don't add up.

Purpose & Capability

The SKILL.md claims a full MITM proxy (generating a CA, signing per-host certs, a ~876-line Python script, a requirements file, Docker deployment, persisted CA volume, and logs) — all of which normally require shipped code and an install spec. The published package contains only skill.md and _meta.json (no code files, no install). That mismatch is a strong incoherence: either the package is incomplete or the skill is misrepresenting what it provides.

Instruction Scope

The runtime instructions direct the agent/user to generate and install a local CA into system trust stores (sudo/system keychains), modify environment variables to route all HTTP/HTTPS traffic through the proxy, and run docker-compose or python scripts. These steps grant the proxy visibility into all HTTPS traffic (including secrets) and modify system trust — very high scope. The SKILL.md also references running binaries/files (clawsec-monitor.py, requirements, Dockerfile) that are not present in the package, so following the instructions as-is is impossible and would require obtaining external code.

Install Mechanism

There is no install specification even though the document lists requirements (cryptography>=42.0.0), scripts, and Docker artifacts. The absence of any install or code files combined with instructions that assume on-disk artifacts is inconsistent and risky: a user following the doc would need to fetch code from an unspecified source, which is a high-risk action.

Credentials

The skill declares no required environment variables or credentials, yet the described behavior (MITMing HTTPS, reading all agent traffic) inherently accesses highly sensitive data (API keys, private keys, credentials appearing in HTTP bodies/headers). The SKILL.md instructs installing a CA into system trust and exporting PROCESS-LEVEL CA overrides that affect other processes — a privilege and scope not reflected in the metadata. This is disproportionate and not declared.

Persistence & Privilege

While the skill is not marked 'always:true', its procedures explicitly instruct persistent, system-level changes (installing a CA into the system trust store, a Docker volume to persist the CA, setting global proxy env vars). Those actions give long-lived, system-wide visibility into HTTPS traffic. The skill's metadata does not disclose or request this level of persistence or elevated privilege.

What to consider before installing

Do not install or run anything from this skill as-is. The documentation claims scripts, requirements, and Docker artifacts that are not included in the package — you'd have to fetch code from an unspecified source to proceed, which is high risk. Installing a local CA into your system trust store or routing all traffic through a proxy lets that software see every HTTPS request/response (including API keys, secrets, private keys). If you want this functionality, ask the publisher for: (1) the complete source files and checksums, (2) a verifiable upstream repository or release artifacts (GitHub release, reproducible build), (3) a clear install mechanism and minimal permissions required, and (4) instructions for running in an isolated, disposable environment (VM/container) and for per-process (non-system-wide) trust-only modes. If you cannot verify the code and origin, run nothing that installs a CA or modifies system trust on your host; test only inside an isolated VM or ephemeral container and audit the code first.

clawsec

You are now acting as the ClawSec Monitor assistant. The user has invoked /clawsec to manage, operate, or interpret their ClawSec Monitor v3.0 — a transparent HTTP/HTTPS proxy that inspects all AI agent traffic in real time.

---

What ClawSec Monitor does

ClawSec Monitor sits between AI agents and the internet. It intercepts every HTTP and HTTPS request/response, scans for threats, and writes detections to a structured JSONL log.

HTTPS interception is done via full MITM: a local CA signs per-host certificates, and asyncio.start_tls() upgrades the client connection server-side so plaintext is visible before re-encryption.

Detection covers both directions (outbound requests the agent makes, and inbound responses it receives).

---

Detection patterns

EXFIL patterns

Pattern name	What it matches
ai_api_key	sk-ant-*, sk-live-*, sk-gpt-*, sk-pro-*
aws_access_key	AKIA*, ASIA* (AWS access key IDs)
private_key_pem	-----BEGIN RSA/OPENSSH/EC/DSA PRIVATE KEY-----
ssh_key_file	.ssh/id_rsa, .ssh/id_ed25519, .ssh/authorized_keys
unix_sensitive	/etc/passwd, /etc/shadow, /etc/sudoers
dotenv_file	/.env, /.aws/credentials
ssh_pubkey	ssh-rsa <key> (40+ chars)

INJECTION patterns

Pattern name	What it matches
pipe_to_shell	curl <url> | bash, wget <url> | sh
shell_exec	bash -c "...", sh -i "..."
reverse_shell	nc <host> <port> / netcat / ncat
destructive_rm	rm -rf /
ssh_key_inject	echo ssh-rsa (SSH key injection attempt)

---

All commands

# Start the proxy (runs in foreground, Ctrl-C or SIGTERM to stop)
python3 clawsec-monitor.py start

# Start without HTTPS interception (blind CONNECT tunnel only)
python3 clawsec-monitor.py start --no-mitm

# Start with a custom config file
python3 clawsec-monitor.py start --config /path/to/config.json

# Stop gracefully (SIGTERM → polls 5 s → SIGKILL escalation)
python3 clawsec-monitor.py stop

# Show running/stopped status + last 5 threats
python3 clawsec-monitor.py status

# Dump last 10 threats as JSON
python3 clawsec-monitor.py threats

# Dump last N threats
python3 clawsec-monitor.py threats --limit 50

---

HTTPS MITM setup (one-time per machine)

After first start, a CA key and cert are generated at /tmp/clawsec/ca.crt.

# 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

# Per-process (no system trust required)
export REQUESTS_CA_BUNDLE=/tmp/clawsec/ca.crt   # Python requests
export SSL_CERT_FILE=/tmp/clawsec/ca.crt         # httpx
export NODE_EXTRA_CA_CERTS=/tmp/clawsec/ca.crt   # Node.js
export CURL_CA_BUNDLE=/tmp/clawsec/ca.crt         # curl

Then route agent traffic through the proxy:

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

---

Config file reference

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

All keys are optional. Defaults are shown above.

---

Threat log format

Threats are appended to /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"
}

Fields:

• direction — outbound (agent → internet) or inbound (internet → agent)
• protocol — http or https
• threat_type — EXFIL (data leaving) or INJECTION (commands arriving)
• pattern — the named rule that fired (see detection table above)
• snippet — up to 200 chars of surrounding context (truncated for safety)
• dest — host:port the agent was talking to
• timestamp — ISO 8601 UTC

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

---

Docker

# Start
docker compose -f docker-compose.clawsec.yml up -d

# Watch threat log live
docker exec clawsec tail -f /tmp/clawsec/threats.jsonl

# Query threats
docker exec clawsec python3 clawsec-monitor.py threats

# Stop
docker compose -f docker-compose.clawsec.yml down

CA persists in the clawsec_data Docker volume across restarts.

---

Files

File	Purpose
clawsec-monitor.py	Main script (876 lines)
run_tests.py	28-test regression suite
Dockerfile.clawsec	Python 3.12-slim image
docker-compose.clawsec.yml	One-command deploy + healthcheck
requirements.clawsec.txt	cryptography>=42.0.0

---

How to help the user

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

1. Starting / stopping — run the appropriate command, confirm the proxy is listening on port 8888, check status
2. Interpreting threats — run python3 clawsec-monitor.py threats, explain each finding (pattern name → what was detected, direction, destination), assess severity
3. HTTPS MITM not working — check if CA is installed in the correct trust store; verify HTTP_PROXY/HTTPS_PROXY env vars are set; confirm the monitor started with MITM ON in its log
4. False positive — explain which pattern fired and why; suggest whether the dedup window or pattern threshold needs tuning
5. Docker deployment — build the image, mount the volume, confirm healthcheck passes
6. Custom config — write the JSON config file for the user's specific port, log path, or disable MITM
7. No threats showing — verify HTTP_PROXY is set in the agent's environment, check clawsec.log for errors, confirm threats.jsonl exists

Always check python3 clawsec-monitor.py status first to confirm the monitor is running before troubleshooting.

---

ClawSec Monitor v3.0 — See what your AI agents are really doing. GitHub: https://github.com/chrisochrisochriso-cmyk/clawsec-monitor