Skip to main content
Glama

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.

Related MCP server: gke-cred-audit

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 (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.

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)

Exporting one day of DENY entries (batch)

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

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.

Exporting a sampled day of all requests (batch)

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

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.

License

MIT

Available Tools

5 tools
daily_briefB

Morning patrol summary: enforced DENYs by rule, home-region

false-positive check, and preview DENYs, in one call.

Inputs: since_hours. Returns: result

enforce_deniesD

Enforced DENY counts per Cloud Armor rule priority over the window.

Inputs: since_hours. Returns: result

health_checkA

Service health: version, config presence and a minimal API probe.

Returns a fixed shape (status/service/version + backend fields) so a monitoring caller never has to branch on missing keys. status is "healthy" when the config loads and a 1-entry probe query succeeds, "degraded" when config loads but the probe fails, "error" when the config itself is unusable.

Inputs: no named parameters.

home_region_deniesA

Enforced DENYs whose source IP geolocates to the home region.

This is the false-positive lens: home-region users being denied on a priority that is not marked known-normal deserves review. Requires CLOUDARMOR_HOME_REGION.

Inputs: since_hours. Returns: result

preview_deniesA

Preview (dry-run) DENY counts per rule priority over the window.

A preview rule that stays free of false positives is a candidate for promotion to enforce.

Inputs: since_hours. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    health_check is clearly distinct. enforce_denies vs preview_denies are differentiated by mode. home_region_denies is a specialized subset of enforced denies, which could be confused with enforce_denies, but the description clarifies its specific lens. daily_brief aggregates the others, but its purpose as a combined summary is evident from the description.

    Naming Consistency3/5

    Tool names mix conventions: verb_noun (enforce_denies, preview_denies), noun_verb (health_check), noun_noun (home_region_denies), and adjective_noun (daily_brief). While all are snake_case, the inconsistent verb/noun order and variable parts of speech make naming less predictable.

    Tool Count5/5

    5 tools is an appropriate scope for a specialized Cloud Armor deny analytics server. The count is neither too sparse to cover the core workflow nor bloated with redundant functionality, and each tool serves a distinct purpose within the defined domain.

    Completeness3/5

    The tools cover deny counts (enforced and preview), home-region analysis, and a summary brief, which addresses the primary monitoring workflow. However, there are notable gaps: no way to list or retrieve rule details to map priorities to rule names, and no allow-count or total-traffic metrics. These omissions could require agents to work around the lack of context when analyzing denies.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Defensive credential-exposure auditor for GKE that inventories workload identity, service account tokens, and RBAC posture, exposing findings via an MCP server at /mcp.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for AI agent security guardrails. Provides input validation, prompt injection detection, PII redaction, output filtering, policy enforcement, rate limiting, and comprehensive audit logging.
      72 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enterprise MCP server for Google SecOps (Chronicle) SIEM/SOAR, enabling alert triage, UDM telemetry search, YARA-L detection rule management, log ingestion, and parser administration via Streamable HTTP.
      -