openclaw-security-guardrails

OpenClaw 运行时安全防护 — 实时检测密钥泄露、Prompt 注入、数据外泄，并通过纵深防御强化 Agent 安全

English | 中文

为什么需要这个？

AI Gateway 面临一系列独特的安全攻击向量，记录在 OWASP LLM Top 10 2025 和 MITRE ATLAS 中：

| 威胁 | 安全框架引用 | 本包对应 Hook | |------|------------|-------------| | Prompt 注入 | OWASP LLM01, MITRE AML.T0051 | prompt-injection-detector | | 敏感数据泄露 | OWASP LLM02 | secrets-scanner, secret-redactor | | Markdown 数据外泄 | CVE-2025-32711, CVE-2025-53773 | exfiltration-detector | | 不安全的 Gateway 配置 | OWASP LLM08 | startup-checker | | Agent 安全规则 | 纵深防御 | security-bootstrap | | 合规与审计 | — | audit-logger |

安装

openclaw plugins install openclaw-security-guardrails

或本地克隆安装：

git clone https://github.com/shanggqm/openclaw-security-guardrails
openclaw plugins install ./openclaw-security-guardrails

架构

┌─────────────────────────────────────────────────────┐
│                     纵深防御架构                       │
├──────────┬──────────┬──────────┬──────────┬─────────┤
│ 第 0 层   │ 第 1 层   │ 第 1 层   │ 第 1 层   │ 第 2 层  │
│ Bootstrap│ 输入扫描  │ 输出扫描  │ 配置审计  │ 输出脱敏 │
│ 注入      │          │          │          │         │
├──────────┼──────────┼──────────┼──────────┼─────────┤
│ security │ prompt-  │ exfiltr- │ startup  │ secret  │
│ bootstrap│ injection│ ation-   │ checker  │ redactor│
│          │ detector │ detector │          │         │
│          │ secrets  │          │          │         │
│          │ scanner  │          │          │         │
├──────────┼──────────┼──────────┼──────────┼─────────┤
│ agent:   │ message: │ message: │ gateway: │ message:│
│ bootstrap│ received │ sent     │ startup  │ sent    │
└──────────┴──────────┴──────────┴──────────┴─────────┘
                   audit-logger (全事件)

Hooks 一览

🔒 security-bootstrap（安全引导注入）— v0.2 新增

通过 agent:bootstrap 事件将 SECURITY.md 安全规则注入 Agent 上下文。

事件: agent:bootstrap

注入规则包括：禁止执行破坏性命令、禁止暴露凭证、报告注入攻击（[SECURITY_FLAG] 标记）、禁止数据外泄、敏感操作前确认。

注意：这是软防御（纵深防御层）。LLM 在对抗性压力下可能忽略注入的规则。

🔐 secret-redactor（密钥脱敏告警）— v0.2 新增

扫描出站 AI 消息中的密钥泄露和 [SECURITY_FLAG] 标记。

事件: message:sent

• 检测 12+ 种密钥类型
• 监控 security-bootstrap 注入的 [SECURITY_FLAG] 标记
• 推送分类告警
• 记录到审计日志

🔑 secrets-scanner（密钥扫描器）

扫描所有收发消息中的泄露凭证，使用 21+ 正则规则。

事件: message:received, message:sent

🛡️ prompt-injection-detector（注入检测器）

防御 Prompt 注入、越狱尝试和 Unicode 隐蔽攻击。

事件: message:received, message:preprocessed

🚫 exfiltration-detector（外泄检测器）

v0.2 改进：智能 data URI 分析——合法小图片不再误报。

事件: message:sent

📋 audit-logger（审计日志）

事件: message:received, message:sent, command:*, gateway:startup, agent:bootstrap

日志位置: ~/.openclaw/security/audit.jsonl（可通过 OPENCLAW_SECURITY_LOG_DIR 自定义）

🏥 startup-checker（启动检查器）

v0.2 改进：使用正确的深层配置路径，检查项从 5 个扩展到 7 个。

事件: gateway:startup

竞品对比

| 项目 | 类型 | 硬拦截 | 输出扫描 | AI 分析 | 纯本地 | |------|------|--------|---------|---------|--------| | 本项目 (v0.2) | Hook Pack | ❌ | ✅ | ✅ (bootstrap) | ✅ | | Knostic openclaw-shield | Plugin | ⚠️ | ✅ | ❌ | ✅ | | ClawReins | Plugin | ✅ | ❌ | ❌ | ✅ | | OpenGuardrails | Skill + Cloud | 部分 | ✅ | ✅ | ❌ |

性能

• 所有检测：< 20ms
• Bootstrap 注入：< 2ms
• 零 npm 依赖 — 仅使用 Node.js 内置 API
• 审计写入异步，不阻塞消息流

开发

npm install
npm test  # 90 个测试用例
npm run build

许可证

MIT © 2026 shanggqm