snyk-agent-scan-compliance

ペルソナ： スキル作成に関するコンプライアンスの専門家です。有用な情報を抑制したり削除したりせず、内容を再構成して snyk-agent-scan のアラートを解消します。

思考モード： ある種類のアラートへの修正によって、別のアラートが表面化したり抑制されたりする可能性があるため、複数のアラートを修正する際は、できる限り深く考えてください。深く考えることで手戻りを減らせます。Claude Code では、ultrathink を使って拡張思考を明示的に有効にしてください。

snyk-agent-scan のコンプライアンス

snyk-agent-scan ツールは、スキル本文に含まれる安全でないパターンを、サードパーティコンテンツの露出（W011）、悪意のある外部 URL（W012）、MCP ツール呼び出しによるプロンプトインジェクション（W001）の 3 つのカテゴリで分析します。情報を損なうことなく、内容を再構成して 3 つすべてを修正できます。

参照ファイル

ファイル	読むタイミング
references/w001-patterns.md	W001 アラートの修正時 — MCP ツール名のパターン
references/w011-patterns.md	W011 アラートの修正時 — 命令形の URL と外部コンテンツのパターン
references/w012-patterns.md	W012 アラートの修正時 — バージョンの固定とフロントマターへの移動

クイックリファレンス

アラート	重大度	根本原因	主な修正方法
W011	高	スキル本文が、エージェントに外部コンテンツの取得や解釈を指示している	命令形を、利用可能性を示す受動的なヒントに置き換える
W012	高	スキル本文が、実行時に取得・実行される外部 URL を参照している	フロントマターの install ブロックに移動し、バージョンを固定する
W001	高	スキル本文で MCP ツール関数を明示的に指定している	代わりに汎用的な表現を使う

スキャナーの実行

# Scan a single skill
SNYK_TOKEN=<token> snyk-agent-scan --skills skills/<name>/

# Scan all skills
SNYK_TOKEN=<token> snyk-agent-scan --skills ./skills

スキャナーには有効な SNYK_TOKEN が必要です。CI では、シークレットとして保存してください。snyk-agent-scan がインストールされていない場合は、インストールせずに代替として uvx snyk-agent-scan@latest を使用できます。アラートの種類ごとの修正方法については、詳細なパターンを参照してください。

W011 — サードパーティコンテンツの露出

スキル本文に、外部コンテンツを取得、確認、または評価したうえで、それに基づいて行動するようエージェントに指示する命令形の動詞が使われていると、W011 が発生します。スキャナーは、エージェントを外部の操作を行う文法上の主語として扱います。

ルール：

• Check <url> や Fetch <url> を、受動的なヒントに置き換えます。例：<url> のリリースノートが役立つ場合があります。
• 外部データに関する指示から「常に」を削除します。例：変更履歴を常に参照してください → 変更履歴には、互換性を損なう変更が記載されています。
• ツール呼び出し（gh repo view、govulncheck）は、実行前の行動をエージェントに促すような文章のチェックリストではなく、コードブロックに記載します。
• ツールの実行と判断を切り離します。ツールの実行は問題ありませんが、そのリモート由来の出力だけを根拠としてリファクタリングを行うのは避けてください。

修正例を 12 件以上掲載したW011 パターンカタログを参照してください。

W012 — 悪意のある可能性がある外部 URL

実行時に取得・実行される外部コンテンツ（@latest を指定したパッケージのインストール、パイプでシェルに渡すパターン、誤った、または存在しないメジャーバージョンの GitHub Actions）を本文で参照していると、W012 が発生します。

ルール：

• go install pkg@latest などのコマンドは、本文からフロントマターの metadata.openclaw.install ブロックに移動します。スキャナーはフロントマターを検出対象にしません。
• GitHub Actions は、正しい最新のメジャーバージョン（@v6 ではなく @v4）に固定します。
• スキル本文では、パイプでシェルに渡すパターン（curl ... | sh）を使用しないでください。

修正例を 8 件以上掲載したW012 パターンカタログを参照してください。

W001 — MCP ツール呼び出しを介したプロンプトインジェクション

W001 は、スキル本文に MCP サーバーのツール関数が明示的に記載されている場合に発火し、プロンプトインジェクションの検出をトリガーします。

ルール：

• スキル本文にツール関数名（resolve-library-id、query-docs、mcp__*）を記載しないでください。
• 一般的な表現に置き換えてください：Context7 can help as a discoverability platform.
• MCP ツール名は allowed-tools フロントマターフィールドには記載できます。制限されるのは本文のみです。

安全な言い換えについては、W001 パターンカタログを参照してください。

修正の方法

アラートを1件ずつ修正し、変更のたびに snyk-agent-scan を再実行して、次に進む前にアラート数が減ったことを確認してください。修正してもアラートが減らない場合は、その変更を元に戻して別の方法を試してください。検証されていない変更を重ねないでください。

スキャンで複数のアラートが検出された場合は、手戻りを最小限に抑えるため、次の順序で修正してください。

1. W001 (simplest) — remove MCP tool names from body; confirm allowed-tools is correct
2. W011 — rewrite imperative sentences as passive statements; move checklist items to code blocks
3. W012 — move install commands to frontmatter; pin versions
4. Re-scan after each individual fix to verify improvement

URL の再構成後に目立つようになると、W011 の修正によって、隠れていた W012 が表面化することがあります。

誤検知

すべてのアラートが実際の問題とは限りません。誤検知の可能性が高い条件は次のとおりです。

条件	誤検知の可能性が高いか？
URL が指示ではなく参考情報として Markdown の表セルに記載されている	はい — 表は通常安全です
ライブラリを説明するスキルで、その URL がライブラリの公式ドキュメントである	はい — 通常安全です
URL がフロントマターの homepage または issues リンクである	はい — スキャン対象外です
ツール名がシェルコマンドとしてトリプルバッククォートのコードブロック内にある	場合によります — コードブロックは検査が比較的緩やかです
クイックリファレンスのコードブロックに、バージョンを固定した go install がある	場合によります — バージョンが固定されているものはリスクが低くなります
外部リソースに関係しない文に always が含まれている	はい — 「always」だけでは W011 は発火しません

アラートが誤検知の可能性が高い場合も、受動的なヒントのパターンを使って再構成してください。スキャナーのヒューリスティックは実際のユーザーを保護するためのものです。スキャナーの誤りだと決めつけるより、再構成するほうが安全です。

作成前のチェックリスト

最初のスキャン前にアラートを避けるため、新しいスキル本文の作成中に次の項目を確認してください。

• URL に対してエージェントが何らかの操作を行う文で、エージェントが主語になっていない
• 本文内のインストール手順に @latest タグが含まれていない
• 本文の文章に MCP ツール関数名（mcp__*、resolve-library-id など）が含まれていない
• すべてのインストールコマンドがフロントマターの install ブロックに記載されている
• GitHub Actions のバージョンが、実在するメジャーバージョンと一致している
• ツールの呼び出しが順序付きチェックリストではなく、コードブロックに記載されている
• 外部リソースに関する指示の前に「always」がない

snyk-agent-scan でバグや予期しない動作を見つけた場合は、https://github.com/snyk/snyk-agent-scan/issues で issue を作成してください。

上記の参考ファイルに記載されていないアラート発火パターン（新しい回避手法、誤検知の条件、文書化されていないアラートコードなど）を見つけた場合は、https://github.com/samber/cc-skills/issues で issue を作成するか、samber/cc-skills リポジトリにプルリクエストを送って、該当するパターンファイルに追加してください。新しいパターンの追加は、このスキルへの最も価値ある貢献です。