clawsentry 0.2.0__tar.gz

clawsentry-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClawSentry Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clawsentry-0.2.0/PKG-INFO

@@ -0,0 +1,469 @@
+Metadata-Version: 2.4
+Name: clawsentry
+Version: 0.2.0
+Summary: AHP unified safety supervision framework for AI agent runtimes.
+Author: ClawSentry Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Elroyper/ClawSentry
+Project-URL: Documentation, https://elroyper.github.io/ClawSentry/
+Project-URL: Repository, https://github.com/Elroyper/ClawSentry
+Project-URL: Changelog, https://github.com/Elroyper/ClawSentry/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/Elroyper/ClawSentry/issues
+Keywords: ai-safety,agent-supervision,llm-security,runtime-monitor,ahp,policy-engine
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn[standard]>=0.23
+Requires-Dist: pydantic>=2.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.20; extra == "llm"
+Requires-Dist: openai>=1.10; extra == "llm"
+Provides-Extra: enforcement
+Requires-Dist: websockets<16.0,>=12.0; extra == "enforcement"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+Requires-Dist: websockets<16.0,>=12.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: clawsentry[llm]; extra == "all"
+Requires-Dist: clawsentry[enforcement]; extra == "all"
+Requires-Dist: clawsentry[dev]; extra == "all"
+Dynamic: license-file
+
+# ClawSentry — AHP 安全监督网关
+
+> **Python 3.11+** | **775 tests** | 协议版本 `ahp.1.0`
+
+**ClawSentry** 是 AHP（Agent Harness Protocol）的 Python 参考实现，面向多 Agent 框架的统一安全监督网关。它以 Sidecar 形式部署，将来自不同运行时（a3s-code、OpenClaw 等）的事件归一化为统一协议，经过三层递进式风险评估后产生实时决策（放行 / 拦截 / 修改 / 延迟），并保留完整的审计轨迹。
+
+**核心目标**：消除跨框架的策略重复实现与可观测性碎片化，用"协议优先、决策集中"的方式统一 Agent 安全监管。
+
+---
+
+## 目录
+
+- [三层决策模型](#三层决策模型)
+- [架构概览](#架构概览)
+- [快速开始](#快速开始)
+- [CLI 命令](#cli-命令)
+- [API 端点](#api-端点)
+- [Web 安全仪表板](#web-安全仪表板)
+- [项目结构](#项目结构)
+- [配置参数](#配置参数)
+- [运行测试](#运行测试)
+- [设计文档索引](#设计文档索引)
+
+---
+
+## 三层决策模型
+
+本框架采用**分层递进**的评估架构，每层有明确的延迟预算和职责边界：
+
+```
+                    事件流量 100%
+                        │
+                 ┌──────▼──────┐
+                 │  L1 规则引擎  │  ← 确定性规则，< 1ms
+                 └──────┬──────┘
+                        │
+            ┌───────────┼───────────┐
+            ▼           ▼           ▼
+     LOW (allow)   MEDIUM (?)   CRITICAL (block)
+      ~60%流量      ~30%流量      ~10%流量
+         │              │           │
+         │       ┌──────▼──────┐   │
+         │       │  L2 语义引擎  │   │  ← 可插拔 LLM，< 3s
+         │       └──────┬──────┘   │
+         │              │          │
+         │       ┌──────▼──────┐   │
+         │       │  L3 审查Agent │   │  ← 多轮工具调用，< 30s
+         │       └──────┬──────┘   │
+         │              │          │
+         ▼              ▼          ▼
+       allow      allow/block    block
+```
+
+| 层级 | 实现 | 延迟 | 依赖 | 激活方式 |
+|------|------|------|------|---------|
+| **L1** 规则引擎 | D1-D5 五维评分 + 短路规则 | < 1ms | 无 | 默认启用 |
+| **L2** 语义分析 | RuleBased / LLM / Composite | < 3s | Anthropic/OpenAI API (可选) | `CS_LLM_PROVIDER` 环境变量 |
+| **L3** 审查 Agent | AgentAnalyzer + ReadOnlyToolkit + SkillRegistry | < 30s | LLM API | `CS_L3_ENABLED=true` |
+
+### D1-D5 五维风险评估
+
+| 维度 | 评估对象 | 分值 |
+|------|---------|------|
+| **D1** 工具类型 | 工具本身的风险等级 (bash=3, read_file=0) | 0-3 |
+| **D2** 目标路径 | 操作涉及的文件/路径 (/etc/passwd=3, /tmp=0) | 0-3 |
+| **D3** 命令模式 | bash/exec 命令内容 (rm -rf=3, ls=0) | 0-3 |
+| **D4** 会话累积 | 该会话已发生的高危事件数 | 0-2 |
+| **D5** 信任等级 | Agent 的权限层级 | 0-2 |
+
+**短路规则**：D1=3 且 D2>=2 → CRITICAL | D3=3 → CRITICAL | D1=D2=D3=0 → LOW
+
+---
+
+## 架构概览
+
+```
+ ┌──────────────────────────────────────────────────────────────────┐
+ │              Framework Runtime Layer                              │
+ │  ┌──────────────────┐          ┌─────────────────────────┐      │
+ │  │ a3s-code (Rust)   │          │  OpenClaw (TypeScript)   │      │
+ │  │   stdio Hook      │          │  WS exec.approval        │      │
+ │  └────────┬─────────┘          └──────────┬──────────────┘      │
+ └───────────┼───────────────────────────────┼─────────────────────┘
+             │                               │
+ ┌───────────▼───────────────────────────────▼─────────────────────┐
+ │                    Adapter Layer                                  │
+ │  ┌──────────────────┐     ┌──────────────────────────────┐      │
+ │  │  A3SCodeAdapter   │     │  OpenClawAdapter + WS Client │      │
+ │  │  + Harness 桥接   │     │  + Webhook Receiver          │      │
+ │  └────────┬─────────┘     └──────────┬───────────────────┘      │
+ └───────────┼──────────────────────────┼──────────────────────────┘
+             │   UDS / HTTP (JSON-RPC)  │
+ ┌───────────▼──────────────────────────▼──────────────────────────┐
+ │              ClawSentry — AHP Supervision Gateway                 │
+ │                                                                   │
+ │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────────┐   │
+ │  │ L1 Rules │→│ L2 LLM   │→│ L3 Agent │→│ Decision Router │   │
+ │  │ D1-D5    │  │ Semantic │  │ Toolkit  │  │ allow/block/   │   │
+ │  │ <1ms     │  │ <3s      │  │ <30s     │  │ modify/defer   │   │
+ │  └──────────┘  └──────────┘  └──────────┘  └───────┬────────┘   │
+ │                                                      │            │
+ │  ┌─────────────────┐  ┌────────────────┐  ┌─────────▼────────┐  │
+ │  │ SessionRegistry  │  │  AlertRegistry │  │ TrajectoryStore  │  │
+ │  │ 会话风险跟踪     │  │  告警管理      │  │ SQLite 审计轨迹  │  │
+ │  └─────────────────┘  └────────────────┘  └──────────────────┘  │
+ │                                                                   │
+ │  ┌─────────────────┐  ┌────────────────┐  ┌──────────────────┐  │
+ │  │ EventBus + SSE  │  │ Idempotency    │  │ Web Dashboard    │  │
+ │  │ 实时事件推送     │  │ Cache (去重)   │  │ React SPA at /ui │  │
+ │  └─────────────────┘  └────────────────┘  └──────────────────┘  │
+ └──────────────────────────────────────────────────────────────────┘
+```
+
+**设计原则**：
+
+| 原则 | 说明 |
+|------|------|
+| 协议优先 | 先解决跨框架互操作，再叠加策略 |
+| 决策集中 | 所有最终决策由 Gateway 产生，Adapter 不做决策 |
+| 双通道处理 | pre-action 同步拦截，post-action 异步审计 |
+| 仅升级不降级 | L2/L3 只能把风险往上调，确保安全下限 |
+| fail-closed | 高危操作在 Gateway 不可达时默认拦截 |
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+# 基础安装
+pip install clawsentry
+
+# 含 OpenClaw WS 集成
+pip install "clawsentry[enforcement]"
+
+# 含 LLM 语义分析
+pip install "clawsentry[llm]"
+
+# 全量安装（含开发依赖）
+pip install "clawsentry[all]"
+
+# 开发模式（从源码）
+git clone <repo-url> && cd ClawSentry
+pip install -e ".[dev]"
+```
+
+### OpenClaw 用户（推荐流程）
+
+```bash
+# 1. 一键初始化（自动探测 ~/.openclaw/openclaw.json 提取 token/端口）
+clawsentry init openclaw --auto-detect
+
+# 2. 自动配置 OpenClaw（设置 tools.exec.host + exec-approvals）
+clawsentry init openclaw --setup
+
+# 3. 启动 Gateway（自动检测 OpenClaw 配置，按需启动 WS/Webhook）
+clawsentry gateway
+
+# 4. 实时监控（另一终端）
+clawsentry watch
+
+# 5. Web 仪表板
+# 浏览器打开 http://127.0.0.1:8080/ui
+```
+
+### a3s-code 用户
+
+```bash
+# 1. 初始化配置
+clawsentry init a3s-code
+
+# 2. 启动 Gateway
+clawsentry gateway
+
+# 3. 在 a3s-code 中配置 AHP transport
+#    opts.ahp_transport = StdioTransport(program="clawsentry-harness")
+
+# 4. 实时监控
+clawsentry watch
+```
+
+### 直接调用 Gateway (JSON-RPC)
+
+```bash
+# 通过 HTTP 发送决策请求
+curl -X POST http://127.0.0.1:8080/ahp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-token>" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "ahp/sync_decision",
+    "id": "req-001",
+    "params": {
+      "rpc_version": "sync_decision.1.0",
+      "request_id": "req-001",
+      "deadline_ms": 100,
+      "decision_tier": "L1",
+      "event": {
+        "schema_version": "ahp.1.0",
+        "event_id": "evt-001",
+        "trace_id": "trace-001",
+        "event_type": "pre_action",
+        "session_id": "sess-abc",
+        "agent_id": "agent-001",
+        "source_framework": "a3s-code",
+        "occurred_at": "2025-01-01T00:00:00Z",
+        "payload": {"tool": "bash", "command": "ls"},
+        "event_subtype": "tool:execute"
+      }
+    }
+  }'
+```
+
+---
+
+## CLI 命令
+
+统一入口 `clawsentry`，行为由配置自动决定：
+
+| 命令 | 说明 |
+|------|------|
+| `clawsentry gateway` | 启动 Gateway（自动检测 OpenClaw 配置，按需启动 WS/Webhook） |
+| `clawsentry watch` | 连接 SSE 实时展示决策（`--filter`/`--json`/`--no-color`/`--interactive`） |
+| `clawsentry init <framework>` | 一键初始化配置（`openclaw`/`a3s-code`） |
+| `clawsentry init openclaw --auto-detect` | 自动探测 `~/.openclaw/openclaw.json` 提取 token/端口 |
+| `clawsentry init openclaw --setup` | 自动配置 OpenClaw（`tools.exec.host` + `exec-approvals`） |
+| `clawsentry harness` | a3s-code stdio 桥接子进程 |
+
+**环境变量自动加载**：Gateway 启动时自动读取 `.env.clawsentry` 文件（不覆盖已有环境变量）。
+
+---
+
+## API 端点
+
+所有端点需 `Authorization: Bearer <token>` 认证（`/health` 和 `/ui` 除外）。SSE 端点支持 `?token=xxx` query param 认证（`EventSource` 不支持自定义 header）。
+
+### 决策
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/ahp` | JSON-RPC 同步决策（ahp/sync_decision） |
+| POST | `/ahp/resolve` | DEFER 决策代理（allow-once/deny），503 当无 OpenClaw |
+
+### 报表 & 监控
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/health` | 健康检查（无需认证，K8s probe 兼容） |
+| GET | `/report/summary` | 跨框架聚合统计（支持 `window_seconds` 参数） |
+| GET | `/report/sessions` | 活跃会话列表 + 风险排序 |
+| GET | `/report/session/{id}` | 会话轨迹回放 |
+| GET | `/report/session/{id}/risk` | 会话风险详情 + D1-D5 时间线 |
+| GET | `/report/stream` | SSE 实时事件推送（decision/session_start/session_risk_change/alert） |
+| GET | `/report/alerts` | 告警列表（过滤: severity/acknowledged/window_seconds） |
+| POST | `/report/alerts/{id}/acknowledge` | 确认告警 |
+
+### Web 界面
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/ui` | Web 安全仪表板 SPA（无需认证） |
+
+---
+
+## Web 安全仪表板
+
+Gateway 内置 React SPA 安全仪表板，通过 `/ui` 路径访问。暗色 SOC 主题，实时 SSE 数据推送。
+
+| 页面 | 功能 |
+|------|------|
+| **Dashboard** | 实时决策 feed + 4 指标卡 + 风险分布图 + 决策来源图 |
+| **Sessions** | 活跃会话列表 + D1-D5 雷达图 + 风险曲线 + 决策时间线 |
+| **Alerts** | 告警表格 + severity/acknowledged 过滤 + 确认按钮 + SSE 自动推送 |
+| **DEFER Panel** | 待决策列表 + 倒计时器 + Allow/Deny 按钮 + 503 降级提示 |
+
+技术栈：React 18 + TypeScript + Vite + recharts + lucide-react
+
+---
+
+## 项目结构
+
+```
+src/clawsentry/
+├── gateway/                           # 核心监督引擎
+│   ├── models.py                      # 统一数据模型 (CanonicalEvent / Decision / RiskSnapshot)
+│   ├── server.py                      # FastAPI HTTP + UDS 双传输 + Auth + SSE + 静态文件
+│   ├── stack.py                       # 一键启动 Gateway + OpenClaw 运行时 + DEFER resolve
+│   ├── policy_engine.py               # L1 规则 + L2 Analyzer 集成
+│   ├── risk_snapshot.py               # D1-D5 五维风险评估
+│   ├── semantic_analyzer.py           # L2 可插拔语义分析 (Protocol + 3 种实现)
+│   ├── llm_provider.py                # LLM Provider 基类 (Anthropic/OpenAI)
+│   ├── llm_factory.py                 # 环境变量驱动 analyzer 构建
+│   ├── agent_analyzer.py              # L3 审查 Agent (MVP 单轮 + 标准多轮)
+│   ├── review_toolkit.py              # L3 ReadOnlyToolkit (5 个只读工具)
+│   ├── review_skills.py               # L3 SkillRegistry (YAML 加载/选择)
+│   ├── l3_trigger.py                  # L3 触发策略 (4 类触发条件)
+│   ├── idempotency.py                 # 请求幂等性缓存
+│   └── skills/                        # 6 个内置审查领域 skill (YAML)
+├── adapters/                          # 框架适配器
+│   ├── a3s_adapter.py                 # a3s-code Hook → CanonicalEvent 归一化
+│   ├── a3s_gateway_harness.py         # a3s-code stdio 桥接 (JSON-RPC 2.0)
+│   ├── openclaw_adapter.py            # OpenClaw 主适配器 (含审批状态机)
+│   ├── openclaw_normalizer.py         # OpenClaw 事件归一化
+│   ├── openclaw_ws_client.py          # OpenClaw WS 客户端 (事件监听 + resolve)
+│   ├── openclaw_webhook_receiver.py   # OpenClaw Webhook 安全接收器
+│   ├── openclaw_gateway_client.py     # OpenClaw → Gateway RPC 客户端
+│   ├── openclaw_approval.py           # 审批生命周期状态机
+│   ├── openclaw_bootstrap.py          # OpenClaw 统一配置工厂
+│   └── webhook_security.py            # Token + HMAC 校验
+├── cli/                               # 统一 CLI
+│   ├── main.py                        # clawsentry 入口 (init/gateway/watch/harness)
+│   ├── init_command.py                # init 命令 + --setup + --auto-detect
+│   ├── watch_command.py               # watch SSE 实时终端 + --interactive DEFER
+│   ├── dotenv_loader.py               # .env.clawsentry 自动加载
+│   └── initializers/                  # 框架初始化器 (openclaw/a3s_code)
+├── ui/                                # Web 安全仪表板 (React SPA)
+│   ├── src/                           # TypeScript 源码
+│   │   ├── api/                       # API client + SSE + types
+│   │   ├── hooks/                     # useAuth
+│   │   ├── components/                # Layout, StatusBar, badges, etc.
+│   │   └── pages/                     # Dashboard, Sessions, Alerts, DeferPanel
+│   └── dist/                          # 预构建产物 (随 pip 包分发)
+└── tests/                             # 测试套件 (775 tests)
+```
+
+---
+
+## 配置参数
+
+### 核心环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `CS_AUTH_TOKEN` | (禁用) | HTTP 端点 Bearer token（建议 >= 32 字符） |
+| `CS_HTTP_HOST` | `127.0.0.1` | HTTP 绑定地址 |
+| `CS_HTTP_PORT` | `8080` | HTTP 端口 |
+| `CS_UDS_PATH` | `/tmp/clawsentry.sock` | UDS 监听地址 |
+| `CS_TRAJECTORY_DB_PATH` | `/tmp/clawsentry-trajectory.db` | SQLite 轨迹文件 |
+
+### LLM 配置
+
+| 变量 | 说明 |
+|------|------|
+| `CS_LLM_PROVIDER` | LLM 提供商 (`anthropic` / `openai`) |
+| `CS_LLM_BASE_URL` | 自定义 API 端点 |
+| `CS_LLM_MODEL` | 模型名称 |
+| `CS_L3_ENABLED` | 启用 L3 审查 Agent (`true`/`false`) |
+
+### OpenClaw 配置
+
+| 变量 | 说明 |
+|------|------|
+| `OPENCLAW_WS_URL` | OpenClaw Gateway WS 地址 |
+| `OPENCLAW_OPERATOR_TOKEN` | 操作员令牌 |
+| `OPENCLAW_ENFORCEMENT_ENABLED` | 启用执法模式 (`true`/`false`) |
+| `OPENCLAW_WEBHOOK_TOKEN` | Webhook 认证 token |
+| `OPENCLAW_WEBHOOK_SECRET` | Webhook HMAC 签名密钥 |
+
+### 会话强制策略
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `AHP_SESSION_ENFORCEMENT_ENABLED` | `false` | 启用会话级累积高危强制策略 |
+| `AHP_SESSION_ENFORCEMENT_THRESHOLD` | `3` | 触发强制的高危事件累积阈值 |
+| `AHP_SESSION_ENFORCEMENT_ACTION` | `defer` | 触发后的动作 (`defer`/`block`/`l3_require`) |
+| `AHP_SESSION_ENFORCEMENT_COOLDOWN_SECONDS` | `600` | 强制状态冷却时间（秒） |
+
+### 安全加固
+
+| 变量 | 说明 |
+|------|------|
+| `CS_RATE_LIMIT_PER_MINUTE` | 速率限制（默认 300/分钟） |
+| `AHP_SSL_CERTFILE` | SSL 证书路径（启用 HTTPS） |
+| `AHP_SSL_KEYFILE` | SSL 私钥路径 |
+| `AHP_WEBHOOK_IP_WHITELIST` | Webhook 来源 IP 白名单（逗号分隔） |
+| `AHP_WEBHOOK_TOKEN_TTL_SECONDS` | Webhook Token 有效期（秒） |
+| `AHP_SKILLS_DIR` | L3 自定义 Skills 目录路径 |
+
+---
+
+## 运行测试
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行全部测试
+python -m pytest src/clawsentry/tests/ -v --tb=short
+# 预期：775 passed
+
+# 按模块运行
+python -m pytest src/clawsentry/tests/test_risk_and_policy.py -v    # L1 风险评估
+python -m pytest src/clawsentry/tests/test_semantic_analyzer.py -v  # L2 语义分析
+python -m pytest src/clawsentry/tests/test_agent_analyzer.py -v     # L3 审查 Agent
+python -m pytest src/clawsentry/tests/test_gateway.py -v            # Gateway 协议
+python -m pytest src/clawsentry/tests/test_openclaw_adapter.py -v   # OpenClaw 适配器
+python -m pytest src/clawsentry/tests/test_ws_gateway_integration.py -v  # WS 全链路集成
+python -m pytest src/clawsentry/tests/test_a3s_e2e_integration.py -v     # a3s-code E2E
+python -m pytest src/clawsentry/tests/test_http_auth.py -v          # HTTP 认证
+python -m pytest src/clawsentry/tests/test_resolve_endpoint.py -v   # DEFER resolve
+python -m pytest src/clawsentry/tests/test_ui_static.py -v          # Web UI 静态文件
+python -m pytest src/clawsentry/tests/test_cli_init.py -v           # CLI init
+python -m pytest src/clawsentry/tests/test_watch_command.py -v      # watch 命令
+```
+
+---
+
+## 设计文档索引
+
+详细设计文档位于 `docs/designs/ClawSentry/`:
+
+| 文档 | 内容 | 状态 |
+|------|------|------|
+| `01-scope-and-architecture.md` | 整体范围、架构层次、部署模型 | FROZEN |
+| `02-unified-ahp-contract.md` | Canonical Event / Decision 统一合约 | FROZEN |
+| `03-openclaw-adapter-design.md` | OpenClaw 适配器设计 | FROZEN |
+| `04-policy-decision-and-fallback.md` | 决策模型、风险评分、超时/重试/降级 | FROZEN |
+| `05-trajectory-observability-audit.md` | 审计轨迹与合规报告 | FROZEN |
+| `06-rollout-validation-and-risks.md` | 分阶段上线风险与验证检查点 | FROZEN |
+| `07-openclaw-field-level-mapping.md` | OpenClaw 字段级映射 | FROZEN |
+| `08-openclaw-webhook-security-hardening.md` | Webhook 安全补强方案 | FROZEN |
+| `09-l2-pluggable-semantic-analysis.md` | L2 可插拔语义分析架构 | FROZEN |
+| `10-http-endpoint-auth.md` | HTTP Bearer Token 认证 | FROZEN |
+| `11-long-term-evolution-vision.md` | 长期演进路线图 (Phase 5+) | ACTIVE |

clawsentry-0.2.0/README.md

@@ -0,0 +1,105 @@
+[![PyPI](https://img.shields.io/pypi/v/clawsentry)](https://pypi.org/project/clawsentry/) [![Python](https://img.shields.io/pypi/pyversions/clawsentry)](https://pypi.org/project/clawsentry/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Docs](https://img.shields.io/badge/docs-online-blue)](https://elroyper.github.io/ClawSentry/)
+
+# 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)
+- **Dual framework support**: a3s-code (stdio / HTTP) + OpenClaw (WebSocket / Webhook)
+- **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
+- **775+ tests**, ~6.5 s full suite
+
+## Installation
+
+```bash
+pip install clawsentry           # core
+pip install clawsentry[llm]      # + Anthropic/OpenAI for L2/L3
+pip install clawsentry[all]      # everything
+```
+
+Requires Python >= 3.11.
+
+## Quick Start
+
+### One-Command Launch (Recommended)
+
+```bash
+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 (OpenClaw or a3s-code)
+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.
+
+### Manual Step-by-Step
+
+#### a3s-code
+
+```bash
+clawsentry init a3s-code --setup   # generate config + patch a3s-code settings
+clawsentry gateway                 # start gateway (default :8080)
+clawsentry watch                   # tail live decisions in your terminal
+```
+
+#### OpenClaw
+
+```bash
+clawsentry init openclaw --setup   # generate config + patch OpenClaw settings
+clawsentry gateway                 # start gateway (default :8080)
+open http://localhost:8080/ui      # open web dashboard
+```
+
+## Architecture
+
+```
+a3s-code ──→ A3S Adapter ──┐
+                            ├──→ AHP CanonicalEvent ──→ PolicyEngine ──→ L1/L2/L3
+OpenClaw ──→ OC Adapter ───┘                                                │
+                                                            SessionRegistry ←┘
+                                                            EventBus ──→ SSE / CLI / Web UI
+```
+
+**Decision tiers:**
+
+- **L1 PolicyEngine** — deterministic rule scoring across five risk dimensions (D1–D5), sub-millisecond latency
+- **L2 SemanticAnalyzer** — LLM-backed semantic analysis with configurable provider (Anthropic / OpenAI / rule-based fallback)
+- **L3 AgentAnalyzer** — multi-turn review agent with read-only toolkit and per-session skill dispatch
+
+## Documentation
+
+Full documentation is available at **https://elroyper.github.io/ClawSentry/**
+
+- [Getting Started](https://elroyper.github.io/ClawSentry/getting-started/)
+- [Architecture Overview](https://elroyper.github.io/ClawSentry/architecture/)
+- [a3s-code Integration Guide](https://elroyper.github.io/ClawSentry/guides/a3s-code/)
+- [OpenClaw Integration Guide](https://elroyper.github.io/ClawSentry/guides/openclaw/)
+- [Configuration Reference](https://elroyper.github.io/ClawSentry/reference/configuration/)
+- [REST & SSE API](https://elroyper.github.io/ClawSentry/reference/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 |
+
+See the [full configuration reference](https://elroyper.github.io/ClawSentry/reference/configuration/) for all variables.
+
+## License
+
+MIT — see [LICENSE](LICENSE)

clawsentry-0.2.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clawsentry"
+version = "0.2.0"
+description = "AHP unified safety supervision framework for AI agent runtimes."
+readme = "src/clawsentry/README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "ClawSentry Contributors"},
+]
+keywords = [
+    "ai-safety",
+    "agent-supervision",
+    "llm-security",
+    "runtime-monitor",
+    "ahp",
+    "policy-engine",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "fastapi>=0.100",
+    "uvicorn[standard]>=0.23",
+    "pydantic>=2.0",
+    "PyYAML>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Elroyper/ClawSentry"
+Documentation = "https://elroyper.github.io/ClawSentry/"
+Repository = "https://github.com/Elroyper/ClawSentry"
+Changelog = "https://github.com/Elroyper/ClawSentry/blob/main/CHANGELOG.md"
+"Bug Tracker" = "https://github.com/Elroyper/ClawSentry/issues"
+
+[project.optional-dependencies]
+llm = [
+    "anthropic>=0.20",
+    "openai>=1.10",
+]
+enforcement = [
+    "websockets>=12.0,<16.0",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "httpx>=0.24",
+    "websockets>=12.0,<16.0",
+]
+all = [
+    "clawsentry[llm]",
+    "clawsentry[enforcement]",
+    "clawsentry[dev]",
+]
+
+[project.scripts]
+clawsentry = "clawsentry.cli.main:main"
+clawsentry-gateway = "clawsentry.gateway.server:main"
+clawsentry-harness = "clawsentry.adapters.a3s_gateway_harness:main"
+clawsentry-stack = "clawsentry.gateway.stack:main"
+
+[tool.setuptools.package-data]
+clawsentry = ["ui/dist/**", "gateway/skills/*.yaml", "gateway/attack_patterns.yaml"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["clawsentry*"]
+exclude = ["clawsentry.tests*"]
+
+[tool.pytest.ini_options]
+testpaths = ["src/clawsentry/tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"