ClawSec：面向AI代理的安全技能套件

---

🦞 什么是 ClawSec？

ClawSec 是一款 面向 AI 代理平台的完整安全技能套件。它提供统一的安全监控、完整性验证和威胁情报功能，可保护您的代理的认知架构免受提示注入、模型漂移及恶意指令的侵害。

支持的平台

• OpenClaw（MoltBot、Clawdbot 及其克隆）——全套工具，包含技能安装程序、文件完整性保护和安全审计
• NanoClaw——容器化的 WhatsApp 机器人安全解决方案，配备 MCP 工具，用于预警监控、签名验证和文件完整性检查

核心功能

• 📦 套件安装程序——一键安装所有安全技能，并进行完整性校验
• 🛡️ 文件完整性保护——检测关键代理文件（SOUL.md、IDENTITY.md 等）的漂移并自动恢复
• 📡 实时安全公告——自动轮询 NVD CVE 数据库及社区威胁情报
• 🔍 安全审计——自检脚本，用于检测提示注入标记和漏洞
• 🔐 校验码验证——所有技能工件均附带 SHA256 校验码
• 健康检查——对所有已安装技能进行自动化更新与完整性验证

---

🎬 产品演示

以下动画预览为 GIF 格式（无音频）。点击任意预览即可打开带有音频的完整 MP4 文件。

安装演示（clawsec-suite）

直接链接：install-demo.mp4

漂移检测演示（soul-guardian）

直接链接：soul-guardian-demo.mp4

---

🚀 快速入门

针对 AI 代理

# 安装 ClawSec 安全套件
npx clawhub@latest install clawsec-suite

安装完成后，该套件可以：

1. 从已发布的技能目录中发现可安装的防护措施
2. 使用签名校验码验证发布版本的完整性
3. 设置预警监控和基于钩子的防护流程
4. 添加可选的定期检查任务

手动/源代码优先选项：

请阅读 https://github.com/prompt-security/clawsec/releases/latest/download/SKILL.md，并按照安装说明操作。

针对人类用户

将此指令复制到您的 AI 代理中：

使用 npx clawhub@latest install clawsec-suite 安装 ClawSec，然后按照生成的说明完成设置步骤。

Shell 和 OS 注意事项

ClawSec 脚本分为两类：

