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_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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cloudarmor_mcp-0.3.1.tar.gz (14.3 kB view details)

Uploaded Aug 11, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

cloudarmor_mcp-0.3.1-py3-none-any.whl (12.4 kB view details)

Uploaded Aug 11, 2026 Python 3

File details

Details for the file cloudarmor_mcp-0.3.1.tar.gz.

File metadata

Download URL: cloudarmor_mcp-0.3.1.tar.gz
Upload date: Aug 11, 2026
Size: 14.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for cloudarmor_mcp-0.3.1.tar.gz
Algorithm	Hash digest
SHA256	`278c9e07998eaf839d982895187377cdae831193521b99c088a47bd83e7233d1`
MD5	`4e6d1a4da1aba6ae1cb82bf1a47ce645`
BLAKE2b-256	`679089d34ec2fc66e25d67a15ab83e006ff54b7a3b526664e3acf9799d7c9a52`

See more details on using hashes here.

Provenance

The following attestation bundles were made for cloudarmor_mcp-0.3.1.tar.gz:

Publisher: release.yml on shigechika/cloudarmor-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: cloudarmor_mcp-0.3.1.tar.gz
- Subject digest: 278c9e07998eaf839d982895187377cdae831193521b99c088a47bd83e7233d1
- Sigstore transparency entry: 2418449742
- Sigstore integration time: Aug 11, 2026
Source repository:
- Permalink: shigechika/cloudarmor-mcp@b2baa50ec04c5907cd8482a78c02adc8eab5d35d
- Branch / Tag: refs/tags/v0.3.1
- Owner: https://github.com/shigechika
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@b2baa50ec04c5907cd8482a78c02adc8eab5d35d
- Trigger Event: release