ClawSentry

AHP (Agent Harness Protocol) reference implementation — a unified security supervision gateway for AI agent runtimes.

Features

• Three-tier progressive decision: L1 rule engine (<1 ms) → L2 semantic analysis (<3 s) → L3 review agent (<30 s)
• Six-dimensional risk scoring (D1–D6): command danger / path sensitivity / command patterns / session history / trust level / injection detection
• D6 injection detection: 3-layer analysis — heuristic regex + Canary Token leak + pluggable EmbeddingBackend (vector similarity)
• Post-action security fence: non-blocking post-tool analysis — indirect injection, data exfiltration, secret exposure, obfuscation (4 response tiers)
• 25 built-in attack patterns (v1.1): OWASP ASI01–ASI05, covering supply chain, container escape, reverse shell, staged exfiltration
• Multi-step attack trajectory detection: 5 built-in sequences with sliding-window analysis, SSE trajectory_alert broadcast
• Self-evolving pattern library (E-5): auto-extract candidates from high-risk events, CANDIDATE→EXPERIMENTAL→STABLE lifecycle, confidence scoring, REST API feedback loop
• Tunable detection pipeline: DetectionConfig frozen dataclass with explicit CS_ / project-level overrides, including high-level L3 routing and trigger controls
• Four-framework support with explicit boundaries: a3s-code (explicit SDK transport) + OpenClaw (WS approval + webhook) + Claude Code (host hooks) + Codex CLI (session-log watcher + optional tested PreToolUse(Bash) preflight)
• Real-time monitoring: SSE streaming, clawsentry watch CLI, React/TypeScript web dashboard
• Production security: Bearer token auth, HMAC webhook signatures, UDS chmod 0o600, SSL/TLS, rate limiting
• Session enforcement: auto-escalate after N high-risk events with configurable cooldown
• 3020+ tests, ~45s full suite

Installation

pip install clawsentry           # core
pip install clawsentry[llm]      # + Anthropic/OpenAI for L2/L3
pip install clawsentry[all]      # everything

Requires Python >= 3.11.

What's New in v0.5.2

• L3 advisory async review foundation: frozen evidence snapshots, advisory job queue, explicit worker execution, provider safety gates, and manual real-provider smoke evidence while keeping canonical decisions unchanged.
• Operator-triggered full review: POST /report/session/{session_id}/l3-advisory/full-review and clawsentry l3 full-review --session ... let operators request bounded advisory reviews without scheduler/enforcement.
• Web UI action: Session Detail now includes Request L3 full review, showing advisory completion/queue status directly in the console.

Quick Start

One-Command Launch (Recommended)

clawsentry start                   # auto-detect framework + init + gateway + watch
# or specify framework:
clawsentry start --framework openclaw
clawsentry start --framework a3s-code --interactive  # enable DEFER interaction

The start command will:

1. Auto-detect your framework (a3s-code, Claude Code, Codex, or OpenClaw)
2. Initialize configuration if needed
3. Start the gateway in the background
4. Display live monitoring in the foreground
5. Show Web UI URL with auto-login token

Press Ctrl+C to gracefully shutdown.

clawsentry init <framework> merges into an existing .env.clawsentry by default: existing CS_AUTH_TOKEN and CS_FRAMEWORK values are preserved, and additional frameworks are recorded in CS_ENABLED_FRAMEWORKS (for example a3s-code,codex,openclaw). Use --force only when you want to replace the existing env file.

Start multiple integrations together:

clawsentry start --frameworks a3s-code,codex,openclaw --no-watch
clawsentry integrations status

If you want start to also patch OpenClaw-side approval config, opt in explicitly:

clawsentry start --frameworks codex,openclaw --setup-openclaw --no-watch
clawsentry integrations status --json

integrations status now reports more than enabled frameworks: it also shows OpenClaw backup restore availability, Claude hook source files, Codex session directory reachability, a per-framework readiness verdict with next steps, and a machine-readable framework capability matrix. The multi-framework start banner now prints the same readiness summary before it returns or begins streaming events.

Disable one framework without disturbing the others:

clawsentry init codex --uninstall
clawsentry init claude-code --uninstall  # also removes Claude Code hooks
clawsentry init openclaw --uninstall     # env only; use --restore for OpenClaw-side backups

Manual Step-by-Step

a3s-code

clawsentry init a3s-code           # generate .env.clawsentry
clawsentry gateway                 # start gateway (default :8080)
clawsentry watch                   # tail live decisions in your terminal

