clawsec-suite

ClawSec 套件

Vercel Skills 安装

使用 Vercel Skills CLI 为此运行环境安装：

npx skills add prompt-security/clawsec --skill clawsec-suite -a openclaw -y

操作说明

• 必需的运行时：node、npx、openclaw、curl、jq、shasum、openssl、unzip
• 副作用：设置脚本会在 ~/.openclaw/hooks 下安装一个安全公告钩子，可选择创建无人值守的 openclaw cron 任务，并使用 npx clawhub@latest install 进行受保护的安装
• 网络行为：除非固定为本地路径，否则会获取已签名的安全公告源文件和远程目录元数据
• 信任模型：该套件可以建议移除或阻止有风险的安装，但移除和安装操作的覆盖仍须经过审批

这意味着 clawsec-suite 可以：

• 监控 ClawSec 安全公告源，
• 跟踪自上次检查以来新增的安全公告，
• 将安全公告与本地安装的技能交叉比对，
• 针对恶意技能安全公告建议移除，并要求用户先明确批准，
• 同时继续作为其他 ClawSec 防护的设置／管理入口。

内置与可选防护

内置于 clawsec-suite

• 嵌入式已签名安全公告信任集：advisories/feed.json、feed.json.sig、checksums.json、checksums.json.sig 和 feed-signing-public.pem
• HEARTBEAT.md 中的可移植心跳工作流
• 安全公告轮询、状态跟踪和受影响技能检查
• OpenClaw 安全公告守护钩子包：hooks/clawsec-advisory-guardian/
• 用于钩子和可选 cron 调度的设置脚本：scripts/
• 受保护的安装程序：scripts/guarded_skill_install.mjs
• 用于发现可安装技能的动态目录：scripts/discover_skill_catalog.mjs

单独安装（动态目录）

clawsec-suite 不会在本文档中硬编码附加技能名称。

运行时从权威索引（https://clawsec.prompt.security/skills/index.json）发现当前目录：

SUITE_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-suite"
node "$SUITE_DIR/scripts/discover_skill_catalog.mjs"

回退行为：

• 如果可以访问远程目录索引且索引有效，套件会使用该索引。
• 如果远程索引不可用或格式错误，脚本会回退到 skill.json 中的套件本地目录元数据。

安装

跨 Shell 路径说明

• 在 bash／zsh 中，让路径变量保持可展开状态（例如，INSTALL_ROOT="$HOME/.openclaw/skills"）。
• 不要为包含主目录变量的路径加单引号（避免使用 '$HOME/.openclaw/skills'）。
• 在 PowerShell 中，设置明确的路径：
  • $env:INSTALL_ROOT = Join-Path $HOME ".openclaw\\skills"
• 如果传入的路径包含未解析的标记（例如 \$HOME/...），套件脚本现在会立即失败并显示清晰的错误信息。

选项 A：通过 clawhub 安装（推荐）

npx clawhub@latest install clawsec-suite

选项 B：手动下载并验证签名与校验和

set -euo pipefail

VERSION="${SKILL_VERSION:?Set SKILL_VERSION (e.g. 0.0.8)}"
INSTALL_ROOT="${INSTALL_ROOT:-$HOME/.openclaw/skills}"
DEST="$INSTALL_ROOT/clawsec-suite"
BASE="https://github.com/prompt-security/clawsec/releases/download/clawsec-suite-v${VERSION}"

TEMP_DIR="$(mktemp -d)"
trap 'rm -rf "$TEMP_DIR"' EXIT

# Pinned release-signing public key (verify fingerprint out-of-band on first use)
# Fingerprint (SHA-256 of SPKI DER): 711424e4535f84093fefb024cd1ca4ec87439e53907b305b79a631d5befba9c8
RELEASE_PUBKEY_SHA256="711424e4535f84093fefb024cd1ca4ec87439e53907b305b79a631d5befba9c8"
cat > "$TEMP_DIR/release-signing-public.pem" <<'PEM'
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAS7nijfMcUoOBCj4yOXJX+GYGv2pFl2Yaha1P4v5Cm6A=
-----END PUBLIC KEY-----
PEM

ACTUAL_KEY_SHA256="$(openssl pkey -pubin -in "$TEMP_DIR/release-signing-public.pem" -outform DER | shasum -a 256 | awk '{print $1}')"
if [ "$ACTUAL_KEY_SHA256" != "$RELEASE_PUBKEY_SHA256" ]; then
  echo "ERROR: Release public key fingerprint mismatch" >&2
  exit 1
fi

