Claude Code security-guidanceで脆弱性を自動検知する

security-guidanceは、Claudeが自分で書いたコードの変更をその場でセキュリティ観点でレビューし、見つかった問題を同じセッション内で直させるプラグインです。人がレビューを依頼するのではなく、編集のたびに自動で走ります。導入方法、3層あるチェックの中身、独自ルールの追加、コストと無効化の手順を扱います。手動で1回だけ差分を調べる/security-reviewコマンドや、PR時に走るCode Reviewの4経路とは別の仕組みで、両方を重ねて使う前提の機能です。

security-guidanceプラグインは何をするものか

security-guidanceは公式Anthropicマーケットプレイスで配布されるプラグインで、インストールすると自動的に動き始めます。呼び出すコマンドはなく、覚えておく操作もありません。Claudeが書いたコードをインジェクション・安全でないデシリアライズ・危険なDOM操作などの観点で継続的にチェックし、問題が見つかればClaude自身に修正を指示します。

この仕組みはPR時に走るCode Reviewの前段に位置します。Code Reviewはプルリクエストに載った差分を精査しますが、security-guidanceはそこに載る前、コードを書いている最中に問題を潰します。PRに届く問題の絶対数を減らすのがこのプラグインの役割で、Code Reviewはそれでも残ったものを拾う後段の網です。

導入前に確認すること

動作にはいくつかの前提があります。

• PATHにPython 3.7以上が必要です。エージェント型のコミットレビューと、Amazon BedrockやGoogle Cloud's Agent Platform経由でモデルを呼ぶ場合のレビュー全般は、Python 3.10以上が必須です。プラグインはpython3.13からpython3.10までのバージョン付きインタープリタを優先し、無ければpython3、python、py -3の順に探します
• 作業ディレクトリがgitリポジトリである必要があります。ターン終了時とコミット時のレビューはgit状態との差分を取るため、リポジトリの外では会話に何も出さずスキップされます。編集直後のパターンチェックだけはリポジトリの外でも動きます

初回実行時、プラグインは~/.claude/security/配下に仮想環境を作りClaude Agent SDKをインストールします。pipとネットワークアクセスが必要です。このインストールに失敗するか、利用可能なPythonが3.10未満の場合の挙動は認証方式で分かれます。Anthropicのアカウントで直接認証している場合は、コミットレビューが単発レビューにフォールバックします。サードパーティープロバイダー経由では、モデルを使うレビューそのものがスキップされます。古いPythonが原因のときは一度だけ通知が出ます。

インストールと有効化の手順

ターミナルのClaude Codeセッションで、公式Anthropicマーケットプレイスからインストールします。

/plugin install security-guidance@claude-plugins-official

/pluginはターミナルCLIでのみ使えるインタラクティブなパネルです。この環境で/pluginが使えないとClaudeが返す場合は、別の方法で有効化します。

• Claude Desktopアプリ(ローカル / SSHセッションのいずれも): プロンプト横の+ボタンからPlugins、Add pluginの順に開くプラグインブラウザーを使う
• Claude Code on the webやクラウドセッション: .claude/settings.jsonにプラグインを宣言する(下記参照)

ターミナルでのインストールはスコープを尋ねてきます。ユーザースコープを選ぶと、このマシンで新しく始めるローカルセッションすべてに読み込まれます。

インストールが失敗した場合はメッセージで切り分けます。「Marketplace "claude-plugins-official" not found」ならマーケットプレイスを追加してから再試行し(/plugin marketplace add anthropics/claude-plugins-official)、プラグインが見つからないならプラグイン名を確認します。インストール概要に「Run /reload-plugins to activate.」と出ていたら、再起動せずに反映させます。

/reload-plugins

クラウドセッションと共有リポジトリで有効にする

ユーザースコープのプラグインはClaude Code on the webには引き継がれません。クラウドセッションはローカルマシンでなくクラウド上で動くためです。クラウドセッションで有効にする、あるいはリポジトリをクローンした全員に配るには、プロジェクトのチェックイン済み設定に宣言します。

{
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true
  }
}

管理者はmanaged settingsのenabledPluginsで組織全体に有効化できます。

3層のチェックはそれぞれ何を見ているか

プラグインはClaudeの作業を3つのタイミング、それぞれ違う深さでレビューします。

編集直後のチェックはモデル呼び出しを伴わないため追加コストがかかりません。Claudeがファイルに書き込むたびに新しいコンテンツをスキャンし、危険なパターンが見つかればその警告をClaudeの次のステップ向けの文脈に追記します。同じファイル内の同じパターンへの警告は1セッション1回だけ出るため、繰り返しの一致で会話が埋まることはありません。security-patterns.yamlで自分のパターンをこの層に追加できます。

