Cloud Armor WAF Patrol MCP

cloudarmor-mcp

English | 日本語

Google Cloud Armor の WAF ログを巡回する MCP サーバーです。ルールごとの拒否サマリー、ホームリージョンにおける誤検知の確認、プレビュー（ドライラン）ルールのレビューを、Cloud Logging から直接実行できます。

毎日の「WAF は正常か？」という巡回向けに作られています。daily_brief を一度呼び出すだけで、何をブロックしたか、本来ブロックすべきでないものをブロックしていないか、プレビュールールを適用する準備ができているかを確認できます。

ドキュメント：https://shigechika.github.io/cloudarmor-mcp/

ツール

ツール	目的
daily_brief	1 回の呼び出しで確認できる朝のサマリー：適用中のルール優先度ごとの DENY、ホームリージョンの誤検知チェック、プレビュー中の DENY
enforce_denies	適用中のルール優先度ごとの DENY 件数
home_region_denies	送信元 IP のジオロケーションがホームリージョンを示す、適用中の DENY。既知の正常としてマークされていないものはすべて誤検知候補です
preview_denies	プレビュー（ドライラン）中の DENY 件数。静かなプレビュールールは適用候補です
health_check	バージョン、設定の有無、Cloud Logging の最小限のプローブ

すべてのツールは読み取り専用です。件数には上限（クエリあたりデフォルト 2000 件）が設けられており、上限に達した結果は正確な合計ではなく、>= N (capped) として報告されます。

セットアップ

1. 最小権限のサービスアカウント

roles/logging.viewer のみを持つサービスアカウントを作成し、キーをダウンロードします。サービスアカウントは人間のアカウントと異なり、組織の再認証ポリシーの対象ではないため、無人で実行する巡回が知らないうちに期限切れになることはありません。

gcloud iam service-accounts create waf-log-viewer --project=YOUR_PROJECT
gcloud projects add-iam-policy-binding YOUR_PROJECT \
  --member=serviceAccount:waf-log-viewer@YOUR_PROJECT.iam.gserviceaccount.com \
  --role=roles/logging.viewer
gcloud iam service-accounts keys create key.json \
  --iam-account=waf-log-viewer@YOUR_PROJECT.iam.gserviceaccount.com

2. インストール

pip install cloudarmor-mcp
# or
uv tool install cloudarmor-mcp

3. 環境変数

変数	必須	説明
CLOUDARMOR_PROJECT	はい	ロードバランサーのログを受け取る GCP プロジェクト ID
GOOGLE_APPLICATION_CREDENTIALS	はい	サービスアカウントのキーファイルへのパス
CLOUDARMOR_BACKEND_SERVICES	いいえ	絞り込み対象のバックエンドサービス名をカンマ区切りで指定（デフォルト：すべて）
CLOUDARMOR_HOME_REGION	いいえ	ホームトラフィックとして扱う ISO リージョンコード（例：JP）。誤検知チェックを有効にします
CLOUDARMOR_RULES_INI	いいえ	ルール INI のパス（ラベルと既知の正常な優先度。下記参照）
CLOUDARMOR_MAX_ENTRIES	いいえ	クエリごとに取得する最大件数（デフォルト：2000）

4. 任意のルール INI

ルール番号をプロンプトに含めず、レポートに人間が読みやすいラベルを表示します。

[rules]
101 = block non-home deep-path crawlers
500 = AutoDiscover probe block
1002 = OWASP LFI protection

[home]
; home-region DENYs on these priorities are expected, not false positives
known_normal_priorities = 500, 600

5. Claude Code（プラグイン）

このリポジトリは単一プラグインのマーケットプレイスも兼ねているため、Claude Code からサーバーをインストールできます。

/plugin marketplace add shigechika/cloudarmor-mcp
/plugin install cloudarmor-mcp@cloudarmor-mcp

このプラグインは uvx cloudarmor-mcp を起動し、上記の環境変数と同じ変数を読み取ります。Claude Code を起動する前に、それらをエクスポートしてください。GOOGLE_APPLICATION_CREDENTIALS は、引き続き自分のマシン上にあるサービスアカウントのキーファイルを指している必要があります。このプラグインからそのファイルを提供したり取得したりすることはできないため、プラグイン自体の設定だけではサーバーを完全に構成できません。

uvx は Claude Code を実行するプロセスの PATH 上にある必要があります。通常、ログインシェルには設定されていますが、GUI から起動したアプリでは設定されていない場合があります。プラグインが起動しない場合は、uv をシステム全体にインストールしてください。

6. Claude Code（手動）

claude mcp add cloudarmor -- cloudarmor-mcp

上記の環境変数をサーバーの環境に設定します。

7. Codex

codex mcp add cloudarmor -- cloudarmor-mcp

上記の環境変数は --env KEY=VALUE で渡します（-- より前に指定してください）。

