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 call answers .
MCP server for Google Cloud Armor WAF log patrol: deny summaries and false-positive checks
2026-11-15
ดาว
—
เครื่องมือ
—
อัปไทม์
—
daily_brief
what did we block, did we block anyone we shouldn't have, and are the preview rules ready to promote
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.
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.
7. Codex
codex mcp add cloudarmor -- cloudarmor-mcp
Pass the environment variables above with --env KEY=VALUE (before --).
Any other MCP client that launches stdio servers works the same way: give it
cloudarmor-mcp as the command and set the environment variables above in its
environment.
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)
Writes one JSON document to stdout with one record per DENY log entry of that
calendar day ([00:00, 24:00) in --tz, default UTC): the enforced and preview
policy verdicts (policy, priority, action, outcome, rule_ids), source IP,
region code and ASN as Cloud Armor logged them, method, host, path (query string
dropped — only its length is kept), status, User-Agent (200 chars) and backend.
--kind both (default) fetches entries where either policy says DENY in a single
query, so a request that matched a preview rule and was denied appears once with
both sections filled. --backend a,b overrides CLOUDARMOR_BACKEND_SERVICES.
This and traffic-export (below) are the only outputs of the package that contain per-request log data; it is
meant for an operator batch on the same host that aggregates the day itself. The
document ends with count, fetched, malformed and capped: when capped is
true the export stopped at --max-entries (default 200000; CLOUDARMOR_MAX_ENTRIES
does not apply) and is a prefix of the day, oldest first. Records are streamed, so
memory does not grow with the day, and pages are fetched at most one per 1.2 s to stay
under the Cloud Logging read quota (60 requests per minute), so a day with 200,000 entries
takes a few minutes. A day that has not ended yet is refused. Run it
some minutes after local midnight — Cloud Logging entries arrive with a delay — and
write to a temporary file first: on a query failure the exit code is 1 and stdout may
hold an unterminated document.
Same document layout and record fields as deny-export, but for every
load-balancer request of the day — allowed, denied and served from the CDN cache —
thinned by Cloud Logging's sample(insertId, RATE) (--sample, default 0.01).
The sample is a hash of each entry's insertId, so it is spread evenly over the day
and the same rate selects the same entries on every run; scale counts by
1 / sample to estimate the day — but not when capped is true: entries are read
oldest first, so a capped export covers only the early part of the day (lower
--sample or raise --max-entries instead). Each record adds cache_hit. When no
backend security policy evaluated a request (a CDN cache hit, for example) it has
enforced: null and no region code or ASN; use cache_hit, not enforced, to tell
cache hits apart.
The header carries sample instead of kind. Use it to see who visits — browsers,
crawlers, AI agents — which the DENY logs cannot show. The per-request caveats of
deny-export apply: the records include legitimate visitors' addresses.
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.