ターン終了時のレビューは、そのターンで変わった内容のgit diffを計算し、セキュリティに絞った別のClaude呼び出しに渡します。バックグラウンドで動くためClaudeの返答は遅れません。問題が見つかるとClaudeは指摘を受け取り、フォローアップとして対処します。この層は1ターンあたり最大30ファイルの変更をカバーし、あなたに制御を返す前に最大3回連続で発火します。

コミット・プッシュ時のレビューは、ClaudeがBashツールを通じてgit commitやgit pushを実行したときだけ動きます。あなた自身のシェルからのコミットや、セッション内の!によるシェルエスケープはレビュー対象外です。1時間あたり最大20回のコミット・プッシュレビューという上限があり、コミットレビューの指摘がターン終了時レビューの指摘と重複する場合はClaudeへの再指示を省略するため、クリーンなコミットはこの層から何も出力しません。

独自ルールを追加する

拡張ポイントは2つあり、どちらも既存の組み込みチェックを無効化するのではなく追加するだけです。

モデルが使うレビュー向けには、プロジェクトに.claude/claude-security-guidance.mdを作り、脅威モデルやレビュー観点を平文で書きます。組み込みの脆弱性チェックリストに加えて、この内容が追加の文脈として読み込まれます。

# このリポジトリのセキュリティ観点
 
- `customer_id`や`account_number`をINFO以上のレベルでログに出さない
- `/admin`配下の全ルートはDBを読む前に`require_role("admin")`を呼ぶ
- トークン比較には`===`でなく`crypto.timingSafeEqual`を使う

これらはレビュー担当への指示であって、確定的なガードレールではありません。プラグインは違反をClaudeが直すべき指摘として提示しますが、書き込みをブロックしたり全ての違反を捕まえることを保証したりはしません。追加のみが可能で、「この脆弱性クラスは無視してよい」というルールを書いても、その種の指摘が抑制されることはありません。強制力が必要なら、保護対象ファイルへの編集をブロックするhookやCIチェックと組み合わせます。

編集直後のパターンチェックには.claude/security-patterns.yamlで正規表現や部分一致のルールを追加できます。

patterns:
  - rule_name: internal_api_key
    substrings: ["sk_live_", "AKIA"]
    reminder: "ハードコードされたAPIキーの接頭辞です。シークレットマネージャーから読み込んでください。"
  - rule_name: tenant_unfiltered_query
    regex: "\\.objects\\.all\\(\\)"
    paths: ["**/src/tenants/**"]
    reminder: "マルチテナントのコードはorg_idで絞り込んでください。"

rule_name(識別子)・reminder(警告文、1KBまで)・regexかsubstringsのどちらか一方・paths(対象パスのglob、任意)・exclude_paths(除外パスのglob、任意)の5フィールドで構成します。security-patterns.ymlとsecurity-patterns.jsonも同じスキーマで読み込まれ、JSON形式はPython環境を選ばず動きます(YAML形式はPyYAMLのインポートが前提)。カスタムルールは最大50件まで読み込まれ、破滅的バックトラッキングを起こしやすい正規表現はスキップされます。

ルールファイルはユーザースコープ(~/.claude/claude-security-guidance.md、全プロジェクトに適用)・プロジェクトスコープ(.claude/claude-security-guidance.md、リポジトリにコミット)・プロジェクトローカル(.claude/claude-security-guidance.local.md、個人用の上書き、.gitignoreに追加)の3か所を探索し、存在する全ての内容を連結します。ガイダンスファイルの合計上限は8KBです。security-patterns.yamlも同じ3か所を探索します。

コストと無効化

編集直後のパターンチェックはモデルを呼ばないため追加コストはゼロです。ターン終了時とコミット時のレビューはそれぞれ追加のモデル使用量を消費し、通常のClaudeリクエストと同じく利用量に加算されます。コミットレビューはエージェント型で1コミットあたり複数ターンかかることがあります。目安として、ファイルを変更したターンごとに1回のレビュー呼び出し、コミットごとに1回のより深いレビューが走り、いずれも前述の上限に収まります。両方のモデルによるレビューは既定でClaude Opus 4.7を使い、SECURITY_REVIEW_MODELでターン終了時レビューのモデルを、SG_AGENTIC_MODELでコミットレビューのモデルを個別に変更できます。プラグイン自体は全プランで利用できます。

層ごとに無効化したい場合は、対応する環境変数を設定します。

