butterclaw-tech/butterclaw

``` ██████╗ ██╗ ██╗████████╗████████╗███████╗██████╗ ██████╗██╗ █████╗ ██╗ ██╗ ██╔══██╗██║ ██║╚══██╔══╝╚══██╔══╝██╔════╝██╔══██╗██╔════╝██║ ██╔══██╗██║ ██║ ██████╔╝██║ ██║ ██║ ██║ █████╗ ██████╔╝██║ ██║ ███████║██║ █╗ ██║ ██╔══██╗██║ ██║ ██║ ██║ ██╔══╝ ██╔══██╗██║ ██║ ██╔══██║██║███╗██║ ██████╔╝╚██████╔╝ ██║ ██║ ███████╗██║ ██║╚██████╗███████╗██║ ██║╚███╔███╔╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝ ╚═════╝╚══════╝╚═╝ ╚═╝ ╚══╝╚══╝ ``` # 🦞 ButterClaw v0.6.5：Agentic SOC [](https://opensource.org/licenses/Apache-2.0) [](CHANGELOG.md) [](https://butterclaw.tech) 用于自主 AI 的本地优先动态响应系统。ButterClaw 使用本地化推理引擎来捕获混淆的 prompt injection。特色是 **ButterVault**：一个零信任凭据保险柜，如果检测到违规行为，它会将您的 API key、OAuth token 和 API key hash 物理性地粉碎成加密垃圾。现在具有**确定性 policy guardrails**、**外部 alert dispatch** 和**生产就绪的部署打包** —— Sentinel 可以部署在任何地方。**先评估，后执行。** 当授权的 AI Agent 通过**间接 prompt injection**或**跨站 WebSocket 劫持（CSWH）**被攻陷时，传统的安全边界就会失效。ButterClaw 充当“中间人 LLM”安全运营中心（SOC），主动监控原始 OS 级遥测数据。 ### 🦞 澄清说明 **ButterClaw Tech (butterclaw.tech)** 是一个独立的、从头开始构建的本地优先 Agentic SOC 和动态安全层，专为自主 AI 系统设计。 它**不**附属于： * `butterclaw.ai` —— 一个基于 OpenClaw 构建的托管托管服务。 * OpenClaw 或任何 OpenClaw 分支（包括 `ai‑nhancement/ButterClaw`）。 * 生态系统中的任何其他“ButterClaw”项目。 ButterClaw Tech 拥有自己的架构、runtime、内存模型和执行语义。它的存在是为了监视、审计和保护 agentic 系统——而不是成为另一个 agent runtime。 **如果您正在寻找：** * **托管式 OpenClaw 体验？** → 使用 `butterclaw.ai` 或 Hostinger 的一键式解决方案。 * **通用的自主 agent 框架？** → 使用 OpenClaw 或 Hermes-Agent。 * **具有行为漂移跟踪、双半球推理和真正能粉碎密钥的保险库的本地优先动态安全层？** → 您找对地方了 ([ButterClaw.tech](https://butterclaw.tech))。 ## 🚀 v0.6.5 的新特性（外骨骼已封印）？ **版本 0.6.5** 是专为 Hacker News 发布而准备的官方代码锁定、数学级封印的生产版本。它引入了确定性的零日防御、实时的终端矩阵以及大规模的安全加固。 * **Zero-Day Arsenal (`default_signatures.json`)：** 内置 5 个预编译的 regex signature，开箱即用地针对 CSWH 和 prompt injection。在 LLM Brain 甚至对其进行评估之前的几毫秒内拦截威胁。 * **The Paranoia Dial：** 可扩展的动态响应系统。Level 1（观察），Level 2（主动防御：仅 SIGKILL），Level 3（Air-Gapped Lockdown：SIGKILL + 粉碎保险柜）。 * **可视化 TUI 仪表盘 (`.\dash`)：** 实时、双缓冲、无闪烁的终端界面，在 Linux 和 Windows Docker 主机上显示实时的 SOC 遥测数据、活动的规则以及当前的 Paranoia 级别。 * **审计修复与加固：** 系统性地根除了 29 个不同的漏洞、竞态条件和线程泄漏。Gibson 竞态条件已得到数学意义上的封印，SMTP 密码现在在静止时进行加密，并且 SQLite 的暴力破解跟踪是完全持久化的。 - **Live Fire 测试脚本 (`scripts/add_rule.py`, `scripts/test_attack.py`)：** 独立的诊断测试工具，允许操作员安全地注入自定义 regex signature，并针对 Arsenal 模拟动态的 prompt injection 攻击，而无需活动的 LLM payload。 * **社区贡献：** Telegram Alert Channel —— 原生的 Telegram Bot API 支持已添加到 Alert Dispatcher 中。操作员可以将 SOC alert 通过 🔴/🟡/🟢 严重性格式化和自动的 4096 字符 payload 限制路由到移动设备。（由 @huanghaiyss 贡献） ## 🚀 v0.6.4 的新特性（自主部署）？ **版本 0.6.4** 结合了上一个功能版本 (0.6.3) 的最后两个错误修复版本的补丁。并添加了一键式自主安装脚本，以减少安装过程中的摩擦。 * **一键式部署** 添加了一个自主的 install.sh 脚本，可将实现价值的时间缩短至 60 秒以内。 * **The Exoskeleton 加固** 统一了 v0.6.3 补丁周期，最终确定了 Nginx TLS 路由、Docker bridge 修复以及主动的 token 刺杀网络层。 ## 🚀 v0.6.3.2 的新特性（主动工具与 Nginx 路由）？ **版本 0.6.3.2** 完全隔离了应用程序后端，并将 Gibson kill-switch 从本地擦除升级为主动的网络级威胁响应。 * **主动 Token 刺杀 (`buttervault.py`)：** 当 `DRY_RUN=False` 时，Gibson 不再只是粉碎本地 SQLite 文件。它现在会向 GitHub 和其他外部 OAuth provider 发送实时的 HTTP `DELETE` 和 `POST` 请求，以便在烧毁本地数据库*之前*立即使 token 全局失效。 * **双重 Air-Gap (`DRY_RUN`)：** 堵住了一个手动 UI 按钮绕过安全保护的关键漏洞。Gibson 现在包含一个硬编码的、低级别的 `DRY_RUN` 检查，阻止所有动态操作，从而保证安全的本地 prompt injection 测试。 * **端口 5000 隔离：** 移除了 Docker 中原始暴露的 5000 端口。所有 UI 和 API 流量（`index.html` 和 `routing.html`）现在都使用本地 TLS 证书通过标准 Web 端口 (80/443) 上的 Nginx 反向代理进行安全路由。 * **SSRF 锁定 (`butterclaw_mcp.py`)：** 将 `scan_port` MCP 工具硬编码为严格的 allowlist。恶意的 LLM 无法再利用 ButterClaw 抓取内部 VPS/AWS 元数据。 ### 📦 v0.6.3.1 的新特性（完整 Docker） **完整 Docker 版** 加强了部署包，实现了无缝的跨平台编排（特别是 Windows/WSL 环境），并打破了几个复杂的容器化死锁。 * **基础设施自动治愈：** 解决了“冷启动悖论”。如果数据库被擦除，服务器会在启动时自动生成并注入自己的安全 API key 和 Watcher 徽章。 * **Air-Gapped 推送通知 (`ntfy`)：** 将官方的 `ntfy` 容器集成到部署 stack 中。ButterClaw 现在可以完全在本地将原生 OS 通知直接推送到您的手机或浏览器，而不会将遥测数据泄露给 Discord 或 Slack 等第三方云服务。 * **Alert Dispatcher 自动启动：** Exoskeleton 会动态读取您的 `.env` topic，并在启动时自动在数据库中构建自己的通知路由规则。 * **保险库初始化死锁修复：** 强制 Master Vault Key 在服务器启动序列中生成，确保 session-cookie 签名者在*第一次*用户登录尝试之前就已准备就绪。 * **Split-Brain 数据库治愈：** 统一了所有模块中针对 `config.py` 的 `try/except` 导入，防止 Docker volume 挂载意外地将 SQLite 写入分散到不同目录。 * **Windows 主机桥接 (`host.docker.internal`)：** 通过将隔离的 Linux 容器干净地桥接回主机原生 Windows Ollama 实例，保护了 GPU 加速的本地 Ollama 推理。 * **可见的 Keyring (`XDG_DATA_HOME`)：** 通过将备用 Keyring 存储直接映射到可见的 `/app/data` 目录中，绕过了 Docker 的 root 权限陷阱。 * **前端路由别名：** 为标准 HTML 路径添加了原生的 Flask `@app.route` 装饰器，允许在没有 Nginx 的情况下进行无缝的开发模式浏览。 ### 📦 v0.6.3 引入的特性 **部署打包** —— Exoskeleton 已经过实战检验。v0.6.3 添加了将 ButterClaw 部署到生产环境所需的一切：集中式配置、Docker 容器化、systemd 服务管理、nginx TLS 终止以及自动化的备份/恢复 —— 所有这些都无需添加任何新的 pip 依赖。 #### ⚙️ 集中式配置 (`config.py`) 所有 5 个模块的所有 runtime 配置的唯一事实来源。无需再修改 5 个文件来更改数据库路径。 跨越 9 个类别的 **26 个可配置字段**： | 类别 | 字段数 | 示例 | |----------|--------|----------| | **Paths** | 3 | `DB_PATH`, `MCP_SCRIPT`, `BASE_DIR` | | **Server** | 3 | `HOST`, `PORT`, `DEBUG` | | **CORS** | 1 | `CORS_ORIGINS` (逗号分隔) | | **Brain/Ollama** | 5 | `OLLAMA_BASE_URL`, `MODEL_NAME`, `CONFIDENCE_THRESHOLD`, `DRY_RUN` | | **MCP Transport** | 3 | `MCP_TRANSPORT`, `MCP_SSE_URL`, `MCP_SSE_TOKEN` | | **Auth** | 4 | `AUTH_RATE_ADMIN`, `SESSION_TTL` | | **Alerts** | 4 | `ALERT_DELIVERY_TIMEOUT`, `ALERT_MAX_RETRIES` | | **OAuth** | 1 | `OAUTH_STATE_TTL` | | **Identity** | 1 | `INSTANCE_ID` | **优先级链：** ``` # 用法 — 所有 5 个模块通用： from config import cfg db_path = cfg.DB_PATH # unified across server, auth, policy, alert, vault port = cfg.PORT # was hardcoded 5000 confidence = cfg.CONFIDENCE_THRESHOLD # was hardcoded 0.6 ``` **关键特性：** * 所有环境变量均带有 `BUTTERCLAW_` 前缀 —— 不会与系统变量发生冲突 * 导入时执行 `_validate()` —— 配置错误时快速失败 * `to_dict(redact_secrets=True)` —— API 安全的配置导出 * 基于标准库构建的 `.env` 解析器 —— 无需 python-dotenv 依赖 * 环境变量永远不会被 `.env` 覆盖（符合 12-factor 规范） #### 🐳 Docker 部署 三容器生产 stack： | 容器 | 角色 | 健康检查 | | --- | --- | --- | | **butterclaw** | 主应用程序（Flask + 所有模块） | `healthcheck.py` → `/api/health` | | **ollama** | 本地 LLM 推理 | `/api/tags` endpoint | | **nginx** | TLS 终止 + 反向代理 + 静态文件 | 上游健康状态 | **关键特性：** * 容器内使用非 root 的 `butterclaw` 用户 * 通过 `nvidia-container-toolkit` 进行 GPU 直通（自动回退至 CPU） * 用于 SQLite 持久化和 Ollama 模型缓存的命名卷 (Named volume) * 具有 10MB 轮转的 JSON 文件日志 * 用于编排器集成的 `HEALTHCHECK` 指令 #### 🖥️ systemd 部署（裸机 VPS） ``` # 安装 service sudo cp systemd/butterclaw.service /etc/systemd/system/ sudo cp .env /etc/butterclaw.env sudo systemctl daemon-reload sudo systemctl enable --now butterclaw # 监控 journalctl -u butterclaw -f ``` **安全加固：** * `ProtectSystem=strict` —— 除工作目录外文件系统只读 * `NoNewPrivileges=true` —— 防止权限提升 * `PrivateTmp=true` —— 隔离的临时目录 * `Restart=on-failure` 并带有 5 秒延迟 #### 💾 备份与恢复 ``` # 创建带有时间戳的 backup (SQLite .backup + .env) ./scripts/backup.sh # 列出可用的 backup ./scripts/restore.sh # 从特定 backup 恢复 ./scripts/restore.sh backups/butterclaw-backup-20260420-1200.tar.gz ``` * SQLite `.backup` 命令（原子操作 —— 切勿在活动数据库上使用 `cp`） * 自动清理旧备份（保留最近 7 次） * 在归档中包含 `.env` 配置 #### 🔒 Nginx TLS 终止 * HTTP → HTTPS 重定向 * TLSv1.2/1.3 和 ECDHE cipher suite * HSTS（1 年）、X-Content-Type-Options、X-Frame-Options * 特定于 SSE 的代理：`proxy_buffering off` + 24 小时超时 * 为仪表盘 HTML 提供静态文件服务 * 300 秒的 Brain 推理读取超时 ## 🔔 Alert Dispatcher (v0.6.2) 一个无法*触达*其操作员的安全监控系统只是一个多了几步操作的日志文件。Alert Dispatcher 将通知推送到外部渠道，以便操作员在事情发生的那一刻就能知晓，即使当时没有人在看仪表盘。 ### 多渠道 Alert 路由 5 种渠道类型，全部基于 Python 标准库构建（零新增 pip 依赖）： | 渠道 | 传输方式 | Payload 格式 | | --- | --- | --- | | **Webhook** | HTTP POST + HMAC-SHA256 签名 | 包含 event_type, severity, context 的 JSON | | **Discord** | Discord webhook API | 带有颜色编码严重性边栏的丰富嵌入 | | **ntfy** | ntfy.sh 或自托管 | 包含 title, body, priority, tags 的推送 | | **SMTP** | smtplib | 具有结构化纯文本正文的电子邮件 | | **Gotify** | 自托管推送 API | Title + message + priority (1-10) | ### 📱 Air-Gapped 推送通知 ButterClaw v0.6.3.1 内置了一个完全私有的、自托管的推送通知服务器（`ntfy`），直接集成到 Docker stack 中。 1. 在您的 `.env` 文件中设置 `BUTTERCLAW_ALERT_NTFY_TOPIC=your-secret-topic`。 2. 在浏览器中打开 `http://localhost:2586`（或您服务器的 IP），或下载免费的 `ntfy` iOS/Android 应用程序。 3. 订阅您的秘密 topic。在检测到威胁的毫秒级时间内，您将收到原生、格式精美的推送通知——绝对不会有哪怕一字节数据离开您的本地网络。 ### 9 种 Alert 事件类型 | 事件 | 触发时机 | 严重性 | | --- | --- | --- | | `verdict_critical` | Brain 或 Policy 返回 CRITICAL | 🔴 Critical | | `verdict_warning` | Brain 返回 WARNING（置信度 >= 50%） | 🟡 Warning | | `gibson_triggered` | 由 ChainExecutor 触发的自动 Gibson | 🔴 Critical | | `gibson_manual` | 通过 `/api/rotate-keys` 触发的手动 Gibson | 🔴 Critical | | `policy_override` | Policy Engine 覆盖了 Brain 的判定 | 🟡 Warning | | `policy_blocked` | Policy Engine 阻止了请求或工具 | 🟡 Warning | | `auth_brute_force` | 60 秒内来自同一 IP 的 5 次以上 auth 失败 | 🔴 Critical | | `mcp_offline` | MCP 进程由存活转为死亡 | 🔴 Critical | | `system_startup` | 服务器成功启动 | 🟢 Info | ## 🛡️ Policy Engine (v0.6.1) 为概率性 Brain 提供确定性的 guardrails。实现了 DRIFT 框架模式（NeurIPS 2025）—— 这是一个动态验证器，它通过声明“*如果 X，则总是 Y*”的规则来约束 Brain 的概率推理 —— 无需额外推理。 ### 3 层 Scope 过滤管道 | Scope | 触发时机 | 它能做什么 | | --- | --- | --- | | **Pre-Brain** | 在调用 LLM 之前 | 直接短路返回 CRITICAL 或 BENIGN，而不消耗推理时间 | | **Post-Brain** | 在 LLM 返回判定之后 | 覆盖、升级、降级判定，或要求更高的置信度 | | **Pre-Tool** | 在链条中的每次 MCP 工具调用之前 | 通过 allowlist/blocklist 阻止特定工具 | **16 个安全的条件运算符** —— 全部使用白名单分派，无 `eval()`： `contains`, `not_contains`, `equals`, `not_equals`, `starts_with`, `ends_with`, `regex_match`, `greater_than`, `less_than`, `greater_equal`, `less_equal`, `in_list`, `not_in_list`, `length_gt`, `length_lt` ## 🔐 API Gateway 与身份验证 (v0.6.0) 每个 endpoint 都受到基于角色的访问控制（RBAC）以及 HMAC-SHA256 API key 和 session token 的保护。 | 级别 | 访问级别 | 用例 | | --- | --- | --- | | **Admin** | 完全访问 —— 保险库、Gibson、密钥管理、配置 | 系统所有者 | | **Operator** | 分析威胁、读取设置、启动 OAuth | 活动操作员 | | **Viewer** | 只读 —— 日志、事件、状态、SSE 流 | 监控仪表盘 | ## 💀 Gibson Kill Switch 核选项。一旦触发，ButterVault 会将所有凭据物理粉碎成加密垃圾。在 v0.6.2+ 版本中，Alert Dispatcher 会在保险库销毁*之前*发送通知 —— 先告警，后焚毁。在 v0.6.3.2+ 版本中，它会在销毁本地数据之前，对外部 API 发出主动的网络级刺杀请求。 ``` Gibson Triggered: 1. dispatch_alert("gibson_triggered") ← alert fires 2. _dispatch_worker → all channels ← notifications sent 3. buttervault.butter_keys() ← vault destroyed & tokens assassinated 4. auth.destroy_all_api_keys() ← auth destroyed 5. Operator receives notification ← notification arrives ``` **Gibson 之后存留的内容：** ``` DESTROYED by Gibson: SURVIVES Gibson: ├── vault table (API keys) ├── policies table ├── oauth_tokens table ├── policy_events table ├── api_keys table ├── alert_channels table ├── session cache ├── alert_rules table └── OS keyring master key ├── alert_history table ├── mcp_events table ├── logs table └── config.py / .env (filesystem) ``` ## 📚 文档 如需深入了解 ButterClaw 的架构、API 参考和安全模型，请查看我们的文档目录： * **[架构与 Exoskeleton](docs/ARCHITECTURE.md)** * **[API 参考（43 个 Endpoint）](docs/API.md)** * **[OWASP Agentic Security Initiative (ASI) 映射](docs/SECURITY.md)** * **[部署与配置指南](docs/DEPLOYMENT.md)** ## 🏗️ 架构 **Exoskeleton —— 分层防御：** ``` ┌─────────────────────────────────────────────────┐ │ Deployment Layer (v0.6.3.x) │ │ Docker, systemd, nginx, config.py, backup │ ├─────────────────────────────────────────────────┤ │ Alert Layer (v0.6.2) │ │ 5 channels, 9 event types, HMAC signing │ ├─────────────────────────────────────────────────┤ │ Policy Layer (v0.6.1) │ │ 3-scope pipeline, 16 operators, DRIFT pattern │ ├─────────────────────────────────────────────────┤ │ Auth Layer (v0.6.0) │ │ HMAC-SHA256 keys, 3-tier RBAC, sessions │ ├─────────────────────────────────────────────────┤ │ The Nervous System (v0.5.x) │ │ Brain, ChainExecutor, Event Ledger, MCP, SSE │ ├─────────────────────────────────────────────────┤ │ Core (v0.1–v0.4) │ │ Watcher, ButterVault, Dashboard, Ollama │ └─────────────────────────────────────────────────┘ ``` **组件映射表：** | 组件 | 文件 | 行数 | 版本 | 角色 | | --- | --- | --- | --- | --- | | Config | `config.py` | ~480 | v0.6.3 | 集中式环境驱动配置 | | Server | `server.py` | ~1,200 | v0.6.3.1 | Flask API、Brain、ChainExecutor | | Auth | `auth.py` | ~890 | v0.6.0 | API gateway、RBAC、session token | | Policy Engine | `policy_engine.py` | ~350 | v0.6.1 | 确定性 guardrails | | Alert Dispatcher | `alert_dispatcher.py` | ~1,566 | v0.6.2 | 推送通知 | | ButterVault | `buttervault.py` | ~400 | v0.6.3.2 | 加密保险库、主动撤销、Gibson | | MCP Client | `butterclaw_mcp.py` | ~300 | v0.6.3.2 | 工具定义与 SSRF 阻断 | | MCP Transport | `mcp_transport.py` | ~250 | v0.5.0 | SSE/stdio 传输 | | OAuth Config | `oauth_config.py` | ~60 | v0.5.2 | OAuth provider 模板 | | Watcher | `watcher.py` | ~150 | v0.1.0 | OS 遥测收集器 | ## 📡 API 参考 ### Auth Endpoint（7 个路由 —— v0.6.0） | 方法 | Endpoint | 角色 | 描述 | | --- | --- | --- | --- | | POST | `/api/auth/login` | public | 用 API key 交换 session token | | POST | `/api/auth/logout` | any | 清除 session cookie | | GET | `/api/auth/whoami` | any | 当前身份 | | GET | `/api/auth/keys` | admin | 列出所有 API key | | POST | `/api/auth/keys` | admin | 创建新的 API key | | DELETE | `/api/auth/keys/` | admin | 撤销 API key | | DELETE | `/api/auth/keys//purge` | admin | 永久删除 key | ### Policy Endpoint（8 个路由 —— v0.6.1） | 方法 | Endpoint | 角色 | 描述 | | --- | --- | --- | --- | | GET | `/api/policies` | viewer | 列出所有 policy | | POST | `/api/policies` | admin | 创建 policy | | GET | `/api/policies/` | viewer | 获取 policy | | PUT | `/api/policies/` | admin | 更新 policy | | DELETE | `/api/policies/` | admin | 删除 policy | | POST | `/api/policies//toggle` | admin | 启用/禁用 | | POST | `/api/policies/dry-run` | operator | 针对 policy 测试 payload | | GET | `/api/policies/events` | viewer | 查询 policy 事件日志 | ### Alert Endpoint（13 个路由 —— v0.6.2） | 方法 | Endpoint | 角色 | 描述 | | --- | --- | --- | --- | | GET | `/api/alerts/channels` | viewer | 列出渠道 | | POST | `/api/alerts/channels` | admin | 创建渠道 | | PUT | `/api/alerts/channels/` | admin | 更新渠道 | | DELETE | `/api/alerts/channels/` | admin | 删除渠道（级联） | | POST | `/api/alerts/channels//toggle` | admin | 启用/禁用 | | POST | `/api/alerts/channels//test` | operator | 发送测试 alert | | GET | `/api/alerts/rules` | viewer | 列出规则 | | POST | `/api/alerts/rules` | admin | 创建规则 | | PUT | `/api/alerts/rules/` | admin | 更新规则 | | DELETE | `/api/alerts/rules/` | admin | 删除规则 | | POST | `/api/alerts/rules//toggle` | admin | 启用/禁用 | | GET | `/api/alerts/history` | viewer | 查询 alert 历史记录 | | GET | `/api/alerts/status` | viewer | Alert 系统摘要 | ### 核心 Endpoint（5 个路由） | 方法 | Endpoint | 角色 | 描述 | | --- | --- | --- | --- | | POST | `/api/analyze` | operator | 分析威胁 payload | | GET | `/api/health` | public | 系统健康状态 + 实例信息（v0.6.3 增强） | | GET | `/api/config` | admin | 已解析配置（脱敏机密）（v0.6.3 新增） | | GET | `/api/stream` | viewer | SSE 事件流 | | GET | `/api/logs` | viewer | 查询日志历史记录 | ### MCP Endpoint（6 个路由 —— v0.5.0+） | 方法 | Endpoint | 角色 | 描述 | | --- | --- | --- | --- | | GET | `/api/mcp/tools` | viewer | 列出可用的 MCP 工具 | | POST | `/api/mcp/restart` | admin | 重启 MCP 进程 | | GET | `/api/mcp/status` | viewer | MCP 进程健康状态 | | GET | `/api/events` | viewer | 查询事件账本 | | GET | `/api/events/count` | viewer | 事件账本计数 | | GET | `/api/settings` | viewer | 服务器设置 | ### Vault 与 OAuth Endpoint（10 个路由 —— v0.5.x） | 方法 | Endpoint | 角色 | 描述 | | --- | --- | --- | --- | | POST | `/api/rotate-keys` | admin | 手动触发 Gibson Kill Switch | | GET | `/api/vault/status` | viewer | 保险柜健康状态 | | GET | `/api/vault/credentials` | operator | 列出已存储的凭据 | | POST | `/api/vault/credentials` | admin | 存储新凭据 | | DELETE | `/api/vault/credentials/` | admin | 删除凭据 | | GET | `/api/oauth/providers` | viewer | 列出 OAuth provider | | POST | `/api/oauth/start/` | operator | 启动 OAuth 流程 | | GET | `/api/oauth/callback` | public | OAuth callback 处理器 | | GET | `/api/oauth/tokens` | operator | 列出 OAuth token | | DELETE | `/api/oauth/tokens/` | admin | 删除 OAuth token | **总计：43 个 API 路由**（7 个 Auth + 8 个 Policy + 13 个 Alert + 5 个核心 + 6 个 MCP + 10 个 Vault，从 49 个减少以考虑共享的 endpoint —— 因为有些 endpoint 跨模块注册） ## 📁 项目结构 ``` butterclaw/ ├── server.py # Flask API + Brain + ChainExecutor (v0.6.3.1) ├── config.py # Centralized configuration (v0.6.3) ├── auth.py # API gateway + RBAC (v0.6.0) ├── policy_engine.py # Deterministic guardrails (v0.6.1) ├── alert_dispatcher.py # Push notifications (v0.6.2) ├── buttervault.py # Encrypted vault + active revokes + Gibson (v0.6.3.2) ├── butterclaw_mcp.py # MCP tool definitions + SSRF blocks (v0.6.3.2) ├── mcp_transport.py # SSE/stdio transport (v0.5.0) ├── oauth_config.py # OAuth provider templates (v0.5.2) ├── watcher.py # OS telemetry collector (v0.1.0) ├── index.html # Main dashboard (v0.6.3) ├── routing.html # Advanced config dashboard (v0.6.3) ├── requirements.txt # pip dependencies (v0.6.3) ├── .env.example # Environment template (v0.6.3) ├── Dockerfile # Container build (v0.6.3) ├── docker-compose.yml # Production orchestration (v0.6.3) ├── docker-compose.dev.yml # Dev overlay (v0.6.3) ├── .dockerignore # Build context exclusions (v0.6.3) ├── nginx/ │ └── butterclaw.conf # Reverse proxy config (v0.6.3) ├── scripts/ │ ├── healthcheck.py # Docker health check (v0.6.3) │ ├── backup.sh # Backup utility (v0.6.3) │ └── restore.sh # Restore utility (v0.6.3) ├── systemd/ │ └── butterclaw.service # systemd unit file (v0.6.3) ├── data/ │ └── butterclaw.db # SQLite database (auto-created) ``` ## 🔒 安全架构 | 层级 | 机制 | 版本 | | --- | --- | --- | | **TLS** | 带 TLSv1.2/1.3、ECDHE cipher、HSTS 的 Nginx 反向代理 | v0.6.3 | | **Container** | 非 root 用户、只读文件系统、ProtectSystem=strict | v0.6.3 | | **Authentication** | HMAC-SHA256 API key、session token、httpOnly cookie | v0.6.0 | | **Authorization** | 3 级 RBAC (admin/operator/viewer) | v0.6.0 | | **Policy** | 确定性的 pre-brain/post-brain/pre-tool guardrails | v0.6.1 | | **Alerting** | 5 个外部渠道、HMAC 签名的 webhook、auth 暴力破解检测 | v0.6.2 | | **Vault** | Fernet 加密、OS keyring、主动网络 token 撤销、Gibson Kill Switch | v0.6.3.2 | | **Analysis** | 本地 LLM 推理 + 置信度评分 + 链式安全轨道 | v0.5.0 | | **Monitoring** | Event Ledger + Policy Events + Alert History —— 3 道审计追踪 | v0.5.0+ | ## 🛡️ OWASP Agentic Security Initiative (ASI) 覆盖范围 | ASI 威胁 | ButterClaw 缓解措施 | | --- | --- | | ASI-01：过度代理 | Brain 置信度门控 + ChainExecutor MAX_STEPS=10 + Policy Engine pre-tool scope (v0.5.0+) | | ASI-02：访问控制不足 | 3 级 RBAC + 每个 key 的速率限制 + HMAC-SHA256 认证 (v0.6.0) | | ASI-03：知识中毒 | 本地优先 LLM —— 无外部训练数据摄取。Watcher 监控 OS 遥测，而非用户内容 (v0.1.0+) | | ASI-04：身份与凭据滥用 | ButterVault + OAuth 生命周期 + 主动 token 撤销 + Gibson (v0.6.3.2) | | ASI-05：级联失败 | ChainExecutor 安全轨道：MAX_STEPS=10, TIMEOUT=60s (v0.5.1) | | ASI-06：间接 Prompt Injection | Policy Engine 对 payload 进行模式匹配 (v0.6.1) | | ASI-07：监控不足 | Event Ledger + Policy Events + Alert History —— 3 道审计追踪 (v0.5.0+) | | ASI-09：日志记录不足 | 3 道审计追踪 + 通过 Alert Dispatcher 的外部通知 (v0.6.2) | | ASI-10：不受控的升级 | Gibson panic 以原子方式销毁所有凭据 + alert 在销毁前触发 (v0.6.2) | ## 📋 版本历史 | 版本 | 代号 | 日期 | 里程碑 | | --- | --- | --- | --- | | **v0.6.4** | The Exoskeleton: Active Tools & Autonomous Deployment | 2026-06-08 | 一键安装脚本 | | **v0.6.3.2** | The Exoskeleton: Active Tools | 2026-05-21 | TLS 路由、SSRF 锁定、主动 token 撤销 | | **v0.6.3.1** | Deployment Packaging (Docker Edition) | 2026-05-07 | Docker bridge、Vault 死锁修复、Windows volume 修复 | | **v0.6.3** | The Exoskeleton: Deployment Packaging | 2026-05-01 | config.py、Docker、systemd、nginx、备份/恢复 | | **v0.6.2** | The Exoskeleton: Alert Dispatcher | 2026-05-01 | 5 个渠道、9 个事件、HMAC 签名、暴力破解检测 | | **v0.6.1** | The Exoskeleton: Policy Engine | 2026-05-01 | 3 层 scope 管道、16 个运算符、DRIFT 模式 | | **v0.6.0** | The Exoskeleton: API Gateway & Auth | 2026-04-20 | HMAC-SHA256、3 级 RBAC、session token | | **v0.5.2** | ButterVault OAuth | 2026-04-16 | OAuth 2.0 流程、token 刷新、Gibson 销毁 OAuth | | **v0.5.1** | Tool Chaining | 2026-04-16 | ChainExecutor、多步执行、安全轨道 | | **v0.5.0** | The Nervous System | 2026-04-14 | Event Ledger、SSE 传输、MCP Manager、内存 | | **v0.4.x** | MCP Transport Refactor | 2026-04-10 | 模块化传输、JSON-RPC、CSP 修复 | | **v0.3.x** | Routing Dashboard | 2026-04-04 | routing.html、高级配置 UI | | **v0.2.0** | ButterVault | 2026-04-01 | 加密凭据、Gibson Kill Switch | | **v0.1.0** | Initial Release | 2026-03-17 | 核心分析、watcher、仪表盘、MCP 工具 | ## 🗺️ 路线图 —— Exoskeleton (v0.6.x) | 支柱 | 版本 | 状态 | 交付物 | | --- | --- | --- | --- | | 1. API Gateway 与 Auth | v0.6.0 | ✅ 已交付 | HMAC-SHA256、RBAC、会话 | | 2. Policy Engine | v0.6.1 | ✅ 已交付 | 3 层 scope 管道、DRIFT 模式 | | 3. Alert Dispatcher | v0.6.2 | ✅ 已交付 | 5 个渠道、HMAC webhook | | 4. 部署打包 | v0.6.3 | ✅ 已交付 | Docker、systemd、config.py | **Exoskeleton 已完成。** 四大支柱均已发布。 ## ⚡ 快速开始（自主部署） 实现价值的时间在 60 秒以内。ButterClaw 的自动治愈架构可以从完全空白的状态开始，构建自己的数据库，生成安全密钥，并连接其 alert 网络。 **1. 一键安装：** ``` curl -sSL [https://raw.githubusercontent.com/butterclaw-tech/butterclaw/main/install.sh](https://raw.githubusercontent.com/butterclaw-tech/butterclaw/main/install.sh) | bash ``` **2. Docker Compose（推荐）：** ButterClaw 的自动治愈架构允许它从完全空白的状态开始，构建其数据库，生成安全密钥，并连接其 alert 网络。假设本地的 ollama 正在使用本地模型运行。建议：执行 `ollama pull Modelfile.example`，您将获得 Gemma 4:e4b 开源模型的 'butterclaw-optimized:latest' 版本。 ``` git clone [https://github.com/butterclaw-tech/butterclaw.git](https://github.com/butterclaw-tech/butterclaw.git) cd butterclaw && git checkout dev # 1. 配置你的环境 cp .env.example .env # 编辑 .env — 设置 BUTTERCLAW_INSTANCE_ID, BUTTERCLAW_ALERT_NTFY_TOPIC 等 # 2. 生成本地 TLS 证书 (用于 Nginx) # 未安装 openssl 的 Windows 用户可以使用此临时容器 # 直接在项目文件夹中生成所需的密钥： mkdir -p nginx/certs docker run --rm -v "${PWD}/nginx/certs:/certs" alpine/openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /certs/butterclaw.key -out /certs/butterclaw.crt -subj "/CN=localhost" # 3. 点燃 Exoskeleton (构建并启动整个 stack) docker compose up -d --build # 4. 获取你的 Bootstrap Admin API Key！ (查找 🔐 [AUTH] 行) docker compose logs -f butterclaw ``` **3. 启动 Matrix TUI：** 一旦容器运行起来，连接到实时终端仪表盘以实时观看 SOC： ``` ./dash ``` 一旦您从终端获取了您的 API key，就可以通过 **https://localhost** 访问安全路由的仪表盘，并在 **http://localhost:2586** 订阅您的 ntfy topic！ ## 🎯 Live Fire 测试（Zero-Day Arsenal） ButterClaw 内置了安全的独立脚本，用于验证 Policy Engine 和 Zero-Day Arsenal 的完整性，而无需实时的 LLM 或外部 payload。 一旦您的部署运行起来，您就可以直接针对 Arsenal 模拟定向的 prompt injection 攻击： ``` # 1. 将测试签名注入 live database python scripts/add_rule.py # 2. 触发模拟的 payload 并观察 Arsenal 拦截它 python scripts/test_attack.py ``` ### systemd（裸机 VPS） ``` git clone [https://github.com/butterclaw-tech/butterclaw.git](https://github.com/butterclaw-tech/butterclaw.git) cd butterclaw && git checkout dev # 安装依赖 pip install -r requirements.txt # 安装 Ollama curl -fsSL [https://ollama.com/install.sh](https://ollama.com/install.sh) | sh ollama pull gemma4:e4b # 配置 cp .env.example /etc/butterclaw.env # 编辑 /etc/butterclaw.env # 安装 service sudo cp systemd/butterclaw.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now butterclaw # 验证 journalctl -u butterclaw -f curl http://localhost/api/health ``` ### 裸机（开发） ``` git clone [https://github.com/butterclaw-tech/butterclaw.git](https://github.com/butterclaw-tech/butterclaw.git) cd butterclaw && git checkout dev pip install -r requirements.txt ollama pull gemma4:e4b # ollama pull Modelfile.example <- 获取 'butterclaw-optimized:latest' 模型 cp .env.example .env python server.py ``` 首次运行时，bootstrap CLI 会将您的 admin API key 打印到终端上。请妥善保存 —— 它只会显示一次。 ## 📊 诊断测试 所有模块均包含独立的诊断套件： | 模块 | 命令 | 测试 | | --- | --- | --- | | `config.py` | `python config.py` | 21/21 | | `alert_dispatcher.py` | `python alert_dispatcher.py` | 14/14 | | `policy_engine.py` | `python policy_engine.py` | 16/16 | | `auth.py` | `python auth.py` | 10/10 | ## 📄 许可证 Apache 2.0 License。有关详细信息，请参见 [LICENSE](LICENSE)。

🦞 ButterClaw v0.6.5 —— The Exoskeleton (The Agentic SOC)
为概率性推理提供确定性 guardrails。先评估，后执行。
The Sentinel 永不沉默。我们注视着整个房间。
使用未经认证的遥测构建。是的，未经认证。🦞
butterclaw.tech · GitHub

标签：AI安全, AI风险缓解, Chat Copilot, DNS 反向解析, StruQ, 凭据管理, 提示注入防护, 智能体监控, 本地化推理, 自动化防御, 请求拦截, 逆向工具