picoclaw-security-guardian

Picoclaw 安全防护

详细的架构和运维文档：wiki/modules/picoclaw-security-guardian.md。

安装 Vercel Skills

使用 Vercel Skills CLI 为此工具链安装：

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

发布制品验证

对于独立安装，请先验证已签名的发布清单，再信任 SKILL.md、skill.json 或压缩包。skill.json 文件是软件包元数据／SBOM 来源，发布流水线使用 ClawSec 发布密钥对 checksums.json 进行签名。

set -euo pipefail

SKILL_NAME="picoclaw-security-guardian"
VERSION="0.0.6"
REPO="prompt-security/clawsec"
TAG="${SKILL_NAME}-v${VERSION}"
BASE="https://github.com/${REPO}/releases/download/${TAG}"
ZIP_NAME="${SKILL_NAME}-v${VERSION}.zip"
TMP_DIR="$(mktemp -d)"
trap 'rm -rf "$TMP_DIR"' EXIT

RELEASE_PUBKEY_SHA256="711424e4535f84093fefb024cd1ca4ec87439e53907b305b79a631d5befba9c8"

curl -fsSL "$BASE/checksums.json" -o "$TMP_DIR/checksums.json"
curl -fsSL "$BASE/checksums.sig" -o "$TMP_DIR/checksums.sig"
curl -fsSL "$BASE/signing-public.pem" -o "$TMP_DIR/signing-public.pem"
curl -fsSL "$BASE/$ZIP_NAME" -o "$TMP_DIR/$ZIP_NAME"
curl -fsSL "$BASE/SKILL.md" -o "$TMP_DIR/SKILL.md"
curl -fsSL "$BASE/skill.json" -o "$TMP_DIR/skill.json"

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

openssl base64 -d -A -in "$TMP_DIR/checksums.sig" -out "$TMP_DIR/checksums.sig.bin"
openssl pkeyutl -verify -rawin -pubin \
  -inkey "$TMP_DIR/signing-public.pem" \
  -sigfile "$TMP_DIR/checksums.sig.bin" \
  -in "$TMP_DIR/checksums.json" >/dev/null

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

verify_manifest_file() {
  asset="$1"
  path="$2"
  expected="$(jq -r --arg asset "$asset" '.files[$asset].sha256 // empty' "$TMP_DIR/checksums.json")"
  if [ -z "$expected" ]; then
    echo "ERROR: checksums.json missing $asset" >&2
    exit 1
  fi
  actual="$(hash_file "$path")"
  if [ "$actual" != "$expected" ]; then
    echo "ERROR: checksum mismatch for $asset" >&2
    exit 1
  fi
}

expected_archive="$(jq -r '.archive.sha256 // empty' "$TMP_DIR/checksums.json")"
if [ -z "$expected_archive" ]; then
  echo "ERROR: checksums.json missing archive.sha256" >&2
  exit 1
fi
actual_archive="$(hash_file "$TMP_DIR/$ZIP_NAME")"
if [ "$actual_archive" != "$expected_archive" ]; then
  echo "ERROR: archive checksum mismatch" >&2
  exit 1
fi

verify_manifest_file "SKILL.md" "$TMP_DIR/SKILL.md"
verify_manifest_file "skill.json" "$TMP_DIR/skill.json"

echo "Signed release manifest, archive, SKILL.md, and skill.json verified."

只有在验证成功后，才能安装或解压压缩包。

目标

为 Picoclaw 提供与 ClawSec 为成熟平台模块跟踪的支持矩阵相同的安全能力：

技能名称	支持的平台	安全源	配置漂移	Agent 安全态势审查通道	供应链验证
picoclaw-security-guardian	Picoclaw	是	是	独立软件包	是

威胁模型

Picoclaw 是一个轻量级 AI 网关，可提供聊天渠道、Web UI、工具执行、MCP 服务、凭据、调度器以及嵌入式／路由器部署。本技能重点关注这些功能可能带来安全风险的信任边界。