Wire a3s-code through explicit SDK transport in your agent script, for example SessionOptions().ahp_transport = StdioTransport(program="clawsentry-harness", args=[]). Do not rely on .a3s-code/settings.json for AHP; the current upstream runtime does not auto-load it.

OpenClaw

clawsentry init openclaw           # generate project env only
clawsentry init openclaw --setup   # opt-in: patch OpenClaw settings
clawsentry gateway                 # start gateway (default :8080)
open http://localhost:8080/ui      # open web dashboard

OpenClaw setup is explicit opt-in. Plain init openclaw and start --frameworks do not modify ~/.openclaw/. Setup writes .bak backups before changing OpenClaw-side config. To preview or restore those backups:

clawsentry init openclaw --restore --dry-run
clawsentry init openclaw --restore

Framework Compatibility

Framework	Integration mode	Pre-action interception	Post-action observation	Main dependency
a3s-code	Explicit SDK transport + clawsentry-harness	Yes	Yes	Agent code must wire SessionOptions.ahp_transport
openclaw	WebSocket approvals + webhook receiver	Yes	Yes	~/.openclaw/ must be configured for gateway exec + callbacks
codex	Session JSONL watcher + optional native hooks	No by default; optional tested PreToolUse(Bash) preflight	Yes	Session logs / optional .codex/hooks.json must be reachable
claude-code	Host hooks + clawsentry-harness	Yes	Yes	~/.claude/settings.json hooks must remain installed

codex should be understood as observation-first by default; optional managed native hooks now provide a narrow tested PreToolUse(Bash) deny path, while PostToolUse, UserPromptSubmit, Stop, and SessionStart remain advisory/observational. a3s-code should be understood as explicit transport wiring, not .a3s-code/settings.json auto-loading. claude-code and openclaw remain more host-config-dependent than a3s-code.

For a machine-readable local view of the same boundaries, run clawsentry integrations status --json.

Architecture

Decision tiers:

• L1 PolicyEngine — deterministic rule scoring across six risk dimensions (D1–D6), sub-millisecond latency
  • Composite score: base = 0.4×max(D1,D2,D3) + 0.25×D4 + 0.15×D5; score = base × (1.0 + 0.5×D6/3.0)
  • Risk thresholds: LOW < 0.8 / MEDIUM 0.8–1.5 / HIGH 1.5–2.2 / CRITICAL ≥ 2.2
• L2 SemanticAnalyzer — LLM-backed semantic analysis with configurable provider (Anthropic / OpenAI / rule-based fallback); 25-pattern attack library + trajectory analysis
• L3 AgentAnalyzer — multi-turn review agent with read-only toolkit and per-session skill dispatch
• PostActionAnalyzer — non-blocking post-execution fence; 4 detectors × 4 response tiers

Documentation

Full documentation is available at https://elroyper.github.io/ClawSentry/

• Getting Started
• Core Concepts
• a3s-code Integration
• OpenClaw Integration
• L1 Rules Engine
• L2 Semantic Analysis
• Configuration Reference
• REST & SSE API

Key Environment Variables

Variable	Default	Description
CS_AUTH_TOKEN	(required)	Bearer token for all REST / SSE endpoints
AHP_LLM_PROVIDER	rule_based	LLM backend for L2/L3: anthropic, openai, or rule_based
AHP_L3_ENABLED	false	Enable L3 multi-turn review agent
AHP_SESSION_ENFORCEMENT_ENABLED	false	Auto-escalate sessions after N high-risk events
OPENCLAW_WS_URL	—	WebSocket URL of a running OpenClaw gateway
CS_EVOLVING_ENABLED	false	Enable self-evolving pattern library (E-5)
CS_EVOLVED_PATTERNS_PATH	—	Path to store evolved patterns YAML
CS_ATTACK_PATTERNS_PATH	(built-in)	Path to custom attack patterns YAML (hot-reload)
CS_THRESHOLD_CRITICAL	2.2	Risk score threshold for CRITICAL level
CS_THRESHOLD_HIGH	1.5	Risk score threshold for HIGH level
CS_THRESHOLD_MEDIUM	0.8	Risk score threshold for MEDIUM level
CS_POST_ACTION_WHITELIST	—	Comma-separated regex list for post-action path whitelist

See the full configuration reference for all 20+ tunable parameters.

License

MIT — see LICENSE