hermes-attestation-guardian

Hermes 证明守护程序

重要范围：

• 此技能仅面向 Hermes 基础设施（CLI/Gateway/由配置文件管理的部署）。
• 此技能不是 OpenClaw 运行时钩子包。

使用 Vercel Skills 安装

使用此执行环境的 Vercel Skills CLI 安装：

npx skills add prompt-security/clawsec --skill hermes-attestation-guardian -a hermes-agent -y

发布制品验证

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

set -euo pipefail

SKILL_NAME="hermes-attestation-guardian"
VERSION="0.1.7"
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."

仅在此验证成功后安装或解压归档文件。

目标

生成确定性的 Hermes 安全态势证明，使用失败即关闭的完整性检查进行验证，并通过稳定的严重性映射比较基线偏移。

Hermes guard 信任策略说明

从社区来源安装时，应配置 Hermes guard 使用基于签名的信任策略（受信任签名者指纹允许列表），而不是仅基于来源名称的信任策略。未知签名者指纹应继续采用社区策略处理，无效签名必须保持阻止状态。

命令

# Generate attestation (default output: ~/.hermes/security/attestations/current.json)
node scripts/generate_attestation.mjs

# Generate with explicit policy + deterministic timestamp
node scripts/generate_attestation.mjs \
  --policy ~/.hermes/security/attestation-policy.json \
  --generated-at 2026-04-15T18:00:00.000Z \
  --write-sha256

# Verify schema + canonical digest
node scripts/verify_attestation.mjs --input ~/.hermes/security/attestations/current.json

# Verify with baseline diff (baseline must be authenticated)
node scripts/verify_attestation.mjs \
  --input ~/.hermes/security/attestations/current.json \
  --baseline ~/.hermes/security/attestations/baseline.json \
  --baseline-expected-sha256 <trusted-baseline-sha256> \
  --fail-on-severity high

# Optional detached signature verification
node scripts/verify_attestation.mjs \
  --input ~/.hermes/security/attestations/current.json \
  --signature ~/.hermes/security/attestations/current.json.sig \
  --public-key ~/.hermes/security/keys/attestation-public.pem

# Refresh advisory feed verification state (fail-closed by default)
node scripts/refresh_advisory_feed.mjs

# Check advisory feed verification + feed summary
node scripts/check_advisories.mjs

# Guarded advisory-aware skill verification gate (returns 42 on advisory match without explicit confirm)
node scripts/guarded_skill_verify.mjs --skill some-skill --version 1.2.3

# Explicit operator acknowledgement path for advisory matches
node scripts/guarded_skill_verify.mjs --skill some-skill --version 1.2.3 --confirm-advisory

# Optional temporary unsigned bypass (dangerous; emergency-only)
HERMES_ADVISORY_ALLOW_UNSIGNED_FEED=1 node scripts/refresh_advisory_feed.mjs --allow-unsigned

# Preview scheduler config without mutating user schedule state
node scripts/setup_attestation_cron.mjs --every 6h --print-only

# Apply managed scheduler block
node scripts/setup_attestation_cron.mjs --every 6h --apply

# Preview advisory check scheduler config (guarded flow, print-only default)
node scripts/setup_advisory_check_cron.mjs --every 6h --skill some-skill --print-only

# Apply advisory check scheduler block (uses guarded_skill_verify flow)
node scripts/setup_advisory_check_cron.mjs --every 6h --skill some-skill --version 1.2.3 --apply

# Emergency-only: unsigned bypass for scheduled advisory checks (do not keep enabled)
node scripts/setup_advisory_check_cron.mjs --every 6h --skill some-skill --allow-unsigned --apply

警告：计划任务命令中的 --allow-unsigned 仅用于事件响应。恢复后请立即移除此选项，并恢复已签名的公告验证。

证明负载（已实现）

生成器会输出：

• schema_version、platform、generated_at
• 生成器元数据（技能 + 节点版本）
• 主机元数据（主机名/平台/架构）
• posture.runtime（网关启用标志 + 风险开关）
• posture.feed_verification 状态（verified|unverified|unknown），来源于 $HERMES_HOME/security/advisories/feed-verification-state.json
• posture.integrity watched_files 和 trust_anchors（是否存在 + sha256）
• digests.canonical_sha256：基于稳定的规范 JSON 表示计算得出

失败即关闭行为

出现以下情况时，验证器会以非零状态码退出：

