# ClawSentry — AHP Supervision Gateway

> **Python 3.12+** | **2234 tests** | Protocol `ahp.1.0`

**ClawSentry** is the Python reference implementation of AHP (Agent Harness Protocol) — a unified security supervision gateway for multi-agent frameworks. Deployed as a sidecar, it normalizes runtime events from different frameworks (a3s-code, Claude Code, Codex, OpenClaw) into a unified protocol, passes them through a three-layer progressive risk evaluation pipeline, and produces real-time decisions (allow / block / modify / defer) with complete audit trails.

**Core goal**: Eliminate cross-framework policy duplication and observability fragmentation through a "protocol-first, decision-centralized" approach to agent security governance.

---

## Table of Contents

- [Three-Layer Decision Model](#three-layer-decision-model)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [CLI Commands](#cli-commands)
- [API Endpoints](#api-endpoints)
- [Web Dashboard](#web-dashboard)
- [Project Structure](#project-structure)
- [Configuration](#configuration)
- [Running Tests](#running-tests)

---

## Three-Layer Decision Model

```
                    Event Flow 100%
                        |
                 +------v------+
                 |  L1 Rules   |  < 0.3ms, D1-D6 composite scoring
                 +------+------+
                        |
            +-----------+-----------+
            v           v           v
     LOW (allow)   MEDIUM (?)   CRITICAL (block)
      ~60%          ~30%          ~10%
         |              |           |
         |       +------v------+   |
         |       |  L2 Semantic |   |  Pluggable LLM, < 3s
         |       +------+------+   |
         |              |          |
         |       +------v------+   |
         |       |  L3 Agent   |   |  Multi-turn tool use, < 30s
         |       +------+------+   |
         |              |          |
         v              v          v
       allow      allow/block    block
```

| Layer | Implementation | Latency | Activation |
|-------|---------------|---------|------------|
| **L1** Rules | D1-D6 six-dimensional scoring + short-circuit rules | < 0.3ms | Always on |
| **L2** Semantic | RuleBased / LLM / Composite + 25 attack patterns | < 3s | `CS_LLM_PROVIDER` |
| **L3** Agent | AgentAnalyzer + ReadOnlyToolkit + SkillRegistry | < 30s | `CS_L3_ENABLED=true` |

### D1-D6 Risk Dimensions

| Dim | Target | Score | Notes |
|-----|--------|-------|-------|
| **D1** | Tool type risk (bash=3, read_file=0) | 0-3 | |
| **D2** | Target path sensitivity (/etc/passwd=3, /tmp=0) | 0-3 | |
| **D3** | Command pattern (rm -rf=3, ls=0) | 0-3 | |
| **D4** | Session accumulation (high-risk event count) | 0-2 | |
| **D5** | Agent trust level | 0-2 | |
| **D6** | Injection detection (prompt injection heuristics) | 0-3 | E-4, multiplier formula |

**Composite scoring**: `base = max(D1,D2,D3)*w1 + D4*w2 + D5*w3`, then `score = base * (1.0 + 0.5 * D6/3.0)`

**Short-circuit rules**: D1=3 & D2>=2 -> CRITICAL | D3=3 -> CRITICAL | D1=D2=D3=0 -> LOW

### Post-Action Security Fence

For `POST_ACTION` events, an async post-action analyzer inspects command outputs for:
- Indirect prompt injection patterns
- Data exfiltration (10 types: curl, wget, base64, DNS, etc.)
- Obfuscation (Shannon entropy, encoding)

Tiered response: `LOG_ONLY` / `MONITOR` / `ESCALATE` / `EMERGENCY`

### Trajectory Analyzer

Multi-step attack sequence detection across session events:
- `exfil-credential`: credential file read -> outbound transfer
- `backdoor-install`: download -> permission change -> persistence
- `recon-then-exploit`: enumeration -> targeted attack
- `secret-harvest`: multiple secret file accesses
- `staged-exfil`: staging to temp -> bulk exfiltration

### Self-Evolving Pattern Repository (E-5)

High-risk events automatically extract candidate attack patterns. Patterns progress through `CANDIDATE -> EXPERIMENTAL -> STABLE -> DEPRECATED` lifecycle with confidence scoring. Controlled by `CS_EVOLVING_ENABLED`.

---

## Architecture

```
 +------------------------------------------------------------------+
 |              Framework Runtime Layer                               |
 |  +------------------+          +-------------------------+        |
 |  | a3s-code (Rust)   |          |  OpenClaw (TypeScript)   |        |
 |  |   stdio Hook      |          |  WS exec.approval        |        |
 |  +--------+---------+          +----------+--------------+        |
 +-----------|-------------------------------|---------------------+
             |                               |
 +-----------v-------------------------------v---------------------+
 |                    Adapter Layer                                  |
 |  +------------------+     +------------------------------+      |
 |  |  A3SCodeAdapter   |     |  OpenClawAdapter + WS Client |      |
 |  |  + Harness bridge |     |  + Webhook Receiver          |      |
 |  +--------+---------+     +----------+-------------------+      |
 +-----------|--------------------------|------------------------+
             |   UDS / HTTP (JSON-RPC)  |
 +-----------v--------------------------v------------------------+
 |              ClawSentry  -  AHP Supervision Gateway             |
 |                                                                  |
 |  +----------+  +----------+  +----------+  +---------------+   |
 |  | L1 Rules |->| L2 LLM   |->| L3 Agent |->| Decision      |   |
 |  | D1-D6    |  | Semantic |  | Toolkit  |  | Router        |   |
 |  | <0.3ms   |  | <3s      |  | <30s     |  | allow/block/  |   |
 |  +----------+  +----------+  +----------+  | modify/defer  |   |
 |                                              +-------+-------+   |
 |  +---------------+  +--------------+  +----------v--------+    |
 |  | D6 Injection  |  | Post-Action  |  | TrajectoryStore   |    |
 |  | Detector      |  | Analyzer     |  | SQLite audit      |    |
 |  +---------------+  +--------------+  +-------------------+    |
 |                                                                  |
 |  +---------------+  +--------------+  +-------------------+    |
 |  | SessionRegistry|  | AlertRegistry|  | PatternEvolution  |    |
 |  | + EventBus/SSE|  | + AttackPats |  | Self-evolving     |    |
 |  +---------------+  +--------------+  +-------------------+    |
 |                                                                  |
 |  +-------------------+                +-------------------+     |
 |  | DetectionConfig   |                | Web Dashboard     |     |
 |  | 17 CS_* env vars  |                | React SPA at /ui  |     |
 |  +-------------------+                +-------------------+     |
 +------------------------------------------------------------------+
```

**Design principles**:

| Principle | Description |
|-----------|-------------|
| Protocol-first | Solve cross-framework interop before stacking policies |
| Centralized decisions | All final decisions from Gateway; adapters don't decide |
| Dual-channel | pre-action sync blocking, post-action async audit |
| Escalate only | L2/L3 can only raise risk level, never lower it |
| Fail-closed | High-risk ops blocked when Gateway unreachable |

---

## Quick Start

### Install

```bash
pip install clawsentry            # Base
pip install "clawsentry[llm]"     # + LLM semantic analysis
pip install "clawsentry[all]"     # Everything

# Development
git clone <repo-url> && cd ClawSentry
pip install -e ".[dev]"
```

### OpenClaw Users

```bash
clawsentry init openclaw --auto-detect   # Auto-detect ~/.openclaw config
clawsentry init openclaw --setup         # Configure OpenClaw settings
clawsentry gateway                        # Start (auto-detects OpenClaw)
clawsentry watch                          # Real-time monitoring
# Browser: http://127.0.0.1:8080/ui      # Web dashboard
```

### a3s-code Users

```bash
clawsentry init a3s-code
clawsentry gateway
clawsentry watch
```

---

## CLI Commands

| Command | Description |
|---------|-------------|
| `clawsentry gateway` | Start Gateway (auto-detects framework, starts WS/Webhook as needed) |
| `clawsentry watch` | SSE real-time display (`--filter`/`--json`/`--no-color`/`--interactive`) |
| `clawsentry init <framework>` | Initialize config (`openclaw`/`a3s-code`) |
| `clawsentry harness` | a3s-code stdio bridge subprocess |

---

## API Endpoints

All endpoints require `Authorization: Bearer <token>` (except `/health` and `/ui`).

| Method | Path | Description |
|--------|------|-------------|
| POST | `/ahp` | JSON-RPC sync decision |
| POST | `/ahp/resolve` | DEFER resolution proxy |
| GET | `/ahp/patterns` | List attack patterns (core + evolved) |
| POST | `/ahp/patterns/confirm` | Confirm/reject evolved pattern |
| GET | `/health` | Health check (no auth) |
| GET | `/report/summary` | Cross-framework aggregate stats |
| GET | `/report/sessions` | Active sessions + risk ranking |
| GET | `/report/session/{id}` | Session trajectory replay |
| GET | `/report/session/{id}/risk` | Session risk detail + D1-D6 timeline |
| GET | `/report/stream` | SSE real-time events |
| GET | `/report/alerts` | Alert list (filter: severity/acknowledged) |
| POST | `/report/alerts/{id}/acknowledge` | Acknowledge alert |
| GET | `/ui` | Web dashboard SPA (no auth) |

---

## Web Dashboard

Built-in React SPA security dashboard at `/ui`. Dark SOC theme with real-time SSE data.

| Page | Features |
|------|----------|
| **Dashboard** | Live decision feed + 4 metric cards + risk distribution + decision source chart |
| **Sessions** | Active sessions + D1-D6 radar + risk curve + decision timeline |
| **Alerts** | Alert table + severity filter + acknowledge + SSE auto-push |
| **DEFER Panel** | Pending decisions + countdown + Allow/Deny buttons |

Tech stack: React 18 + TypeScript + Vite + recharts + lucide-react

---

## Project Structure

```
src/clawsentry/
|-- gateway/                           # Core supervision engine
|   |-- models.py                      # Unified data models (CanonicalEvent/Decision/RiskSnapshot)
|   |-- server.py                      # FastAPI HTTP + UDS + Auth + SSE + static files
|   |-- stack.py                       # One-click start: Gateway + OpenClaw runtime + DEFER
|   |-- policy_engine.py               # L1 rules + L2 Analyzer integration
|   |-- risk_snapshot.py               # D1-D6 six-dimensional risk assessment
|   |-- injection_detector.py          # D6 injection detection (weak/strong patterns + canary)
|   |-- post_action_analyzer.py        # Post-action security fence (exfil/injection/obfuscation)
|   |-- trajectory_analyzer.py         # Multi-step attack sequence detection (5 sequences)
|   |-- pattern_matcher.py             # Attack pattern matching engine (25 OWASP ASI patterns)
|   |-- pattern_evolution.py           # Self-evolving pattern repository (E-5)
|   |-- detection_config.py            # DetectionConfig (17 tunable CS_* env vars)
|   |-- semantic_analyzer.py           # L2 pluggable semantic (Protocol + 3 implementations)
|   |-- llm_provider.py                # LLM Provider base (Anthropic/OpenAI)
|   |-- llm_factory.py                 # Environment-driven analyzer builder
|   |-- agent_analyzer.py              # L3 review Agent (MVP single + standard multi-turn)
|   |-- review_toolkit.py              # L3 ReadOnlyToolkit (5 read-only tools)
|   |-- review_skills.py               # L3 SkillRegistry (YAML load/select)
|   |-- l3_trigger.py                  # L3 trigger policy (4 trigger types)
|   |-- idempotency.py                 # Request idempotency cache
|   +-- skills/                        # 6 built-in review domain skills (YAML)
|-- adapters/                          # Framework adapters
|   |-- a3s_adapter.py                 # a3s-code Hook -> CanonicalEvent normalization
|   |-- a3s_gateway_harness.py         # a3s-code stdio bridge (JSON-RPC 2.0)
|   |-- openclaw_adapter.py            # OpenClaw main adapter (approval state machine)
|   |-- openclaw_normalizer.py         # OpenClaw event normalization
|   |-- openclaw_ws_client.py          # OpenClaw WS client (listen + resolve)
|   |-- openclaw_webhook_receiver.py   # OpenClaw Webhook secure receiver
|   |-- openclaw_gateway_client.py     # OpenClaw -> Gateway RPC client
|   |-- openclaw_approval.py           # Approval lifecycle state machine
|   |-- openclaw_bootstrap.py          # OpenClaw unified config factory
|   +-- webhook_security.py            # Token + HMAC verification
|-- cli/                               # Unified CLI
|   |-- main.py                        # clawsentry entry (init/gateway/watch/harness)
|   |-- init_command.py                # init + --setup + --auto-detect
|   |-- start_command.py               # Framework detection + start routing
|   |-- watch_command.py               # watch SSE terminal + --interactive DEFER
|   |-- dotenv_loader.py               # .env.clawsentry auto-load
|   +-- initializers/                  # Framework initializers (openclaw/a3s_code)
|-- ui/                                # Web security dashboard (React SPA)
|   |-- src/                           # TypeScript source
|   +-- dist/                          # Pre-built artifacts (shipped with pip)
+-- tests/                             # Test suite (2234 tests)
```

---

## Configuration

### Core

| Variable | Default | Description |
|----------|---------|-------------|
| `CS_AUTH_TOKEN` | (disabled) | HTTP Bearer token (>= 32 chars recommended) |
| `CS_HTTP_HOST` | `127.0.0.1` | HTTP bind address |
| `CS_HTTP_PORT` | `8080` | HTTP port |
| `CS_UDS_PATH` | `/tmp/clawsentry.sock` | UDS listen path |
| `CS_TRAJECTORY_DB_PATH` | `/tmp/clawsentry-trajectory.db` | SQLite trajectory file |

### Detection Tuning (CS_*)

| Variable | Default | Description |
|----------|---------|-------------|
| `CS_COMPOSITE_WEIGHT_MAX_D123` | `0.6` | Weight for max(D1,D2,D3) |
| `CS_COMPOSITE_WEIGHT_D4` | `0.25` | Weight for D4 session risk |
| `CS_COMPOSITE_WEIGHT_D5` | `0.15` | Weight for D5 trust |
| `CS_D6_INJECTION_MULTIPLIER` | `0.5` | D6 multiplier coefficient |
| `CS_THRESHOLD_CRITICAL` | `2.2` | Score threshold for CRITICAL |
| `CS_THRESHOLD_HIGH` | `1.5` | Score threshold for HIGH |
| `CS_THRESHOLD_MEDIUM` | `0.8` | Score threshold for MEDIUM |
| `CS_L2_BUDGET_MS` | `3000` | L2 analysis time budget (ms) |
| `CS_ATTACK_PATTERNS_PATH` | (built-in) | Custom attack patterns YAML |
| `CS_EVOLVING_ENABLED` | `false` | Enable self-evolving pattern repository |
| `CS_EVOLVED_PATTERNS_PATH` | (none) | Path for evolved patterns YAML |
| `CS_POST_ACTION_EMERGENCY` | `0.9` | Post-action EMERGENCY tier threshold |
| `CS_POST_ACTION_ESCALATE` | `0.7` | Post-action ESCALATE tier threshold |
| `CS_POST_ACTION_MONITOR` | `0.4` | Post-action MONITOR tier threshold |

### LLM

| Variable | Description |
|----------|-------------|
| `CS_LLM_PROVIDER` | `anthropic` / `openai` |
| `CS_LLM_BASE_URL` | Custom API endpoint |
| `CS_LLM_MODEL` | Model name |
| `CS_L3_ENABLED` | Enable L3 review Agent |

### OpenClaw

| Variable | Description |
|----------|-------------|
| `OPENCLAW_WS_URL` | OpenClaw Gateway WS URL |
| `OPENCLAW_OPERATOR_TOKEN` | Operator token |
| `OPENCLAW_ENFORCEMENT_ENABLED` | Enable enforcement mode |
| `OPENCLAW_WEBHOOK_TOKEN` | Webhook auth token |
| `OPENCLAW_WEBHOOK_SECRET` | Webhook HMAC secret |

### Session Enforcement

| Variable | Default | Description |
|----------|---------|-------------|
| `AHP_SESSION_ENFORCEMENT_ENABLED` | `false` | Enable session-level cumulative enforcement |
| `AHP_SESSION_ENFORCEMENT_THRESHOLD` | `3` | High-risk event accumulation threshold |
| `AHP_SESSION_ENFORCEMENT_ACTION` | `defer` | Action on trigger (`defer`/`block`/`l3_require`) |

---

## Running Tests

```bash
pip install -e ".[dev]"

# Full suite
python -m pytest src/clawsentry/tests/ -v --tb=short
# Expected: 2234 passed, 3 skipped

# E2E (requires LLM API key)
A3S_SDK_E2E=1 python -m pytest src/clawsentry/tests/ -v --tb=short
# Runs additional a3s-code SDK E2E coverage when a3s_code, agent.hcl, and credentials are available

# By module
python -m pytest src/clawsentry/tests/test_risk_and_policy.py -v
python -m pytest src/clawsentry/tests/test_injection_detector.py -v
python -m pytest src/clawsentry/tests/test_post_action_analyzer.py -v
python -m pytest src/clawsentry/tests/test_trajectory_analyzer.py -v
python -m pytest src/clawsentry/tests/test_pattern_evolution.py -v
python -m pytest src/clawsentry/tests/test_ws_gateway_integration.py -v
python -m pytest src/clawsentry/tests/test_openclaw_e2e.py -v
python -m pytest src/clawsentry/tests/test_detection_config.py -v
```
