Clawsec.Bak

Manage and interpret ClawSec Monitor v3.0, a proxy that inspects AI agent HTTP/HTTPS traffic, detects threats, and logs suspicious activity in real time.

Security Scan

The skill's instructions describe a high-privilege HTTPS MITM proxy and logging tool (ClawSec Monitor) that would require local scripts, Docker images, and system CA changes, but the skill package contains no code, no provenance, and no declared runtime requirements — proceed with caution and verify the real software before trusting or installing its CA.

Purpose & Capability

The SKILL.md claims to manage a local ClawSec Monitor proxy (start/stop, inspect threats, install a CA, run Docker), which is coherent with the description. However the skill bundle contains no code, no Docker files, and no homepage or source link — yet the instructions assume the presence of files like clawsec-monitor.py, Dockerfile.clawsec, and requirements.clawsec.txt. Required runtime tools (python3, docker, update-ca-certificates, sudo) are not declared. The absence of the referenced artifacts and provenance is an incoherence: the skill either expects the user to already have an external project installed, or it omits required files/metadata.

Instruction Scope

The instructions explicitly direct the agent/user to perform a full HTTPS MITM (generate a CA, install it into system trust stores, route HTTP(S)_PROXY env vars) and to inspect all agent traffic, including sensitive headers and payloads (API keys, private keys). That behavior is consistent with the stated purpose but is high-privilege and sensitive: installing a system-trusted CA affects all TLS on the machine and lets the proxy see secrets. The SKILL.md does not limit scope nor include safety/privacy guidance beyond logging and dedup rules. Also, the instructions assume running local scripts (python3 clawsec-monitor.py) which are absent from the package — the agent following these literal instructions would fail or try to fetch code from elsewhere (not specified).

Install Mechanism

There is no install spec (instruction-only), reducing the risk from automatic code installation. However the SKILL.md references building/running Docker Compose and installing Python dependencies (cryptography>=42.0.0) and expects filesystem artifacts. Because nothing is provided and no trusted download URLs or source repository are given, a user would need to obtain and run external code manually; that creates a provenance gap and increases risk if the user fetches unknown binaries from untrusted sources.

Credentials

The skill declares no required environment variables or credentials, but the runtime instructions instruct users to set HTTP_PROXY/HTTPS_PROXY and various CA-related env vars (REQUESTS_CA_BUNDLE, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, CURL_CA_BUNDLE). Those proxy/CA env vars are reasonable for a proxy, but the skill does not declare or document required binaries (python3, docker) nor the need for root/sudo to install a CA. The detection patterns include very sensitive matches (API keys, SSH/private keys, /etc files) — appropriate for a monitor but meaning the tool will see high-value secrets. There is no justification or guidance about data retention, secure handling of logs, or limiting collection, and no credentials are declared which might be expected for centralized logging or telemetry (but none are present).

Persistence & Privilege

The skill does not request 'always:true' and is user-invocable, which is normal. However the operational instructions require creating a local CA and (optionally) adding it to system trust stores, which is a persistent, system-wide change requiring administrative privilege. The skill also writes logs to /tmp/clawsec and suggests a persistent Docker volume. Those are sensible for the described monitor, but they are privileged actions that the package metadata does not surface — another provenance/privilege mismatch to be aware of.

What to consider before installing

This skill's documentation describes a full HTTPS MITM proxy that will intercept and log sensitive traffic (API keys, private keys, credentials). However the skill bundle contains no code, no Dockerfiles, and no source/homepage: you would need to obtain the ClawSec Monitor software elsewhere before any of these commands work. Before proceeding, verify the origin of the monitor binary/image and its checksums; do not install the CA into your system trust store unless you trust and have audited the code and understand the privacy implications. Prefer running the proxy in an isolated VM or disposable container, review and limit what agents/applications you route through it, and require explicit user approval before making system-trust changes. If the maintainer/link for the actual ClawSec Monitor is provided, request the source repository, build instructions, and integrity signatures and re-run an evaluation including the code.

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