默认安全态势

• 默认只读。
• v0.0.1 中不创建调度器。
• 默认不进行出站网络访问。
• 除非运维人员提供仅用于测试的临时路径，否则只会在 $PICOCLAW_HOME/security/clawsec/ 下写入明确指定的报告／配置文件输出。
• 除非运维人员通过 --allow-unsigned 指定已记录的紧急／离线时段，否则验证状态未通过时，建议检查将按失败关闭处理。

安全公告意识

使用 scripts/check_advisories.mjs 并提供本地源／缓存和验证状态：

node scripts/check_advisories.mjs   --feed ~/.picoclaw/security/clawsec/feed.json   --state ~/.picoclaw/security/clawsec/feed-verification-state.json

该脚本会筛选适用于 picoclaw、ai-gateway、未指定平台／所有平台的公告，以及受影响软件包条目中包含 picoclaw 的公告。 预期的源输入为整合后的已签名 ClawSec 安全公告源，因此其中可能包含 NVD CVE、经批准的社区公告，以及尚无 CVE 的临时 GHSA 记录。

漂移防护

生成确定性配置文件：

node scripts/generate_profile.mjs   --output ~/.picoclaw/security/clawsec/current-profile.json

与已批准的基线进行比较：

node scripts/check_drift.mjs   --baseline ~/.picoclaw/security/clawsec/baseline-profile.json   --current ~/.picoclaw/security/clawsec/current-profile.json   --fail-on critical

严重漂移包括启用公开 Web UI、禁用 Web UI 身份验证、禁用工作区限制、采用未签名／不安全的验证模式、已验证源状态回退，以及受监控文件／发布制品指纹发生变化。

供应链验证

使用校验和清单及分离签名验证 Picoclaw 发布制品。要获得通过的供应链判定，必须验证已签名清单：

node scripts/verify_supply_chain.mjs \
  --artifact ./picoclaw \
  --checksums ./checksums.json \
  --signature ./checksums.json.sig \
  --public-key ./feed-signing-public.pem

仅校验和模式只能验证完整性，不能验证来源。仅在时间较短且有记录的离线分类时段内使用 --allow-unsigned-checksums；该模式不应满足生产安装验证要求。

运维审查说明

• 将公开 UI 绑定（0.0.0.0、-public）视为严重审查项，直到确认身份验证和网络允许列表有效。
• 将 MCP 服务视为独立的信任边界；审查每个服务对文件系统、网络和凭据的访问权限。
• 将第三方 OpenWrt／LuCI 封装程序视为独立的供应链制品。将其安装到路由器前，先验证来源。
• 切勿在定期检查或生产检查中持续启用未签名公告模式。

验证

python utils/validate_skill.py skills/picoclaw-security-guardian
node skills/picoclaw-security-guardian/test/profile.test.mjs
node skills/picoclaw-security-guardian/test/drift.test.mjs
node skills/picoclaw-security-guardian/test/supply_chain.test.mjs
bash -n skills/picoclaw-security-guardian/test/picoclaw_security_guardian_sandbox_regression.sh

预发布安装回归

发布 v0.0.1 制品前，请从仓库根目录运行隔离安装流程：

skills/picoclaw-security-guardian/test/picoclaw_security_guardian_sandbox_regression.sh

该回归测试会通过 Picoclaw 自身的 find_skills / install_skill 路径，从本地兼容 ClawHub 的注册表中，将技能安装到由 Docker 托管且隔离的 Picoclaw 工作区，并隔离 HOME、PICOCLAW_HOME 和 PICOCLAW_WORKSPACE。它会验证已签名的发布制品预检输入，确认 Picoclaw 的技能加载器可以列出并加载已安装的技能，然后针对 Picoclaw 风格的 config.json 和 launcher-config.json 文件，运行已安装副本的配置文件、漂移、建议故障关闭、建议筛选和供应链验证流程。