clawsec-suite

ClawSec Suite

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 にあるカタログメタデータにフォールバックします。

インストール

シェル間でのパスに関する注意

• 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 で終了します。
• その後、ユーザーに明示的な2回目の確認を求め、--confirm-advisory を付けて再実行します。

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

これにより、次の2段階の確認が確実に行われます。

1. 1回目の確認：ユーザーがインストールを依頼します。
2. 2回目の確認：アドバイザリの詳細を確認した後、ユーザーがインストールを明示的に承認します。

埋め込みアドバイザリフィードの動作

埋め込みフィードのロジックでは、次のデフォルト値を使用します。

• リモート統合フィード URL：https://clawsec.prompt.security/advisories/feed.json
• フィードの内容：NVD CVE、承認済みのコミュニティアドバイザリ、暫定的な GHSA（CVE なし）アドバイザリ。
• リモートフィード署名 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 フィールドを含めることができます。

• 悪用可能性スコア：high、medium、low、または unknown
• コンテキストを考慮した評価：攻撃ベクトル、認証要件、AI エージェントのデプロイパターンを考慮します。
• エクスプロイトの入手可能性：公開エクスプロイトと武器化の状況を検出します。

アドバイザリを処理する際は、深刻度に加えて悪用可能性も優先順位付けに反映してください。深刻度が HIGH で悪用可能性も HIGH の CVE は、深刻度が CRITICAL で悪用可能性が LOW の CVE より緊急性が高くなります。

詳しい手法については、悪用可能性スコアリングのドキュメントを参照してください。

ハートビートとの統合

セキュリティチェックを定期的に実行する際の唯一のエントリーポイントとして、スイートのハートビートスクリプトを使用します。

• skills/clawsec-suite/HEARTBEAT.md

このスクリプトは、次の処理を行います。

• スイートの更新チェック
• フィードのポーリング
• 新しいアドバイザリの検出
• 影響を受けるスキルとの相互参照
• 悪意のあるアドバイザリ／削除推奨アドバイザリへの対応に関する、承認を条件としたガイダンス
• 状態の永続的な更新

承認を条件とする対応の契約

アドバイザリが、悪意のあるスキルまたは削除が推奨されるスキルであることを示しており、そのスキルがインストール済みの場合：

1. アドバイザリの詳細と深刻度を、直ちにユーザーに通知します。
2. 影響を受けるスキルの削除または無効化を推奨します。
3. 元のインストール依頼は、最初の意向としてのみ扱います。
4. 削除／無効化の操作を行う前（またはリスクのあるインストールを続行する前）に、明示的な2回目の確認を求めます。
5. 2回目の確認を得てからのみ続行します。

スイートのフックとハートビートのガイダンスは、意図的にデフォルトで非破壊的な動作をします。

アドバイザリの抑制／許可リスト

アドバイザリガーディアンのパイプラインでは、セキュリティチームが確認して許容したアドバイザリを、オプトインで抑制できます。ファーストパーティのツールや、デプロイ環境に該当しないアドバイザリに便利です。

有効化

アドバイザリの抑制には単一のゲートが必要です。設定ファイルの"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などのチェック識別子を持つ監査エントリは、監査パイプラインのみで照合されます。CVE-2026-25593やCLAW-2026-0001などのアドバイザリIDを持つアドバイザリエントリは、アドバイザリパイプラインのみで照合されます。各パイプラインは、それぞれに関連するエントリを絞り込みます。

オプションのスキルインストール

現在インストール可能なスキルを動的に検出し、必要なものをインストールします。

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から移行する場合は、通知の重複を避けるため、正規の状態ファイルを1つだけ使用してください。
• 初回使用前に、公開鍵のフィンガープリントを別経路で確認し、固定してください。