• 架构验证失败
• 不支持规范摘要算法，或摘要绑定不匹配
• 预期文件的 sha256 不匹配（如已配置）
• 分离签名验证失败（如已配置）
• 提供了基线，但未进行经过身份验证的信任绑定（--baseline-expected-sha256 和/或基线签名 + 公钥）
• 基线真实性或基线架构/摘要验证失败
• 基线差异的最高严重性达到或超过 --fail-on-severity（默认值：critical）

严重性消息会以 INFO / WARNING / CRITICAL 样式的行输出。

副作用

• generate_attestation.mjs 会在 $HERMES_HOME/security/attestations 下写入一个 JSON 文件（以及可选的 .sha256 文件）。
• verify_attestation.mjs 为只读。
• refresh_advisory_feed.mjs 会在 $HERMES_HOME/security/advisories 下写入已验证的源缓存和验证状态。
• check_advisories.mjs 为只读。
• guarded_skill_verify.mjs 会重新运行源刷新/验证（产生相同的公告缓存和状态副作用），然后执行公告感知门禁检查。
• 除非提供 --apply，否则 setup_attestation_cron.mjs 为只读。
• setup_attestation_cron.mjs --apply 仅重写当前用户管理的计划任务区块，该区块由以下标记界定：
  • # >>> hermes-attestation-guardian >>>
  • # <<< hermes-attestation-guardian <<<
• 除非提供 --apply，否则 setup_advisory_check_cron.mjs 为只读。
• setup_advisory_check_cron.mjs --apply 仅重写当前用户管理的公告检查计划任务区块，该区块由以下标记界定：
  • # >>> hermes-attestation-guardian-advisory-check >>>
  • # <<< hermes-attestation-guardian-advisory-check <<<
  • 生成的命令路径使用 guarded_skill_verify.mjs（公告感知门禁），而不是原始的 check_advisories.mjs

安全公告源覆盖选项

默认的签名安全公告源已整合：其中可包含 NVD CVE、经批准的社区安全公告，以及暂不关联 CVE 的临时 GHSA 记录。Hermes 匹配仍以受影响的软件包名称和受支持的版本范围为准。

• 源选择：HERMES_ADVISORY_FEED_SOURCE=auto|remote|local
• 远程构件：HERMES_ADVISORY_FEED_URL、HERMES_ADVISORY_FEED_SIG_URL、HERMES_ADVISORY_FEED_CHECKSUMS_URL、HERMES_ADVISORY_FEED_CHECKSUMS_SIG_URL
• 本地构件：HERMES_LOCAL_ADVISORY_FEED、HERMES_LOCAL_ADVISORY_FEED_SIG、HERMES_LOCAL_ADVISORY_FEED_CHECKSUMS、HERMES_LOCAL_ADVISORY_FEED_CHECKSUMS_SIG
• 固定公钥覆盖项：HERMES_ADVISORY_FEED_PUBLIC_KEY（默认使用内置固定公钥）
• 可选校验和开关：HERMES_ADVISORY_VERIFY_CHECKSUM_MANIFEST（默认：启用）
• 仅用于紧急情况的不安全绕过选项：HERMES_ADVISORY_ALLOW_UNSIGNED_FEED=1

说明

• Hermes 扫描和测试上下文按设计使用 .mjs：
  • 运行时脚本：scripts/*.mjs
  • 共享库：lib/*.mjs
  • 回归测试：test/*.test.mjs
• 保持 .mjs 路径和扩展名稳定，以确保扫描器范围、SBOM 接线和测试框架引用有效。
• 默认输出根目录为 ~/.hermes/security/attestations/。
• 未实现任何破坏性修复操作（删除／还原／隔离）。
• v0.0.2 尚未实现安全公告源远程 URL 允许列表；操作人员必须明确地信任所配置的安全公告源和校验和端点。
• 受保护的安全公告版本匹配支持 >=、<=、>、<、=、^、~、通配符 *、以空格或逗号分隔的 AND 比较器集合，以及 SemVer 预发布版本优先级。OR 和连字符范围仍不受支持，并会默认拒绝。
• 整合后的 NVD 安全公告源中的有效 CPE 2.3 条目会作为非软件包元数据接受，并在软件包名称匹配时忽略。格式错误的 CPE 条目仍会默认拒绝。
• 操作人员策略文件为可选 JSON，包含：
  • watch_files：文件路径列表
  • trust_anchor_files：文件路径列表