ZIP_NAME="clawsec-suite-v${VERSION}.zip"

# 1) Download release archive + signed checksums manifest + signing public key
curl -fsSL "$BASE/$ZIP_NAME" -o "$TEMP_DIR/$ZIP_NAME"
curl -fsSL "$BASE/checksums.json" -o "$TEMP_DIR/checksums.json"
curl -fsSL "$BASE/checksums.sig" -o "$TEMP_DIR/checksums.sig"

# 2) Verify checksums manifest signature before trusting any hashes
openssl base64 -d -A -in "$TEMP_DIR/checksums.sig" -out "$TEMP_DIR/checksums.sig.bin"
if ! openssl pkeyutl -verify \
  -pubin \
  -inkey "$TEMP_DIR/release-signing-public.pem" \
  -sigfile "$TEMP_DIR/checksums.sig.bin" \
  -rawin \
  -in "$TEMP_DIR/checksums.json" >/dev/null 2>&1; then
  echo "ERROR: checksums.json signature verification failed" >&2
  exit 1
fi

EXPECTED_ZIP_SHA="$(jq -r '.archive.sha256 // empty' "$TEMP_DIR/checksums.json")"
if [ -z "$EXPECTED_ZIP_SHA" ]; then
  echo "ERROR: checksums.json missing archive.sha256" >&2
  exit 1
fi

if command -v shasum >/dev/null 2>&1; then
  ACTUAL_ZIP_SHA="$(shasum -a 256 "$TEMP_DIR/$ZIP_NAME" | awk '{print $1}')"
else
  ACTUAL_ZIP_SHA="$(sha256sum "$TEMP_DIR/$ZIP_NAME" | awk '{print $1}')"
fi

if [ "$EXPECTED_ZIP_SHA" != "$ACTUAL_ZIP_SHA" ]; then
  echo "ERROR: Archive checksum mismatch for $ZIP_NAME" >&2
  exit 1
fi

echo "Checksums manifest signature and archive hash verified."

# 3) Install verified archive
mkdir -p "$INSTALL_ROOT"
rm -rf "$DEST"
unzip -q "$TEMP_DIR/$ZIP_NAME" -d "$INSTALL_ROOT"

chmod 600 "$DEST/skill.json"
find "$DEST" -type f ! -name "skill.json" -exec chmod 644 {} \;

echo "Installed clawsec-suite v${VERSION} to: $DEST"
echo "Next step (OpenClaw): node \"\$DEST/scripts/setup_advisory_hook.mjs\""

OpenClaw 自动化（钩子 + 可选 Cron）

安装套件后，启用安全公告守护钩子：

SUITE_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-suite"
node "$SUITE_DIR/scripts/setup_advisory_hook.mjs"

设置脚本会在安装并启用持久钩子之前打印预检审查信息。

可选：创建／更新定期 cron 提醒（默认每 6h 一次），以触发主会话安全公告扫描：

SUITE_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-suite"
node "$SUITE_DIR/scripts/setup_advisory_cron.mjs"

cron 设置脚本会在创建或更新无人值守任务之前打印预检审查信息。

此功能会：

• 在 agent:bootstrap 和 /new（command:new）时扫描，
• 将安全公告的 affected 条目与已安装技能进行比对，
• 处理包含 application: "openclaw" 的安全公告（以及为保持向后兼容而处理缺少 application 的旧条目），
• 在出现新匹配项时通知，
• 并在任何移除流程开始前征求用户明确批准。

启用钩子后重启 OpenClaw 网关。然后运行一次 /new，以便在下一个会话上下文中立即执行扫描。

技能安装防护流程（双重确认）

当用户要求安装技能时，将其视为第一次请求，并运行防护式安装检查：

SUITE_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-suite"
node "$SUITE_DIR/scripts/guarded_skill_install.mjs" --skill helper-plus --version 1.0.1

行为：

• 如果未找到匹配的公告，则继续安装。
• 如果省略了 --version，匹配规则会更加保守：任何提及该技能名称的公告都视为匹配。
• 如果找到匹配的公告，脚本会打印公告上下文并以代码 42 退出。
• 随后要求用户进行明确的第二次确认，并使用 --confirm-advisory 重新运行：

node "$SUITE_DIR/scripts/guarded_skill_install.mjs" --skill helper-plus --version 1.0.1 --confirm-advisory

这可确保：

1. 第一次确认：用户要求安装。
2. 第二次确认：用户查看公告详情后明确批准安装。

内置公告源行为

内置公告源逻辑使用以下默认值：

