Alibaba-AAIG/ClawArmor

# ClawArmor [](LICENSE) [](package.json) [](https://openclaw.dev) [](https://nodejs.org) ## 亮点 / 为何选择 ClawArmor - **解决误报问题** — 不同场景需要不同的防御策略。静态规则会导致过多的误报/漏报，破坏用户体验。ClawArmor 从每个业务上下文中学习正常/攻击模式，并自动生成针对性的规则。 - **零接触持续安全提升** — 自动从失败中学习，识别防御漏洞，并在无需人工干预的情况下生成新的检测规则。系统会随着时间推移变得更智能。 - **多层防护** — 三个核心检测点（输入、行为、输出），为 AI Agent 生命周期提供全面覆盖。 - **工具链攻击检测** — 识别跨多个工具调用的多阶段攻击（例如：侦察 → 凭证读取 → 渗出）。 - **影子 → 活跃规则生命周期** — 新规则以影子模式（仅监控）启动，经过验证后转为活跃，若无效则被弃用。 - **实时仪表板** — 基于 Web 的监控仪表板，地址为 `http://127.0.0.1:18790`，提供实时威胁可见性。 ## 演示 --- ## 架构概述 ClawArmor 实现了 **纵深防御 + 自适应演进** 架构，在 **三个关键钩点** 拦截 AI Agent 交互，并通过其演进引擎持续更新防御规则。  系统由两层组成。上层 **三层防御流水线** 处理用户输入，通过： - **用户威胁防护**（钩点：`message_received`） — 只读检测提示注入和敏感数据 - **行为防护**（钩点：`before_tool_call`） — 风险告警，可选阻断危险命令 - **外部内容防护**（钩点：`after_tool_call`） — 只读扫描间接注入 下层 **自我防御核心** 通过影子、活跃和废弃阶段管理规则生命周期，采用自适应阈值控制与反馈学习，持续优化防御策略。 ### 规则生命周期 新规则以 **影子模式**（仅监控）启动，在命中 ≥ 3 且误报率 ≤ 30% 后晋升为 **活跃**，若有效性 < 0.2 则被废弃。 ## 快速开始 ### 先决条件 - **Node.js** >= 18.0.0 - **OpenClaw** >= v2026.4.1（用于插件系统兼容性） - **LLM API 密钥**（可选但推荐用于自我演进） ### 安装 ``` # 克隆仓库 git clone https://github.com/clawarmor/clawarmor-evolve.git cd clawarmor-evolve/ClawArmor-OpenClaw-Plugin # 安装依赖 npm install # 构建并安装插件 npm run install-plugin ``` ### 配置 创建配置文件： ``` mkdir -p ~/.openclaw/clawarmor cat > ~/.openclaw/clawarmor/config.json << 'EOF' { "enabled": true, "blockOnCritical": true, "blockOnHighRisk": false, "maskSensitiveData": true, "evolveEnabled": true, "evolveLlmApiBase": "https://api.openai.com/v1", "evolveLlmApiKey": "sk-your-api-key-here", "evolveLlmModel": "gpt-4", "evolveUpdateInterval": 5, "evolveTargetFpRate": 0.05, "evolveTargetFnRate": 0.02 } EOF chmod 600 ~/.openclaw/clawarmor/config.json ``` ### 启动 ``` # 启动 OpenClw 网关（ClawArmor 自动加载） openclaw gateway start # 或启动监控仪表板 npm run dashboard # 仪表板地址为 http://127.0.0.1:18790 ``` ### 验证安装 ``` # 检查 ClawArmor 日志 tail -f ~/.openclaw/logs/gateway.log | grep "\[ClawArmor\]" # 检查警告 tail -f ~/.openclaw/logs/gateway.log | grep "\[ClawArmor\]" | grep -E "warn|WARN" # 监控演化事件 tail -f ~/.openclaw/logs/gateway.log | grep -E "EVOLVE|evolution" ``` ## 配置参考 配置优先级（从高到低）：**环境变量 > 配置文件 > 默认值** | 配置项 | 环境变量 | 默认值 | 描述 | |-------------|---------------------|---------|-------------| | `enabled` | `CLAWARMOR_ENABLED` | `true` | 启用/禁用 ClawArmor 保护 | | `blockOnCritical` | `CLAWARMOR_BLOCK_CRITICAL` | `false` | 在 CRITICAL 风险检测时阻断请求 | | `blockOnHighRisk` | `CLAWARMOR_BLOCK_HIGH` | `false` | 在 HIGH 风险检测时阻断请求 | | `logAllChecks` | `CLAWARMOR_LOG_ALL` | `false` | 记录所有安全检查用于调试 | | `maxInputLength` | `CLAWARMOR_MAX_LENGTH` | `10000` | 最大处理输入长度 | | `maskSensitiveData` | `CLAWARMOR_MASK_DATA` | `true` | 在日志中屏蔽敏感数据（API 密钥、密码） | | `evolveEnabled` | `CLAWARMOR_EVOLVE_ENABLED` | `true` | 启用自演进防御引擎 | | `evolveDbPath` | `CLAWARMOR_EVOLVE_DB_PATH` | `~/.openclaw/clawarmor/events.db` | 事件数据库路径 | | `evolveRulesPath` | `CLAWARMOR_EVOLVE_RULES_PATH` | `~/.openclaw/clawarmor/rules.json` | 动态规则存储路径 | | `evolveUpdateInterval` | `CLAWARMOR_EVOLVE_INTERVAL` | `5` | 触发演进周期的采集事件数 | | `evolveLlmApiBase` | `CLAWARMOR_EVOLVE_LLM_API_BASE` | `https://dashscope.aliyuncs.com/api/v1` | LLM API 基础 URL | | `evolveLlmApiKey` | `CLAWARMOR_EVOLVE_LLM_API_KEY` | *(空)* | LL API 密钥用于规则生成 | | `evolveLlmModel` | `CLAWARMOR_EVOLVE_LLM_MODEL` | `qwen3-coder-plus` | 用于规则生成的 LLM 模型 | | `evolveTargetFpRate` | `CLAWARMOR_EVOLVE_TARGET_FP` | `0.05` | 目标误报率（0-1） | | `evolveTargetFnRate` | `CLAWARMOR_EVOLVE_TARGET_FN` | `0.02` | 目标漏报率（0-1） | ### 环境变量示例 ``` # 基本设置 export CLAWARMOR_ENABLED=true export CLAWARMOR_BLOCK_CRITICAL=true export CLAWARMOR_MASK_DATA=true # 演化 LLM 配置（OpenAI 示例） export CLAWARMOR_EVOLVE_LLM_API_BASE=https://api.openai.com/v1 export CLAWARMOR_EVOLVE_LLM_API_KEY=sk-xxxxxxxxxxxx export CLAWARMOR_EVOLVE_LLM_MODEL=gpt-4 export CLAWARMOR_EVOLVE_INTERVAL=5 ``` ## 功能特性 ### 多层检测 ClawArmor 实现了 **三阶段纵深防御** 模型，在三个关键点上保护 AI Agent 交互： #### 用户威胁防护 — `message_received` 第一道防线。在用户消息到达 Agent 之前进行检查。 - **提示注入检测** — 直接注入、角色扮演绕过、多语言攻击 - **敏感数据屏蔽** — 个人信息、API 密钥、凭证 - **演进动态规则匹配** — 影子 + 活跃规则 - **事件上报** — 将检测事件上报至演进引擎 #### 行为防护 — `before_tool_call` 防止危险的工具执行。 - **危险命令检测** — `rm -rf`、`curl` 渗出等 - **意图-动作对齐检查** — 工具调用是否匹配用户意图？ - **工具链攻击检测** — 多步骤攻击模式（如凭证窃取链） - **注入检测** — 工具参数中的恶意模式 - **演进动态规则匹配** — 影子 + 活跃规则 - **事件上报** — 将检测事件上报至演进引擎 #### 外部内容防护 — `after_tool_call` 检查来自 LLM 和工具执行的所有响应。 - **间接注入检测** — 隐藏在网页、文档中的恶意指令 - **外部内容威胁标记** — 区分工具输出与助手消息 - **敏感数据泄漏检测** — 扫描输出中暴露的凭证 - **演进动态规则匹配** — 影子 + 活跃规则 - **事件上报** — 将检测事件上报至演进引擎 **行为防护层** 行为防护层采用 **分级告警机制**，在安全与用户体验之间取得平衡。工具调用由三个并行检测模块评估（危险命令检测、意图偏差分析、工具链模式匹配），得分映射为四个风险等级（CRITICAL、HIGH、MEDIUM、LOW）。 **工具链攻击检测** 单个工具调用可能看似无害，但组合起来会形成完整的攻击链。ClawArmor 维护一个工具调用历史记录（环形缓冲区，容量 50），以检测跨多个调用的多阶段攻击（例如：侦察 → 凭证读取 → 数据渗出）。 ### 自演进防御（防御演进引擎） ClawArmor 的核心创新在于其 **自我演进** 能力——持续从观察到的攻击中学习，并自动优化防御策略。 **规则生命周期：影子 → 活跃 → 废弃** 1. **影子模式** — 新的 LLM 生成规则在此阶段。仅监控并记录命中，不触发告警。 2. **晋升标准** — 命中 ≥ 3 次 且 误报率 ≤ 30% 3. **活跃模式** — 规则参与风险评分并可触发告警/阻断 4. **废弃** — 5 次以上命中但有效性 < 0.2 的规则将被退役 **LLM 驱动的规则生成** 当攻击绕过检测（漏报）时，系统分析漏报样本并生成新的检测规则。流水线包含多级回退策略（AI 分析 → 关键词提取 → 启发式模板），确保系统不会“卡住”。所有生成的规则均进入影子模式进行验证。 **演进飞轮**  每 N 个检测事件（可配置），系统自动执行一次“演进”周期，包含四个顺序步骤：晋升已验证的影子规则为活跃 → 分析漏报以学习新模式 → 通过 AI 分析生成新规则 → 剪除低于有效性阈值的规则。 ClawArmor 支持任何 OpenAI 兼容的 API 用于规则生成（OpenAI、DashScope、Azure OpenAI、本地 vLLM）。当 LLM 不可用时，系统会优雅降级为启发式规则生成。 ### 实时仪表板 启动监控仪表板： ``` npm run dashboard ``` 特性： - 实时威胁检测流 - 规则有效性指标 - 演进周期状态 ### OpenClaw v2026.4.1+ 兼容 使用 `definePluginEntry` 进行现代插件注册，兼容 v2026.3.13。 ## 防御有效性 ### 检测能力矩阵 | 攻击类型 | 检测方法 | 钩点 | 状态 | |-------------|-----------------|------------|--------| | 直接提示注入 | 正则模式 + 语义相似度 | `message_received` | ✅ 活跃 | | 逃逸/角色覆盖 | 多语言模式匹配 | `message_received` | ✅ 活跃 | | 间接注入 | 外部内容扫描 | `after_tool_call` | ✅ 活跃 | | 凭证渗出链 | 工具序列匹配 | `before_tool_call` | ✅ 活跃 | | 侦察 → 权限提升 → 执行 | 多阶段模式检测 | `before_tool_call` | ✅ 活跃 | | 危险 Shell 命令 | 命令解析 + 风险评分 | `before_tool_call` | ✅ 活跃 | | 意图-动作不一致 | 用户意图 vs 工具调用分析 | `before_tool_call` | ✅ 活跃 | | 输入中的敏感数据 | 12 类 PII/凭证检测 | `message_received` | ✅ 活跃 | | 输出中的敏感数据 | 输出内容扫描 | `after_tool_call` | ✅ 活跃 | ## API / 插件钩子 ClawArmor 注册了三个 OpenClaw 钩子： | 钩子 | 触发时机 | 是否可阻断 | 用途 | |------|---------|-----------|---------| | `message_received` | 用户消息到达 | 否 | 输入验证、注入检测、数据屏蔽、轨迹收集 | | `before_tool_call` | 工具执行前 | **是** | 危险命令、意图对齐、工具链分析、注入检测 | | `after_tool_call` | LLM/工具响应后 | 否 | 间接注入、外部内容威胁、输出扫描、轨迹更新 | ## 开发 ### 构建 ``` npm run build # Compile TypeScript npm run watch # Development mode with auto-rebuild ``` ### 测试 ``` npm test # Run Jest test suite ``` ### 项目结构 ``` ClawArmor-OpenClaw-Plugin/ ├── src/ │ ├── index.ts # Plugin entry, hook registration │ ├── types.ts # TypeScript definitions │ ├── detectors/ │ │ ├── injection.ts # Prompt injection detection │ │ ├── command.ts # Dangerous command detection │ │ ├── intent.ts # Intent-action alignment │ │ └── toolchain.ts # Multi-stage attack detection │ ├── utils/ │ │ ├── config.ts # Configuration management │ │ ├── logger.ts # Logging utilities │ │ └── masker.ts # Sensitive data masking │ ├── evolve/ # Self-evolution engine │ │ ├── event-store.ts # Event persistence │ │ ├── rule-bank.ts # Dynamic rule repository │ │ ├── adaptive-threshold.ts # Auto-tuning sensitivity │ │ ├── reward-signal.ts # Effectiveness scoring │ │ ├── rule-updater.ts # LLM rule generation │ │ └── evolve-manager.ts # Evolution orchestrator │ └── cli/ │ └── dashboard.ts # Monitoring dashboard ├── dist/ # Compiled output ├── openclaw.plugin.json # Plugin metadata └── package.json ``` ### NPM 脚本 | 命令 | 描述 | |---------|-------------| | `npm run build` | 编译 TypeScript | | `npm run watch` | 开发模式（自动重建） | | `npm run install-plugin` | 首次安装：构建 + 复制到扩展 | | `npm run update-plugin` | 更新：构建 + 覆盖 dist | | `npm run deploy` | 快速部署：更新 + 重启网关 | | `npm run dashboard` | 启动监控仪表板 | | `npm test` | 运行测试套件 | ### 开发指南 - 遵循 TypeScript 严格模式 - 为新检测规则添加测试 - 更新 API 变更的文档 - 确保向后兼容性 ### 报告问题 请包含： - OpenClaw 版本 - Node.js 版本 - ClawArmor 配置（脱敏 API 密钥） - 重现步骤 - 预期行为与实际行为 ## 许可证 本项目根据 **Apache License 2.0** 许可 —— 详见 [LICENSE](./LICENSE) 文件。 ## 感谢 - **[OpenClaw](https://openclaw.dev)** — 使此插件成为可能的 AI Agent 框架 - **提示注入社区** — 攻击模式研究与数据集

标签：AI安全, API密钥检测, C2, Chat Copilot, CMS安全, GNU通用公共许可证, JavaScript, JSONLines, MITM代理, Node.js, SEO: AI Agent 防护, SEO: ClawArmor, SEO: 多阶段攻击, SEO: 提示注入, 仪表盘, 多阶段攻击防御, 异常检测, 影子规则, 提示注入防护, 数据泄露防护, 服务端安全, 网络探测, 自动化攻击, 自适应安全, 规则自动生成, 输入验证, 输出过滤, 零信任, 零日漏洞检测