• 跨平台的 Node.js/Python 工具（npm run build、钩子/初始化 .mjs 文件、utils/*.py）
• POSIX shell 工作流（*.sh 文件，大多数手动安装片段）

对于 Linux/macOS（bash/zsh）：

• 使用未加引号或双引号的主目录变量：export INSTALL_ROOT="$HOME/.openclaw/skills"
• 请勿使用单引号包裹可展开的变量（例如，避免使用 '$HOME/.openclaw/skills'）

对于 Windows（PowerShell）：

• 建议显式构建路径：
  • $env:INSTALL_ROOT = Join-Path $HOME ".openclaw\\skills"
  • node "$env:INSTALL_ROOT\\clawsec-suite\\scripts\\setup_advisory_hook.mjs"
• POSIX .sh 脚本需要 WSL 或 Git Bash。

故障排除：如果出现类似 ~/.openclaw/workspace/$HOME/... 的目录结构，说明主目录变量被原样传递了。请使用绝对路径或不加引号的主目录表达式重新运行。

---

📱 NanoClaw 平台支持

ClawSec 现已支持 NanoClaw，这是一款基于 Claude 代理的容器化 WhatsApp 机器人。

clawsec-nanoclaw 技能

位置：skills/clawsec-nanoclaw/

专为 NanoClaw 的容器化架构设计的完整安全套件：

• 9 个 MCP 工具，供代理检查漏洞
  • 预警检查与浏览
  • 安装前安全检查
  • 技能包签名验证（Ed25519）
  • 文件完整性监控
• 自动预警推送——每 6 小时拉取并缓存一次预警信息
• 平台过滤——仅显示与 NanoClaw 相关的预警
• IPC 通信——确保容器环境下的主机安全通信
• 完整文档——包括安装指南、使用示例和故障排除

NanoClaw 的预警推送

该推送现在会监控与 NanoClaw 相关的关键字：

• NanoClaw——直接的产品名称
• WhatsApp-bot——核心功能
• baileys——WhatsApp 客户端库依赖项

预警信息中可指定 platforms: ["nanoclaw"]，以明确问题仅针对 NanoClaw 平台。

NanoClaw 的快速入门

详细安装说明请参阅 skills/clawsec-nanoclaw/INSTALL.md。

快速集成步骤：

1. 将技能复制到 NanoClaw 部署环境中
2. 在容器内集成 MCP 工具
3. 在主机端添加 IPC 处理程序和缓存服务
4. 重启 NanoClaw

---

📦 ClawSec 套件（OpenClaw）

clawsec-suite 是一个技能管理器，用于安装、验证并维护来自 ClawSec 目录的安全技能。

clawsec-suite 是可选的编排工具；您也可以直接将各个技能作为独立软件包进行安装。

ClawSec 技能

技能	描述	安装方式	兼容性
📡 clawsec-feed	实时 CVE 更新的安全公告订阅监控	✅ 默认包含	所有代理
🔭 openclaw-audit-watchdog	自动化每日审计，支持 DM 通知及可选的邮件报告	⚙️ 可选（需单独安装）	OpenClaw/MoltBot/Clawdbot
👻 soul-guardian	漂移检测与文件完整性保护，并具备自动恢复功能	⚙️ 可选	所有代理
🤝 clawtributor	社区事件上报	❌ 可选（需明确请求）	所有代理

⚠️ clawtributor 不会默认安装，因为它可能会共享匿名化的事件数据。仅在用户明确请求时才进行安装。

⚠️ openclaw-audit-watchdog 专为 OpenClaw/MoltBot/Clawdbot 代理系列设计。其他代理将获得通用技能集。

套件特性

• 完整性验证：每个技能包都包含带有 SHA256 哈希值的 checksums.json
• 更新：自动检查新版本的技能
• 自愈能力：若完整性校验失败，将自动从可信发布中重新下载
• 公告交叉引用：已安装的技能会与安全公告流进行比对

---

📡 安全公告流

ClawSec 维护着一个持续更新的安全公告流，该流由 NIST 的国家漏洞数据库 (NVD) 自动填充。

公告流 URL

# 获取最新公告
curl -s https://clawsec.prompt.security/advisories/feed.json | jq '.advisories[] | select(.severity == "critical" or .severity == "high")'

规范端点：https://clawsec.prompt.security/advisories/feed.json
兼容镜像（旧版）：https://clawsec.prompt.security/releases/latest/download/feed.json

监控关键词

公告流会轮询与以下内容相关的 CVE：

• OpenClaw 平台：OpenClaw、clawdbot、Moltbot
• NanoClaw 平台：NanoClaw、WhatsApp-bot、baileys
• 提示注入模式
• 代理安全漏洞

可利用性上下文

ClawSec 会为 CVE 公告补充 可利用性上下文，以帮助代理评估实际风险，而不仅仅是原始的 CVSS 分数。新分析的公告可能包括：

• 漏洞利用证据：是否存在公开的漏洞利用代码
• 武器化状态：漏洞是否已被集成到常见的攻击框架中
• 攻击条件：成功利用所需的先决条件（如网络访问、身份验证、用户交互）
• 风险评估：结合技术严重性和可利用性得出的综合风险等级

此功能有助于代理优先处理那些构成直接威胁的漏洞，而非理论上的风险，从而做出更明智的安全决策。

公告模式

NVD CVE 公告：

{
  "id": "CVE-2026-XXXXX",
  "severity": "critical|high|medium|low",
  "type": "vulnerable_skill",
  "platforms": ["openclaw", "nanoclaw"],
  "title": "简短描述",
  "description": "来自 NVD 的完整 CVE 描述",
  "published": "2026-02-01T00:00:00Z",
  "cvss_score": 8.8,
  "nvd_url": "https://nvd.nist.gov/vuln/detail/CVE-2026-XXXXX",
  "exploitability_score": "high|medium|low|unknown",
  "exploitability_rationale": "为什么该 CVE 在代理部署中可能或不可能被利用",
  "references": ["..."],
  "action": "推荐的修复措施"
}

社区公告：

{
  "id": "CLAW-2026-0042",
  "severity": "high",
  "type": "prompt_injection|vulnerable_skill|tampering_attempt",
  "platforms": ["nanoclaw"],
  "title": "简短描述",
  "description": "来自问题的详细描述",
  "published": "2026-02-01T00:00:00Z",
  "affected": ["skill-name@1.0.0"],
  "source": "社区报告",
  "github_issue_url": "https://github.com/.../issues/42",
  "action": "推荐的修复措施"
}

平台取值：

• "openclaw" - 仅适用于 OpenClaw/Clawdbot/MoltBot
• "nanoclaw" - 仅适用于 NanoClaw
• ["openclaw", "nanoclaw"] - 适用于两个平台
• （空/缺失）- 适用于所有平台（向后兼容）

---

🔄 CI/CD 流水线

ClawSec 使用自动化流水线来实现持续的安全更新和技能分发。

自动化工作流

工作流	触发条件	描述
ci.yml	向 main 分支提交 PR 或推送	代码检查/类型检查/构建 + 技能测试套件
pages-verify.yml	向 main 分支提交 PR	验证 Pages 构建和签名输出，但不发布
poll-nvd-cves.yml	每日定时任务（UTC 06:00）	轮询 NVD 获取新 CVE，并更新公告流
community-advisory.yml	标记为 advisory-approved 的问题	将社区报告处理为公告
skill-release.yml	技能标签及元数据 PR 更改	验证 PR 中的版本一致性，并在标签上发布签名后的技能
deploy-pages.yml	成功的可信 CI/发布工作流运行后或手动触发	构建并部署 Web 界面至 GitHub Pages
wiki-sync.yml	向 main 分支推送并触及 wiki/**	将 wiki/ 同步到 GitHub Wiki 镜像

技能发布流水线

当某个技能被打上标签（例如 soul-guardian-v1.0.0）时，流水线会执行以下步骤：

1. 验证：检查 skill.json 版本是否与标签一致
2. 强制密钥一致性：验证固定发布的密钥引用在仓库 PEM 文件和 skills/clawsec-suite/SKILL.md 中是否一致
3. 生成校验和：为所有 SBOM 文件创建包含 SHA256 哈希值的 checksums.json
4. 签名与验证：对 checksums.json 进行签名，并将生成的 signing-public.pem 指纹与仓库中的标准密钥材料进行比对
5. 发布：将所有工件发布到 GitHub Releases
6. 覆盖旧版本：删除同一主版本线内的旧版本（标签保留）
7. 触发 Pages 更新：刷新网站上的技能目录

签名密钥一致性保障机制

为防止供应链漂移，CI 现在会在签名密钥引用出现偏差时立即失败。

保障脚本：

• scripts/ci/verify_signing_key_consistency.sh

检查内容：

• skills/clawsec-suite/SKILL.md 中内嵌的公钥指纹是否与 RELEASE_PUBKEY_SHA256 匹配
• 标准 PEM 文件是否都具有相同的指纹：
  • clawsec-signing-public.pem
  • advisories/feed-signing-public.pem
  • skills/clawsec-suite/advisories/feed-signing-public.pem
• 工作流中生成的公钥是否与标准密钥一致：
  • release-assets/signing-public.pem（发布工作流）
  • public/signing-public.pem（Pages 工作流）

实施位置：

• .github/workflows/skill-release.yml
• .github/workflows/deploy-pages.yml

发布版本管理与替代

ClawSec 遵循 语义化版本控制。每当发布新版本时：

场景	行为
新补丁/次要版本（例如 1.0.1、1.1.0）	同一主版本的先前版本会被删除
新主版本（例如 2.0.0）	前一主版本 (1.x.x) 会保留以支持向后兼容

为什么旧版本会消失？

当你发布 skill-v0.0.2 时，之前的 skill-v0.0.1 版本会自动被删除，以保持发布页面的整洁。每个主版本下仅保留最新版本。

• Git 标签会被保留 - 如果需要，你始终可以从现有标签重新创建发布
• 主版本共存 - skill-v1.x.x 和 skill-v2.x.x 的最新版本都会保留，以支持向后兼容

发布工件

每个技能发布包含：

• checksums.json - 用于完整性验证的 SHA256 哈希值
• skill.json - 技能元数据
• SKILL.md - 主要技能文档
• 来自 SBOM 的其他文件（脚本、配置等）

签名操作文档

关于 feed/发布签名的部署和操作指南：

• wiki/security-signing-runbook.md - 密钥生成、GitHub Secrets、轮换/撤销、事件响应
• wiki/migration-signed-feed.md - 从非签名 feed 的分阶段迁移、强制执行机制、回滚计划

---

🛠️ 离线工具

ClawSec 包含用于本地技能开发和验证的 Python 工具。

技能验证器

根据所需模式验证技能文件夹：

python utils/validate_skill.py skills/clawsec-feed

检查内容：

• skill.json 存在且为有效 JSON
• 必要字段齐全（名称、版本、描述、作者、许可证）
• SBOM 文件存在且可读
• OpenClaw 元数据结构正确

技能校验和生成器

为技能生成包含 SHA256 哈希值的 checksums.json：

python utils/package_skill.py skills/clawsec-feed ./dist

输出：

• checksums.json - 用于验证的 SHA256 哈希值

---

🛠️ 本地开发

先决条件

• Node.js 20+
• Python 3.10+（用于离线工具）
• npm

设置

# 安装依赖
npm install

# 启动开发服务器
npm run dev

填充本地数据

# 从本地 skills/ 目录填充技能目录
./scripts/populate-local-skills.sh

# 使用真实的 NVD CVE 数据填充公告 feed
./scripts/populate-local-feed.sh --days 120

# 从 wiki/ 生成 wiki LLMS 导出文件（用于本地预览）
./scripts/populate-local-wiki.sh

# 直接调用生成入口点（由 predev/prebuild 使用）
npm run gen:wiki-llms

注意：

• npm run dev 和 npm run build 会自动重新生成 wiki 的 llms.txt 导出文件（通过 predev/prebuild 钩子）。
• public/wiki/ 是生成的输出（本地 + CI），并被有意忽略在 Git 中。

构建

npm run build

---

📁 项目结构

├── advisories/
│   └── feed.json              # 主要公告 feed（自动从 NVD 更新）
├── components/                 # React 组件
├── pages/                      # 页面组件
├── wiki/                       # 事实来源文档（同步到 GitHub Wiki）
├── scripts/
│   ├── generate-wiki-llms.mjs # wiki/*.md -> public/wiki/**/llms.txt
│   ├── populate-local-feed.sh # 本地 CVE feed 填充工具
│   ├── populate-local-skills.sh # 本地技能目录填充工具
│   ├── populate-local-wiki.sh # 本地 wiki LLMS 导出填充工具
│   └── release-skill.sh       # 手动技能发布辅助工具
├── skills/
│   ├── clawsec-suite/       # 📦 套件安装程序（技能中的技能 - 从这里开始，让代理完成其余工作）
│   ├── clawsec-feed/        # 📡 公告 feed 技能
│   ├── clawsec-scanner/     # 🔍 漏洞扫描器（依赖项 + SAST + OpenClaw DAST）
│   ├── clawsec-nanoclaw/    # 📱 NanoClaw 平台安全套件
│   ├── clawsec-clawhub-checker/ # 🧪 ClawHub 声誉检查
│   ├── clawtributor/           # 🤝 社区报告技能
│   ├── openclaw-audit-watchdog/ # 🔭 自动审计技能
│   └── soul-guardian/         # 👻 文件完整性技能
├── utils/
│   ├── package_skill.py       # 技能打包工具
│   └── validate_skill.py      # 技能验证工具
├── .github/workflows/
│   ├── ci.yml                 # 跨平台 lint/类型检查/构建 + 测试
│   ├── pages-verify.yml       # 仅 PR 的页面构建验证
│   ├── poll-nvd-cves.yml      # CVE 轮询管道
│   ├── community-advisory.yml # 批准的问题 -> 公告 PR
│   ├── skill-release.yml      # 技能发布管道
│   ├── wiki-sync.yml          # 将 repo wiki/ 同步到 GitHub Wiki
│   └── deploy-pages.yml       # Pages 部署
└── public/                     # 静态资源 + 生成的发布工件

