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/
| 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
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]
known_normal_priorities = 500, 600
5. Claude Code (plugin)
This repository doubles as a single-plugin marketplace, so Claude Code can install
the server for you:
/plugin marketplace add shigechika/cloudarmor-mcp
/plugin install cloudarmor-mcp@cloudarmor-mcp
The plugin launches uvx cloudarmor-mcp and reads the same environment variables
described in Environment variables above; export them
before starting Claude Code. GOOGLE_APPLICATION_CREDENTIALS still has to point at
a service-account key file that exists on your own machine β the plugin can't ship
or fetch that file for you, so this server can't be fully configured through the
plugin's own settings alone.
uvx must be on the PATH of the process that runs Claude Code β a login
shell usually has it, but a GUI-launched app may not; install
uv system-wide if the plugin fails to start.
6. Claude Code (manual)
claude mcp add cloudarmor -- cloudarmor-mcp
with the environment variables above in the server's env.
CLI
cloudarmor-mcp --version
cloudarmor-mcp --check
cloudarmor-mcp --brief
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_priorities list 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