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の順に探します。WindowsでPython Install Managerを使う場合の不具合はAppXSvcのメモリ枯渇の記事にあります
• 作業ディレクトリがgitリポジトリである必要があります。ターン終了時とコミット時のレビューはgit状態との差分を取るため、リポジトリの外では会話に何も出さずスキップされます。編集直後のパターンチェックだけはリポジトリの外でも動きます

初回実行時、プラグインは~/.claude/security/配下に仮想環境を作りClaude Agent SDKをインストールします。pipとネットワークアクセスが必要です。このインストールに失敗するか、利用可能なPythonが3.10未満の場合の挙動は、認証方式で次のように分かれます。古いPythonが原因のときは一度だけ通知が出ます。

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

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

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

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

• Claude Desktopアプリ(ローカル / SSHセッションのいずれも): プロンプト横の+ボタンからPlugins、Add pluginの順に開くプラグインブラウザーを使う
• VS Code拡張: Manage pluginsダイアログからインストールする
• クラウドセッション: ユーザー設定のプラグインも、リポジトリの.claude/settings.jsonに書いたプラグインも読み込まれません。組織がmanaged settingsで配るプラグインは別の扱いです

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

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

/reload-plugins

チームのローカルセッションで有効にする

インストール時に選ぶスコープで、誰に効くかと記録先の設定ファイルが決まります。

チェックイン済みのプロジェクト設定には、次の形で宣言します。

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

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

スクリプトやCIから入れる

シェルから入れるclaude plugin installには、対話パネルを使わないためのオプションがあります。v2.1.287のclaude plugin install --helpは、次の3つを表示します(抜粋)。

--json                     Print one machine-readable result line on stdout
                           instead of the human message (same exit codes; ...
-s, --scope <scope>        Installation scope: user, project, or local
                           (default: "user")
-y, --yes                  Accept the displayed marketplace-declared command
                           without the confirmation prompt ... (required when
                           stdin or stdout is not a TTY)

--scopeの既定はuserです。-yはマーケットプレイスが宣言したコマンドの確認を省くためのフラグで、標準入力か標準出力がTTYでないときは必須と説明されています。--jsonは結果を1行の機械可読な形で出すので、パイプラインで成否を拾えます。

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

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

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

ターン終了時のレビューは、そのターンに作業ツリーで変わった内容のgit diffを計算します。編集ツールだけでなく、Bashコマンドやサブエージェントによる変更も含まれます。この差分をセキュリティに絞ってレビューするため、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に実行時の診断を書き込みます。レビューが出てこないときはまずここを確認します
• security-patterns.yamlを置いたのに反映されない: PyYAMLがインポートできない環境ではYAML形式は無視されます。security-patterns.jsonに切り替えれば任意のPython環境で動きます

まとめ

追加のモデル使用量が出るのはターン終了時とコミット時の2層だけで、編集直後の層で足りるかどうかがENABLE_STOP_REVIEW=0などの切り方を決めます。チームに配るなら設定のコミットに各自のインストールが加わり、クラウドセッションにはmanaged settingsで配ります。