---

🤝 贡献

我们欢迎贡献！请参阅 CONTRIBUTING.md 获取指南。

提交安全公告

发现提示注入向量、恶意技能或安全漏洞？请通过 GitHub Issues 报告：

1. 使用 安全事件报告 模板打开新问题
2. 填写必填字段（严重性、类型、描述、受影响的技能）
3. 维护者将审核并添加 advisory-approved 标签
4. 公告会自动以 CLAW-{YEAR}-{ISSUE#} 的形式发布到 feed 中

详细指南请参阅 CONTRIBUTING.md。

添加新技能

1. 在 skills/ 下创建一个技能文件夹
2. 添加包含必要元数据和 SBOM 的 skill.json
3. 添加带有代理可读指令的 SKILL.md
4. 使用 python utils/validate_skill.py skills/your-skill 进行验证
5. 提交 PR 以供审查

📚 文档的事实来源

所有 wiki 内容均编辑此仓库下的 wiki/ 文件。GitHub Wiki (<repo>.wiki.git) 会在 wiki/** 在 main 分支上发生变化时，由 .github/workflows/wiki-sync.yml 从 wiki/ 同步而来。

LLM 导出文件从 wiki/ 生成到 public/wiki/：

• /wiki/llms.txt 是适用于 LLM 的导出文件，用于 wiki/INDEX.md（或在缺少 INDEX.md 时作为生成的后备索引）。
• /wiki/<page>/llms.txt 是该单个 wiki 页面的 LLM 可读导出文件。

---

📄 许可证

• 源代码：GNU AGPL v3.0 或更高版本 - 详情请参阅 LICENSE。
• font/ 中的字体：单独授权 - 详情请参阅 font/README.md。

---

ClawSec 快速上手指南

ClawSec 是一套专为 AI Agent 平台（如 OpenClaw、NanoClaw）设计的安全技能套件，提供统一的安全监控、完整性验证和威胁情报，保护您的 Agent 免受提示注入、配置漂移和恶意指令的侵害。

环境准备

系统要求

• 操作系统：Linux、macOS 或 Windows (PowerShell/WSL)
• 运行时：Node.js (推荐最新 LTS 版本)
• 包管理器：npm 或 npx

前置依赖

确保已安装 npx（通常随 Node.js 自动安装）。

• Linux/macOS: 支持 Bash 或 Zsh。
• Windows: 推荐使用 PowerShell。若需运行 .sh 脚本，请安装 WSL 或 Git Bash。

注意：在设置环境变量时，Linux/macOS 请使用双引号或未加引号的变量（如 "$HOME"），避免使用单引号导致变量无法展开。Windows PowerShell 建议使用 Join-Path 构建路径。

安装步骤

ClawSec 提供了一键安装命令，可自动部署完整的安全技能套件并进行完整性验证。

1. 执行安装命令

在终端中运行以下命令安装 clawsec-suite：

npx clawhub@latest install clawsec-suite

2. 完成初始化

安装完成后，套件将自动执行以下操作：

• 从发布的技能目录中发现可安装的保护模块。
• 使用签名的校验和验证发布版本的完整性。
• 设置咨询监控和基于钩子（hook）的保护流程。
• （可选）添加定期安全检查任务。

手动安装备选方案： 若需手动安装，请访问 最新发行版 SKILL.md 并按照说明操作。

3. 针对 NanoClaw 用户

如果您使用的是容器化的 WhatsApp Bot (NanoClaw)，请参考 skills/clawsec-nanoclaw/INSTALL.md 进行特定集成，主要步骤包括复制技能文件、集成 MCP 工具及重启服务。

基本使用

安装完成后，ClawSec 将自动在后台运行，无需复杂配置即可提供核心安全能力。

核心功能概览

• 🛡️ 文件完整性保护：自动检测关键文件（如 SOUL.md, IDENTITY.md）的漂移并尝试自动恢复。
• 📡 实时安全咨询：自动轮询 NVD CVE 数据库，获取与 OpenClaw/NanoClaw 相关的最新漏洞情报。
• 🔍 安全审计：内置自检脚本，用于检测提示注入标记和潜在漏洞。
• 🔐 校验和验证：对所有技能工件进行 SHA256 校验，确保未被篡改。

简单示例：查看高危漏洞情报

您可以直接通过命令行获取最新的关键和高危安全咨询：

curl -s https://clawsec.prompt.security/advisories/feed.json | jq '.advisories[] | select(.severity == "critical" or .severity == "high")'

给 AI Agent 的指令

如果您希望通过自然语言让 Agent 自行安装，可以发送以下指令：

Install ClawSec with npx clawhub@latest install clawsec-suite, then complete the setup steps from the generated instructions.

技能套件组成

默认安装的 clawsec-suite 包含以下核心技能：

• clawsec-feed: 实时监控安全咨询和 CVE 更新（默认启用）。
• soul-guardian: 检测配置漂移并守护文件完整性（可选，建议启用）。
• openclaw-audit-watchdog: 针对 OpenClaw/MoltBot 系列的每日自动审计（仅适用于该平台）。
• clawtributor: 社区事件报告工具（默认不安装，需用户显式请求以保护隐私）。