ClawSec 套件

这意味着clawsec-suite可以：

• 监控 ClawSec 安全通告源，
• 追踪自上次检查以来新增的通告，
• 将通告与本地安装的技能进行交叉比对，
• 针对恶意技能通告建议移除，并需事先获得用户的明确批准，
• 同时仍可作为其他 ClawSec 防护功能的设置/管理入口。

内置与可选防护功能

已内置到 clawsec-suite 中

• 嵌入式源种子文件：advisories/feed.json
• HEARTBEAT.md 中包含的可移植心跳工作流
• 安全通告轮询 + 状态追踪 + 受影响技能检查
• OpenClaw 安全通告守护程序钩子包：hooks/clawsec-advisory-guardian/
• 用于钩子和可选定时任务调度的设置脚本：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 提醒任务（默认每6小时），该任务会触发主会话的咨询扫描：

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

这增加了：

• 在以下时机进行扫描：代理：引导程序和/new(命令：new),
• 比较咨询受影响的条目与已安装技能进行比对，
• 考虑具有应用："openclaw"的咨询（以及为向后兼容性而保留的无应用字段的遗留条目），
• 当出现新匹配时通知，
• 并且在任何移除流程前要求明确的用户批准。

启用钩子后重启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
• 远程源签名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
• Hook 速率限制环境变量 (OpenClaw hook):CLAWSEC_HOOK_INTERVAL_SECONDS(默认值300)

故障关闭验证：默认情况下需要提供签名。当存在配套的校验和构件时，会验证校验和清单。仅当上游尚无可用的签名 feed 构件时，在采用此版本的过程中作为临时迁移绕过措施，才设置CLAWSEC_ALLOW_UNSIGNED_FEED=1。

快速 Feed 检查

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

可利用性上下文

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

• 可利用性评分：高、中、低或未知
• 上下文感知评估：考虑攻击向量、身份验证要求以及AI代理部署模式
• 漏洞利用可用性：检测公开漏洞利用和武器化状态

处理安全公告时，除了严重性之外，还应优先考虑可被利用性。一个严重性为高 + 可被利用性为高的CVE比一个严重性为严重 + 可被利用性为低的CVE更为紧急。

详细方法论，请参见可被利用性评分文档。

心跳集成

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

• skills/clawsec-suite/HEARTBEAT.md

它处理：

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

审批门控响应契约

如果一项建议表明某个技能是恶意的或建议移除，且该技能已安装：

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

套件钩子和心跳指南在默认情况下被设计为非破坏性的。

建议抑制 / 允许列表

建议守护管道支持对已由您的安全团队审查并接受的建议进行选择性抑制。这对于第一方工具或不适用于您部署环境的建议非常有用。

激活

建议抑制需要满足一个单一条件：配置文件必须包含"enabledFor"字段，且"advisory"在数组中。无需命令行标志——配置文件中的哨兵值即为选择启用开关。

如果enabledFor数组缺失、为空或不包含"advisory"，则所有建议都将正常报告。

配置文件解析（四层优先级）

建议守护程序使用与审计管道相同的优先级顺序解析抑制配置：

1. 显式--config <路径>参数
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:与咨询中受影响技能名称进行不区分大小写的匹配
• 两个字段都必须匹配，咨询才会被抑制

每个抑制条目所需的字段

与审计流水线共享配置

建议流水线和审计流水线共享同一个配置文件。使用启用对象数组来控制哪些流水线遵循抑制列表：

{
  "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

安全注意事项

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