|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## What This Project Is |
| 6 | + |
| 7 | +**ClawEDR** is a kernel-level endpoint detection and response system for AI coding agents (specifically OpenClaw). It enforces security policies by intercepting system calls via eBPF on Linux and Apple Seatbelt on macOS, blocking dangerous executables, paths, domains, and behavioral patterns. |
| 8 | + |
| 9 | +## Build / Development Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Setup |
| 13 | +python3 -m venv .venv && source .venv/bin/activate |
| 14 | +pip install -r requirements-dev.txt |
| 15 | + |
| 16 | +# The Execution Loop (main.py CLI): |
| 17 | +./main.py sync # Fetch ClawSec advisory feed + merge with master_rules.yaml |
| 18 | +./main.py compile # Generate deploy/compiled_policy.json + deploy/macos/clawedr.sb |
| 19 | +./main.py test # Run pytest builder/tests/ |
| 20 | +./main.py publish # git add/commit/push deploy/ |
| 21 | +./main.py all # sync → compile → test (skips publish) |
| 22 | +``` |
| 23 | + |
| 24 | +## Testing |
| 25 | + |
| 26 | +```bash |
| 27 | +# CI-safe (skips platform enforcement tests): |
| 28 | +python3 -m pytest builder/tests/ -v --ignore=builder/tests/test_linux_bpf.py -k "not Enforcement" |
| 29 | + |
| 30 | +# Run a specific test class: |
| 31 | +python3 -m pytest builder/tests/test_mac_sb.py::TestSeatbeltProfileSyntax -v |
| 32 | + |
| 33 | +# E2E tests (require live OS environment): |
| 34 | +bash tests/test_macos_e2e.sh |
| 35 | +bash tests/test_linux_e2e.sh |
| 36 | +``` |
| 37 | + |
| 38 | +Linux BPF tests (`test_linux_bpf.py`) require an OrbStack Ubuntu VM accessible via SSH — configure the host in `builder/config.yaml`. |
| 39 | + |
| 40 | +## Architecture: Three Components |
| 41 | + |
| 42 | +### 1. THE FORGE (`builder/` + `main.py`) |
| 43 | +Policy compilation pipeline: |
| 44 | +- `builder/master_rules.yaml` — Source of truth for all manual rules (Rule IDs: `BIN-*`, `DOM-*`, `PATH-*`, `LIN-*`, `MAC-*`) |
| 45 | +- `builder/threat_aggregator.py` — Downloads ClawSec feed, merges with master_rules → `.merged_rules.json` |
| 46 | +- `builder/compiler.py` — Reads merged rules, outputs `deploy/compiled_policy.json` (HMAC-signed) and `deploy/macos/clawedr.sb` (Seatbelt LISP profile) |
| 47 | + |
| 48 | +### 2. THE REGISTRY (`deploy/`) |
| 49 | +Distributable artifacts installed via `deploy/install.sh` (curl | sh): |
| 50 | +- `deploy/compiled_policy.json` — Universal policy consumed by both platforms |
| 51 | +- `deploy/linux/` — eBPF hooks + Shield daemon |
| 52 | +- `deploy/macos/` — Seatbelt profile + log tailer |
| 53 | +- `deploy/shared/` — User rules, alert dispatch, policy verification, rule updater |
| 54 | +- `deploy/dashboard/` — FastAPI backend (port 8477) + browser UI |
| 55 | + |
| 56 | +### 3. THE SHIELD (runtime, installed on end-user machines) |
| 57 | + |
| 58 | +**Linux** (`deploy/linux/monitor.py` + `deploy/linux/bpf_hooks.c`): |
| 59 | +- `bpf_hooks.c` (873 LOC) — eBPF programs for `execve`/`openat`/`socket_connect` interception; runs in-kernel |
| 60 | +- `monitor.py` (1428 LOC) — Python daemon: loads BPF via BCC, hot-reloads maps when policy changes, scoped to OpenClaw processes and descendants |
| 61 | +- Enforcement layers: blocked executables (SIGKILL on execve), blocked paths (openat hash check), deny rules (argv matching), heuristics (pipe sibling detection, rate limits) |
| 62 | + |
| 63 | +**macOS** (`deploy/macos/`): |
| 64 | +- `clawedr.sb` — Compiled Seatbelt profile (deny rules for blocked paths/executables) |
| 65 | +- `apply_macos_policy.py` — Rebuilds `.sb` profile when `user_rules.yaml` changes |
| 66 | +- `log_tailer.py` — Monitors sandbox violation logs, dispatches alerts to OpenClaw chat |
| 67 | + |
| 68 | +**Dashboard** (`deploy/dashboard/app.py`, 945 LOC): |
| 69 | +- FastAPI on port 8477 |
| 70 | +- Key endpoints: `/api/alerts`, `/api/rules`, `/api/user-rules`, `/api/custom-rules`, `/api/sessions` |
| 71 | + |
| 72 | +## Rule ID System |
| 73 | + |
| 74 | +Rule IDs enable precise user exemptions (`~/.clawedr/user_rules.yaml` survives updates): |
| 75 | + |
| 76 | +| Prefix | Meaning | |
| 77 | +|--------|---------| |
| 78 | +| `BIN-*` | Blocked executables | |
| 79 | +| `DOM-*` | Blocked domains | |
| 80 | +| `PATH-MAC-*`, `PATH-LIN-*` | OS-specific blocked paths | |
| 81 | +| `LIN-*`, `MAC-*` | OS-specific deny rules | |
| 82 | +| `THRT-*` | Auto-generated from threat feed | |
| 83 | +| `USR-*` | User custom rules | |
| 84 | +| `HEU-*` | Heuristic detection rules | |
| 85 | + |
| 86 | +## Data Flow |
| 87 | + |
| 88 | +``` |
| 89 | +master_rules.yaml + ClawSec feed |
| 90 | + ↓ (threat_aggregator.py) |
| 91 | + .merged_rules.json |
| 92 | + ↓ (compiler.py) |
| 93 | +compiled_policy.json + clawedr.sb |
| 94 | + ↓ (install.sh on end-user machine) |
| 95 | +Shield daemon (monitor.py / sandbox-exec) |
| 96 | + ↓ |
| 97 | +Violation logs → dashboard/app.py → Browser UI + alert_dispatcher.py |
| 98 | +``` |
| 99 | + |
| 100 | +## Key Files |
| 101 | + |
| 102 | +| File | Purpose | |
| 103 | +|------|---------| |
| 104 | +| `builder/master_rules.yaml` | All manual security rules; edit here to add/modify rules | |
| 105 | +| `builder/config.yaml` | Forge environment config (Linux VM host for BPF tests) | |
| 106 | +| `deploy/compiled_policy.json` | Generated; do not edit manually | |
| 107 | +| `deploy/linux/bpf_hooks.c` | eBPF kernel hooks — C with BCC macros | |
| 108 | +| `deploy/linux/monitor.py` | Linux Shield daemon — BCC Python bindings | |
| 109 | +| `deploy/dashboard/app.py` | FastAPI dashboard backend | |
| 110 | +| `.github/workflows/ci.yml` | CI: compile + verify artifacts + run unit tests | |
0 commit comments