• 远程整合公告源 URL：https://clawsec.prompt.security/advisories/feed.json
• 公告源内容：NVD CVE、已批准的社区公告，以及未关联 CVE 的临时 GHSA 公告。
• 远程公告源签名 URL：${CLAWSEC_FEED_URL}.sig（使用 CLAWSEC_FEED_SIG_URL 覆盖）
• 远程校验和清单 URL：同级目录中的 checksums.json（使用 CLAWSEC_FEED_CHECKSUMS_URL 覆盖）
• 本地种子回退文件：~/.openclaw/skills/clawsec-suite/advisories/feed.json
• 本地公告源签名：${CLAWSEC_LOCAL_FEED}.sig（使用 CLAWSEC_LOCAL_FEED_SIG 覆盖）
• 本地校验和清单：~/.openclaw/skills/clawsec-suite/advisories/checksums.json
• 固定的公告源签名密钥：~/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem（使用 CLAWSEC_FEED_PUBLIC_KEY 覆盖）
• 状态文件：~/.openclaw/clawsec-suite-feed-state.json
• 钩子速率限制环境变量（OpenClaw 钩子）：CLAWSEC_HOOK_INTERVAL_SECONDS（默认值为 300）

验证失败即拒绝： 默认要求公告源签名。如果存在配套校验和文件，则会验证校验和清单。只有在采用此版本时上游尚无已签名公告源文件的情况下，才将 CLAWSEC_ALLOW_UNSIGNED_FEED=1 作为临时迁移绕过选项。

快速检查公告源

FEED_URL="${CLAWSEC_FEED_URL:-https://clawsec.prompt.security/advisories/feed.json}"
STATE_FILE="${CLAWSEC_SUITE_STATE_FILE:-$HOME/.openclaw/clawsec-suite-feed-state.json}"

TMP="$(mktemp -d)"
trap 'rm -rf "$TMP"' EXIT

if ! curl -fsSLo "$TMP/feed.json" "$FEED_URL"; then
  echo "ERROR: Failed to fetch advisory feed"
  exit 1
fi

if ! jq -e '.version and (.advisories | type == "array")' "$TMP/feed.json" >/dev/null; then
  echo "ERROR: Invalid advisory feed format"
  exit 1
fi

mkdir -p "$(dirname "$STATE_FILE")"
if [ ! -f "$STATE_FILE" ]; then
  echo '{"schema_version":"1.0","known_advisories":[],"last_feed_check":null,"last_feed_updated":null}' > "$STATE_FILE"
  chmod 600 "$STATE_FILE"
fi

NEW_IDS_FILE="$TMP/new_ids.txt"
jq -r --argfile state "$STATE_FILE" '($state.known_advisories // []) as $known | [.advisories[]?.id | select(. != null and ($known | index(.) | not))] | .[]?' "$TMP/feed.json" > "$NEW_IDS_FILE"

if [ -s "$NEW_IDS_FILE" ]; then
  echo "New advisories detected:"
  while IFS= read -r id; do
    [ -z "$id" ] && continue
    jq -r --arg id "$id" '.advisories[] | select(.id == $id) | "- [\(.severity | ascii_upcase)] \(.id): \(.title)"' "$TMP/feed.json"
    jq -r --arg id "$id" '.advisories[] | select(.id == $id) | "  Exploitability: \(.exploitability_score // "unknown" | ascii_upcase)"' "$TMP/feed.json"
  done < "$NEW_IDS_FILE"
else
  echo "FEED_OK - no new advisories"
fi

可利用性上下文

公告源中的公告可以包含 exploitability_score 和 exploitability_rationale 字段，帮助 Agent 优先处理现实世界的威胁：

• 可利用性评分：high、medium、low 或 unknown
• 结合上下文的评估：考虑攻击途径、身份验证要求和 AI Agent 部署模式
• 漏洞利用可用性：检测公开漏洞利用和武器化状态

处理公告时，除了严重性之外，还应按可利用性排序。HIGH 严重性且 HIGH 可利用性的 CVE，比 CRITICAL 严重性但 LOW 可利用性的 CVE 更紧急。

详细方法请参阅可利用性评分文档。

心跳集成

使用套件心跳脚本作为定期安全检查的唯一入口：

• skills/clawsec-suite/HEARTBEAT.md

它负责处理：

• 套件更新检查，
• 公告源轮询，
• 新公告检测，
• 受影响技能的交叉引用，
• 针对恶意/建议移除公告的审批门控响应指南，
• 以及持久化状态更新。

审批门控响应约定

如果公告指出某技能存在恶意行为或建议移除该技能，且该技能已安装：

