Skill: chrisochrisochriso-cmyk/clawsec (version 1.0.0)

# 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 ```bash # 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`. ```bash # 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: ```bash export HTTP_PROXY=http://127.0.0.1:8888 export HTTPS_PROXY=http://127.0.0.1:8888 ``` --- ## Config file reference ```json { "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): ```json { "direction": "outbound", "protocol": "https", "threat_type": "EXFIL", "pattern": "ai_api_key", "snippet": "[REDACTED_SECRET]", "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 ```bash # 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*


Security scan verdicts — ClawScan: suspicious | static analysis:  | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)