VickyTarun89/clawguard
GitHub: VickyTarun89/clawguard
ClawGuard 是一个面向个人 AI agent 的默认拒绝操作代理防火墙，通过策略引擎评估每次工具调用并支持手机端即时审批和防篡改审计日志。
Stars: 1 | Forks: 0
# 🛡️ ClawGuard
**个人 AI agent 的防火墙。** 这是一个默认拒绝的操作代理，驻留在你的 agent（OpenClaw, Hermes, …）和你的机器之间——你可以通过手机使用 Telegram 或 WhatsApp 点击批准任何高风险操作，并保留一份关于 agent 所有操作的防篡改审计日志。
## 工作原理
1. agent 内部的一个轻量级插件将每次工具调用转发到 `127.0.0.1` 上的 ClawGuard 守护进程。
2. 策略引擎对其进行评估：`hard_deny` → 立即阻止，`allow` → 放行，其他所有情况 → 在 Telegram、WhatsApp 或控制台上**询问人类**，并在超时后自动拒绝。
3. 每个请求和决策都会记录在只能追加的、基于 SHA-256 哈希链的审计日志中——修改任何一行都会导致验证失败。
每个操作都会确切地获得以下三种裁定之一：
## 安全模型（反 OpenClaw）
- **默认拒绝。** 未匹配的操作只能 `ask` 或 `deny`——配置格式无法表达“默认允许”。
- **失败即关闭。** 守护进程无法访问？工具调用被阻止。超时？被拒绝。没有任何决策路径会以静默批准结束。
- **无入站暴露。** 守护进程仅绑定到本地回环地址。Telegram 采用出站长轮询；WhatsApp 回复通过出站轮询中继到达。你的机器不开放任何公共端口。
- **强制身份验证。** 每次 API 调用都需要 bearer token；没有“禁用身份验证”的标志。
- **批准者白名单。** 只有配置的 Telegram 用户 ID / 电话号码可以做出决定，并且 `hard_deny` 操作不能被任何人批准——包括凌晨 2 点时的你。
- **自我保护。** 示例策略硬性拒绝了 agent 触碰 `policy.yaml` 或 ClawGuard 自身。
- **密钥不显示在屏幕上。** 配置位于 gitignore 的 `.env` 文件中，守护进程在启动输出中会遮蔽其 API token——这样共享日志和屏幕录制就是安全的。
有关完整的威胁模型，包括 ClawGuard **无法**防范的明确列表，请参阅 [SECURITY.md](SECURITY.md)。
## 快速开始
```
npm install
copy policy.example.yaml policy.yaml # then edit paths/commands for your machine
copy .env.example .env # then put your secrets in .env (gitignored)
npm test
npm start # daemon on 127.0.0.1:4747, console approvals on
```
密钥保存在 `.env` 中（由 Node 原生读取，从不提交），因此你永远不需要在可能正在进行屏幕录制的终端中
输入 token。默认情况下，守护进程也会在启动输出中
遮蔽其 API token。
然后连接你的 agent——这两个插件都与同一个守护进程通信，并且由一个策略管理所有内容：
- **OpenClaw：** `openclaw plugins install ./integrations/openclaw`，然后重启网关。有关验证步骤和注意事项，请参阅 [其 README](integrations/openclaw/README.md)。
- **Hermes Agent：** 将 [`integrations/hermes/`](integrations/hermes/) 复制到 `~/.hermes/plugins/clawguard/`——它会挂钩 `pre_tool_call` 以控制执行，*并且*报告已执行的调用，因此审计日志会暴露任何绕过检查的工具调用（**绕过检测**）。请参阅其 [README](integrations/hermes/README.md)。
- **任何其他工具：** 守护进程与 agent 无关——`POST /v1/check {agent, tool, params}`，仅根据 `"allow"` 执行操作。适配器大约需要 50 行代码。
### 手机批准——选择你的渠道
**Telegram（推荐——约 3 分钟，零基础设施）：**
1. 向 [@BotFather](https://t.me/BotFather) 发送消息 → `/newbot` → 复制 token。
2. 获取你的数字用户 ID（向 [@userinfobot](https://t.me/userinfobot) 发送消息）。
3. 将两者放入你的 `.env` 中，分别作为 `TG_BOT_TOKEN` 和 `TG_APPROVERS`，重启守护进程，然后打开你的机器人并发送一次 `/start`（Telegram 机器人无法主动向你发送消息）。
批准请求到达时带有内联的 **✅ 批准 / ⛔ 拒绝 按钮**——点击即可决定。守护进程仅通过出站长轮询 Telegram：没有 webhook，没有中继，没有额外的账户。
**WhatsApp（旗舰级——约 25 分钟，自托管）：** 在 [`relay/`](relay/) 中部署免费的中继 Worker（完整演练在其 [README](relay/README.md) 中），然后设置 `WA_ACCESS_TOKEN`、`WA_PHONE_NUMBER_ID`、`WA_APPROVERS`（逗号分隔的 E.164 格式）、`WA_RELAY_URL` 和 `WA_RELAY_TOKEN`。
**控制台（零设置）：** 默认开启——在终端中使用 `a
` / `d ` 进行批准。
在没有 agent 的情况下尝试一下：
```
curl -s -X POST http://127.0.0.1:4747/v1/check \
-H "Authorization: Bearer $CLAWGUARD_TOKEN" -H "Content-Type: application/json" \
-d '{"agent":"demo","tool":"exec_shell","params":{"command":"curl https://evil.example"}}'
# → 根据 your policy 进行阻止、询问或允许
```
## 状态
`v0.1` —— 可用的核心功能（策略引擎、批准队列、审计链、HTTP API、控制台 + Telegram + WhatsApp 渠道、OpenClaw + Hermes 插件）。
**已在原生 Windows 上针对 OpenClaw 2026.6.11 完成端到端验证。** 所有三种裁定路径都已针对实时 agent 进行了测试：
| Agent 操作 | ClawGuard | 结果 |
|---|---|---|
| 读取 `secrets.env` | `hard_deny`，立即拒绝 | agent 回复 *“对该文件的访问已被 ClawGuard 拒绝”*——不向任何人提供批准 |
| 写入 `test.txt` | `ask` → Telegram | 手机显示 *“openclaw 想要写入 …”*；点击 ⛔ 会记录 `decidedBy=human`，该文件永远不会被创建 |
| 写入 `test.txt`，被忽略 | `ask` → 超时 | 120 秒后自动拒绝——agent 报告 *“等待人类批准超时”* |
每个请求和决策都已记录在哈希链日志中，该日志目前依然验证通过。
尚未经过独立审计；请将其视为第二道锁，而不是保险库。有关威胁模型，请参阅 [SECURITY.md](SECURITY.md)，有关设计和路线图（配对码批准者身份验证、适用于任何 agent 的通用 LLM 代理模式、OS 沙箱执行层），请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 受保护的内容（不仅仅是 `.env` 文件）
ClawGuard 保护**你的策略所指定的任何内容**——密钥只是最显眼的例子。其思维模型包含三个区域：
1. **`hard_deny` —— 绝不，无论谁请求。** 示例策略默认将关键材料（`.env`、SSH 密钥、云凭证）和破坏性命令放在此处。添加你自己的不可触碰内容——财务文件、税务文件夹、密码管理器保管库：
- note: 财务和身份证明文件——任何 agent 都永远不能访问
tool: "*"
path: ["C:/Users/you/Documents/Banking/**", "**/tax-returns/**"]
2. **`allow` —— 你明确的安全区域。** 项目文件夹、安全的只读命令。**保持这些 glob 范围尽可能窄**——你允许的每个路径都是 agent 可以无需询问直接触碰的路径。不要允许 `C:/Users/you/**`；应该允许 `D:/projects/**`。
3. **其他所有内容 —— 询问人类。** 这是人们容易忽略的部分：你的银行对账单、隐藏文件、照片和随机的个人文件夹**默认受保护**，因为任何不匹配规则的操作都会进入 `ask`（如果你设置得更严格，则会进入 `deny`）。agent 无法在没有先让你的手机震动的情况下打开 `Documents\loan-statement.pdf`——不是因为你为此写了规则，而是因为你*没有*写允许这么做的规则。
两个诚实的限制：ClawGuard 匹配的是**工具调用的参数**（路径、命令、字符串）——它不读取文件内容，因此位于你已允许文件夹*内*的敏感文件将通过该允许规则。此外，它控制的是通过 agent 工具层路由的操作——OS 级别的沙箱层（路线图 v0.4）将负责强制执行边界，即使在 agent 被完全攻破的情况下也是如此。
## 攻击是如何被阻止的
一封提示词注入的电子邮件或恶意技能告诉你的 agent 窃取你的密钥并将其发送出去。agent 服从了——但该操作仍然必须通过关口，而关键材料对每个工具都是硬性拒绝的：
## 贡献
欢迎提交 Issue 和 PR——尤其是针对其他 agent 的适配器，以及
值得在示例中提供的策略规则。对于安全漏洞，请**不要**开启 Issue；请参阅
[SECURITY.md](SECURITY.md)。
[MIT 许可](LICENSE)。公开构建——欢迎持续关注。标签：AI代理, MITM代理, Python脚本, Streamlit, 人工智能, 用户模式Hook绕过, 策略引擎, 网络安全挑战, 自动化攻击, 访问控制, 防火墙