cloudarmor-mcp
English | 日本語
MCP server for Google Cloud Armor WAF log patrol — deny summaries per rule, home-region false-positive checks, and preview (dry-run) rule review, straight from Cloud Logging.
Built for a daily "is the WAF healthy?" patrol: one daily_brief call answers what did we block, did we block anyone we shouldn't have, and are the preview rules ready to promote.
Documentation: https://shigechika.github.io/cloudarmor-mcp/
Tools
| Tool | Purpose |
|---|---|
daily_brief | One-call morning summary: enforced DENYs by rule priority, home-region false-positive lens, preview DENYs |
enforce_denies | Enforced DENY counts per rule priority |
home_region_denies | Enforced DENYs whose source IP geolocates to your home region — anything not marked known-normal is a false-positive candidate |
preview_denies | Preview (dry-run) DENY counts — a quiet preview rule is a promotion candidate |
health_check | Version, config presence, and a minimal Cloud Logging probe |
All tools are read-only. Counts are hard-capped (default 2000 entries per query) and a capped result is reported as >= N (capped), never as an exact total.
Setup
1. Least-privilege service account
Create a service account with roles/logging.viewer only and download a key. Unlike human accounts, service accounts are not subject to organization re-authentication policies, so an unattended patrol never silently expires.
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. Install
pip install cloudarmor-mcp
# or
uv tool install cloudarmor-mcp
3. Environment variables
| Variable | Required | Meaning |
|---|---|---|
CLOUDARMOR_PROJECT | yes | GCP project ID that receives the load-balancer logs |
GOOGLE_APPLICATION_CREDENTIALS | yes | Path to the service-account key file |
CLOUDARMOR_BACKEND_SERVICES | no | Comma-separated backend service names to filter (default: all) |
CLOUDARMOR_HOME_REGION | no | ISO region code treated as home traffic, e.g. JP. Enables the false-positive lens |
CLOUDARMOR_RULES_INI | no | Path to a rules INI (labels + known-normal priorities, see below) |
CLOUDARMOR_MAX_ENTRIES | no | Max entries fetched per query (default 2000) |
4. Optional rules INI
Keep your rule numbering out of prompts and give the reports human-readable labels:
[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 mcp add cloudarmor -- cloudarmor-mcp
with the environment variables above in the server's env.
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)
Reading the report
- Enforced DENY by rule — your normal blocking volume. Sudden shifts in the mix are worth a look.
- Home-region DENY — requests from your own country/region that were blocked. Legitimate users and legitimate crawlers being denied show up here; scanner traffic that happens to originate locally will too, so the
known_normal_prioritieslist keeps expected rules (e.g. an AutoDiscover block) out of the suspicious list. - Preview DENY — rules in dry-run. A preview rule that stays free of home-region hits over time is a candidate for promotion to enforce.
License
MIT