1. 立即向用户告知公告详情和严重性。
2. 建议移除或禁用受影响的技能。
3. 将原始安装请求仅视为初步意向。
4. 在执行删除/禁用操作之前（或继续进行有风险的安装之前），要求用户明确进行第二次确认。
5. 只有在获得第二次确认后才继续操作。

套件钩子和心跳指南默认不会执行破坏性操作。

公告抑制/允许列表

公告守护程序流程支持选择性抑制已由安全团队审查并接受的公告。这适用于内部工具或不影响当前部署的公告。

激活

抑制公告只需满足一个条件：配置文件必须包含 "enabledFor"，且其数组中包含 "advisory"。无需使用 CLI 标志——配置文件中的哨兵值本身就是启用门槛。

如果缺少 enabledFor 数组、数组为空或不包含 "advisory"，则会正常报告所有公告。

配置文件解析（4 级）

公告防护程序按照与审计流水线相同的优先级顺序解析抑制配置：

1. 显式传入的 --config <path> 参数
2. OPENCLAW_AUDIT_CONFIG 环境变量
3. ~/.openclaw/security-audit.json
4. .clawsec/allowlist.json

配置格式

{
  "enabledFor": ["advisory"],
  "suppressions": [
    {
      "checkId": "CVE-2026-25593",
      "skill": "clawsec-suite",
      "reason": "First-party security tooling — reviewed by security team",
      "suppressedAt": "2026-02-15"
    },
    {
      "checkId": "CLAW-2026-0001",
      "skill": "example-skill",
      "reason": "Advisory does not apply to our deployment configuration",
      "suppressedAt": "2026-02-16"
    }
  ]
}

哨兵语义

• "enabledFor": ["advisory"] —— 仅启用公告抑制
• "enabledFor": ["audit"] —— 仅启用审计抑制（对公告流水线无效）
• "enabledFor": ["audit", "advisory"] —— 两条流水线均遵循抑制规则
• 缺少或为空的 enabledFor —— 不启用任何抑制（安全默认值）

匹配规则

• checkId： 与公告 ID 精确匹配（例如，CVE-2026-25593 或 CLAW-2026-0001）
• skill： 与公告中的受影响技能名称进行不区分大小写的匹配
• 两个字段都必须匹配，公告才会被抑制

每条抑制记录的必填字段

字段	说明	示例
checkId	要抑制的公告 ID	CVE-2026-25593
skill	受影响的技能名称	clawsec-suite
reason	审计记录所需的理由（必填）	First-party tooling, reviewed by security team
suppressedAt	ISO 8601 日期（YYYY-MM-DD）	2026-02-15

与审计流水线共用配置

公告和审计流水线共用同一个配置文件。使用 enabledFor 数组控制哪些流水线遵循抑制列表：

{
  "enabledFor": ["audit", "advisory"],
  "suppressions": [
    {
      "checkId": "skills.code_safety",
      "skill": "clawsec-suite",
      "reason": "First-party tooling — audit finding accepted",
      "suppressedAt": "2026-02-15"
    },
    {
      "checkId": "CVE-2026-25593",
      "skill": "clawsec-suite",
      "reason": "First-party tooling — advisory reviewed",
      "suppressedAt": "2026-02-15"
    }
  ]
}

审计记录（其检查标识符类似 skills.code_safety）仅由审计流水线匹配。公告记录（其公告 ID 类似 CVE-2026-25593 或 CLAW-2026-0001）仅由公告流水线匹配。每条流水线都会筛选与自身相关的记录。

可选技能安装

动态查看当前可安装的技能，然后安装所需技能：

SUITE_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-suite"
node "$SUITE_DIR/scripts/discover_skill_catalog.mjs"

# then install any discovered skill by name
npx clawhub@latest install <skill-name>

也可获取机器可读输出，用于自动化：

node "$SUITE_DIR/scripts/discover_skill_catalog.mjs" --json

安全说明

• 在信任 checksums.json 中的文件 URL／哈希值之前，务必先验证其签名，然后再验证每个文件的校验和。
• 验证公告源的分离签名；除临时迁移期间外，不要启用 CLAWSEC_ALLOW_UNSIGNED_FEED。
• 限制公告轮询频率（两次检查至少间隔 5 分钟）。
• 将影响已安装技能的 critical 和 high 级公告视为需要立即处理的事项。
• 如果从独立的 clawsec-feed 迁移，请保留一个规范状态文件，以避免重复通知。
• 首次使用前，通过带外方式固定并验证公钥指纹。