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

この検証に成功してから、アーカイブをインストールまたは展開してください。

目標

成熟したプラットフォームモジュール向けに ClawSec が追跡するものと同じセキュリティ機能を、Picoclaw に提供します。

スキル名	対応プラットフォーム	セキュリティフィード	設定ドリフト	エージェントのポスチャレビュー用レーン	サプライチェーン検証
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

このリグレッションでは、ローカルの ClawHub 互換レジストリから、HOME、PICOCLAW_HOME、PICOCLAW_WORKSPACE を分離した Docker 上の Picoclaw ワークスペースに、Picoclaw 独自の find_skills／install_skill パスを通じてスキルをインストールします。署名済みリリースアーティファクトの事前チェック入力を検証し、Picoclaw のスキルローダーでインストール済みスキルを一覧表示および読み込みできることを確認した後、Picoclaw 形式の config.json および launcher-config.json ファイルを使って、インストール済みコピーのプロファイル、ドリフト、アドバイザリーのフェイルクローズ、アドバイザリーのフィルタリング、サプライチェーン検証の各パスを実行します。