ユーザースコープで一時停止するには/plugin disable security-guidance@claude-plugins-official、完全に取り除くには/plugin uninstall security-guidance@claude-plugins-officialを使います。プロジェクトの.claude/settings.json経由で有効化されていた場合、/pluginからのアンインストールはチェックイン済みファイルを直接編集せず.claude/settings.local.jsonに上書きを書き込むため、あなただけプラグインが止まりチームメイトには影響しません。同じダイアログから、共有の.claude/settings.json自体を書き換えて全員分を無効化することも選べます。managed settings経由で有効化されていた場合は管理者しか無効化できません。

hooksの上に構築されている仕組み

security-guidanceは完全にhooksの上に組まれています。SessionStartでPython環境をブートストラップし、UserPromptSubmitでターン終了時レビューが差分を取る基準となる作業ツリーのスナップショットを取得し、Edit・Write・NotebookEditへのPostToolUseで編集直後のパターンチェックを、Stopでターン終了時のdiffレビューをバックグラウンド実行し、git commit・git pushにフィルタしたBashへのPostToolUseでコミット・プッシュレビューを走らせます。自分でhooksを組む際は、公式マーケットプレイスのリポジトリでこのプラグインの実装を読むと、hookから別のモデル呼び出しを行い結果をセッションに戻す実装例として参考になります。

他のセキュリティツールとどう重ねるか

security-guidanceは多層防御の1枚に過ぎず、後段のチェックを置き換えるものではありません。

Claudeが書いている最中のコードでなく、すでに手元にあるコードの脆弱性を探したいときは、セッション内でファイルやディレクトリのレビューを頼むか、リポジトリ全体をより深くスキャンしたいならClaude Securityプラグインを使います。/security-reviewが対象にするのは現在のブランチの差分だけです。どの経路でもレビューはチェックアウト済みのソースコードを読むのであって、稼働中のサイトやデプロイ済みサービスは対象外です。

つまずきやすいポイント

• 診断ログを見ずに「動いていない」と判断する: プラグインは~/.claude/security/log.txtに実行時の診断を書き込みます。レビューが出てこないときはまずここを確認します
• gitリポジトリ外で動かして黙ってスキップされる: ターン終了時とコミット時のレビューはgit状態を前提にしており、リポジトリの外では会話に何も出さずスキップします
• security-patterns.yamlを置いたのに反映されない: PyYAMLがインポートできない環境ではYAML形式は無視されます。security-patterns.jsonに切り替えれば任意のPython環境で動きます
• サードパーティープロバイダーでモデルによるレビューが動かない: Amazon BedrockやGoogle Cloud's Agent Platformの認証では、モデルによるレビュー自体にClaude Agent SDKが必要になるため、Python 3.10未満やSDKインストール失敗の環境ではその層がスキップされます
• 認証設定なしのセッションでレビューが薄いと感じる: Anthropicのアカウントでもサードパーティープロバイダーでもないセッションでは、モデルによるレビューそのものがスキップされ、編集直後のパターンチェックだけが動きます

よくある質問

security-guidanceは書き込みやコミットをブロックしますか

しません。指摘は書いているClaudeへの指示として渡され、Claudeが会話の中で対処します。レビュー担当のモデルが問題を見逃す可能性もあるため、唯一の防御手段としては扱いません。

無料プランでも使えますか

プラグイン自体は全プランで利用できます。ただしターン終了時とコミット時のレビューは追加のモデル使用量を消費するため、通常のClaudeリクエストと同じく利用量の上限に影響します。

/security-reviewコマンドと同時に使う意味はありますか

あります。security-guidanceはClaudeが書いている最中に問題を潰す層で、/security-reviewは現在のブランチの差分をあなたが望むタイミングで一括点検する層です。役割が異なるため重ねて使う前提の設計です。

自分のsecurity-patterns.yamlで組み込みパターンを無効化できますか

できません。拡張ポイントはどちらも追加専用で、組み込みチェックを個別に無効化する手段はありません。層ごと丸ごと止めるには環境変数を使います。

まとめ

security-guidanceは、Claudeが書いたコードを編集直後・ターン終了時・コミット時の3層でレビューし、見つけた問題を同じセッション内でClaude自身に直させるプラグインです。編集直後の層はコストゼロ、残る2層は追加のモデル使用量を伴います。導入は/plugin install security-guidance@claude-plugins-officialの1コマンドで、独自ルールは追加専用のガイダンスファイルとパターンファイルで拡張できます。手動の/security-reviewやPR時のCode Reviewを置き換える機能ではなく、それらより手前でリスクを減らす前段の層として位置づけて使うのが実務での落としどころです。