stdio サーバーを起動するその他の MCP クライアントも同様に使用できます。コマンドとして cloudarmor-mcp を指定し、環境に上記の環境変数を設定してください。

CLI

cloudarmor-mcp --version   # print version
cloudarmor-mcp --check     # config + API probe (exit 0 when healthy)
cloudarmor-mcp --brief     # print daily_brief to stdout (cron / smoke tests)

DENY エントリーを1日分エクスポートする（バッチ）

cloudarmor-mcp deny-export --date 2026-09-22 --tz Asia/Tokyo > out.tmp && mv out.tmp 2026-09-22.json

その日の暦日（--tz の [00:00, 24:00)、デフォルトは UTC）に記録された DENY ログエントリーごとに1レコードを含む JSON ドキュメントを標準出力に書き込みます。強制ポリシーとプレビューポリシーの判定結果（policy、priority、action、outcome、rule_ids）、送信元 IP、Cloud Armor のログに記録されたリージョンコードと ASN、メソッド、ホスト、パス（クエリー文字列は除外され、その長さのみを保持します）、ステータス、User-Agent（200文字）、バックエンドが含まれます。--kind both（デフォルト）は、どちらかのポリシーが DENY としたエントリーを1回のクエリーで取得するため、プレビュールールに一致し、かつ拒否されたリクエストは、両方のセクションが入力された状態で1回だけ表示されます。--backend a,b を指定すると、CLOUDARMOR_BACKEND_SERVICES が上書きされます。

このパッケージでリクエストごとのログデータを含む出力は、これと traffic-export（後述）のみです。これは、同じホスト上でその日分のデータを集計するオペレーター向けのバッチ処理を想定しています。ドキュメントの末尾には count、fetched、malformed、capped が含まれます。capped が true の場合、エクスポートは --max-entries（デフォルトは 200000）に達した時点で停止しており、古いものから順に並んだその日のデータの先頭部分です（CLOUDARMOR_MAX_ENTRIES は適用されません）。レコードはストリーミングされるため、1日分のデータが増えてもメモリ使用量は増加しません。また、Cloud Logging の読み取りクォータ（1分あたり60リクエスト）を超えないよう、ページの取得は最大1.2秒に1回です。そのため、200,000件のエントリーがある日は処理に数分かかります。まだ終わっていない日は拒否されます。Cloud Logging のエントリーは遅れて届くため、現地時間の午前0時を過ぎて数分経ってから実行してください。また、まず一時ファイルに書き込んでください。クエリーに失敗すると終了コードは1になり、標準出力には終端されていないドキュメントが残ることがあります。

リクエスト全件をサンプリングして1日分エクスポートする（バッチ）

cloudarmor-mcp traffic-export --date 2026-09-22 --tz Asia/Tokyo --sample 0.01 > out.tmp && mv out.tmp 2026-09-22.json

deny-export と同じドキュメントレイアウトおよびレコードフィールドを、Cloud Logging の sample(insertId, RATE)（--sample、デフォルトは 0.01）で間引いた、その日の すべてのロードバランサーリクエスト（許可、拒否、CDN キャッシュからの応答を含む）について出力します。サンプルは各エントリーの insertId のハッシュなので、1日を通して均等に分散され、実行ごとに同じレートを指定すれば同じエントリーが選択されます。件数に 1 / sample を掛けるとその日の推定値になります。ただし、capped が true の場合は除きます。エントリーは古いものから順に読み取られるため、上限に達したエクスポートにはその日の早い時間帯しか含まれません。その場合は、--sample の値を下げるか、代わりに --max-entries を増やしてください。各レコードには cache_hit も含まれます。バックエンドのセキュリティポリシーがリクエストを評価しなかった場合（たとえば CDN キャッシュヒット時）、enforced: null となり、リージョンコードと ASN は含まれません。キャッシュヒットを判別するには、enforced ではなく cache_hit を使用してください。 ヘッダーには kind の代わりに sample が含まれます。DENY ログでは確認できない、訪問者（ブラウザー、クローラー、AI エージェントなど）を調べるのに使用してください。deny-export のリクエストごとのデータに関する注意事項は、この出力にも当てはまります。レコードには正規の訪問者のアドレスも含まれます。

レポートを読む

• ルール別の強制 DENY — 通常のブロック件数です。内訳に急な変化があれば確認してください。
• ホームリージョンからの DENY — 自国または自地域からのリクエストが拒否された件数です。正規のユーザーや正規のクローラーが拒否された場合もここに表示されます。たまたまローカル発のスキャナー通信も含まれるため、known_normal_priorities リストによって AutoDiscover のブロックなど、想定内のルールは不審なリストから除外されます。
• プレビュー DENY — ドライラン中のルールです。一定期間にわたってホームリージョンからのヒットがないプレビュールールは、強制適用に移行する候補です。

ライセンス

MIT