clawsentry 0.4.0

AHP unified safety supervision framework for AI agent runtimes.

ClawSentry — AHP Supervision Gateway

Python 3.11+ | 2331 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
• Architecture
• Quick Start
• CLI Commands
• API Endpoints
• Web Dashboard
• Project Structure
• Configuration
• 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

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

clawsentry init openclaw --auto-detect   # Auto-detect ~/.openclaw config
clawsentry init openclaw --setup         # Configure OpenClaw settings
clawsentry start --framework openclaw    # Project env only (no ~/.openclaw edits)
clawsentry start --framework openclaw --setup-openclaw
clawsentry gateway                        # Start (auto-detects OpenClaw)
clawsentry watch                          # Real-time monitoring
# Browser: http://127.0.0.1:8080/ui      # Web dashboard

a3s-code Users

clawsentry init a3s-code
clawsentry gateway
clawsentry watch

---

Framework Compatibility

Framework	Integration mode	Pre-action interception	Post-action observation	Main dependency	Maturity
a3s-code	Explicit SDK transport + clawsentry-harness	Yes	Yes	Agent code must wire SessionOptions.ahp_transport	High
openclaw	WebSocket approvals + webhook receiver	Yes	Yes	~/.openclaw/ must be configured for gateway exec + callbacks	Medium-high
codex	Session JSONL watcher	No	Yes	Session logs must be reachable	Medium
claude-code	Host hooks + clawsentry-harness	Yes	Yes	~/.claude/settings.json hooks must remain installed	Medium

Operational boundary notes:

• codex is an observation path, not a pre-execution interception path.
• a3s-code should be documented as explicit SDK transport wiring, not .a3s-code/settings.json auto-loading.
• openclaw and claude-code provide strong coverage only when host-side setup remains intact.

For a machine-readable local view of the same boundaries, run clawsentry integrations status --json. The command now also emits per-framework readiness diagnostics with concrete next steps, and clawsentry start reuses the same summary in its startup banner.

---

CLI Commands

Command	Description
clawsentry gateway	Start Gateway (auto-detects framework, starts WS/Webhook as needed)
clawsentry start	Auto-init + Gateway + watch; supports --frameworks, explicit --setup-openclaw, and startup readiness summaries
clawsentry integrations status	Inspect enabled frameworks, host-side diagnostics, framework capability summaries, and per-framework readiness
clawsentry watch	SSE real-time display (--filter/--json/--no-color/--interactive)
clawsentry init <framework>	Initialize config (a3s-code/claude-code/codex/openclaw)
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 (2331 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

pip install -e ".[dev]"

# Full suite
python -m pytest src/clawsentry/tests/ -v --tb=short
# Expected: 2331 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