cloudarmor-mcp 0.1.0__tar.gz

cloudarmor_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIKAWA Shigechika
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cloudarmor_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: cloudarmor-mcp
+Version: 0.1.0
+Summary: MCP server for Google Cloud Armor WAF log patrol — deny summaries, false-positive checks, preview rules
+Author: AIKAWA Shigechika
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shigechika/cloudarmor-mcp
+Project-URL: Repository, https://github.com/shigechika/cloudarmor-mcp
+Project-URL: Issues, https://github.com/shigechika/cloudarmor-mcp/issues
+Keywords: cloud-armor,waf,gcp,mcp,model-context-protocol,security,monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-cloud-logging<4,>=3
+Requires-Dist: mcp<2,>=1.2
+Dynamic: license-file
+
+# cloudarmor-mcp
+
+MCP server for [Google Cloud Armor](https://cloud.google.com/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*.
+
+## 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.
+
+```bash
+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
+
+```bash
+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) |
+
+### 4. Optional rules INI
+
+Keep your rule numbering out of prompts and give the reports human-readable labels:
+
+```ini
+[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
+
+```bash
+claude mcp add cloudarmor -- cloudarmor-mcp
+```
+
+with the environment variables above in the server's env.
+
+## CLI
+
+```bash
+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

cloudarmor_mcp-0.1.0/README.md

@@ -0,0 +1,91 @@
+# cloudarmor-mcp
+
+MCP server for [Google Cloud Armor](https://cloud.google.com/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*.
+
+## 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.
+
+```bash
+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
+
+```bash
+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) |
+
+### 4. Optional rules INI
+
+Keep your rule numbering out of prompts and give the reports human-readable labels:
+
+```ini
+[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
+
+```bash
+claude mcp add cloudarmor -- cloudarmor-mcp
+```
+
+with the environment variables above in the server's env.
+
+## CLI
+
+```bash
+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

cloudarmor_mcp-0.1.0/cloudarmor_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""cloudarmor-mcp — Google Cloud Armor WAF log patrol MCP Server."""
+
+__version__ = "0.1.0"  # x-release-please-version

cloudarmor_mcp-0.1.0/cloudarmor_mcp/__main__.py

@@ -0,0 +1,72 @@
+"""Entry point for cloudarmor-mcp."""
+
+import argparse
+import asyncio
+import os
+import sys
+
+from cloudarmor_mcp import __version__
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Google Cloud Armor WAF log patrol MCP Server",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Required environment variables:
+  CLOUDARMOR_PROJECT              GCP project ID that receives the LB logs
+  GOOGLE_APPLICATION_CREDENTIALS  Service-account key (roles/logging.viewer)
+
+Optional environment variables:
+  CLOUDARMOR_BACKEND_SERVICES  Comma-separated backend service names to filter
+  CLOUDARMOR_HOME_REGION       ISO region code treated as home (e.g. JP)
+  CLOUDARMOR_RULES_INI         Rule-priority labels / known-normal priorities
+""",
+    )
+    parser.add_argument("--version", action="store_true", help="Print version and exit")
+    parser.add_argument("--check", action="store_true", help="Verify config and API access, then exit")
+    parser.add_argument(
+        "--brief",
+        action="store_true",
+        help="Print the daily_brief to stdout and exit (handy for cron / smoke tests)",
+    )
+    args = parser.parse_args()
+
+    if args.version:
+        print(f"cloudarmor-mcp {__version__}")
+        sys.exit(0)
+
+    if not os.environ.get("CLOUDARMOR_PROJECT"):
+        print("Error: missing environment variable: CLOUDARMOR_PROJECT", file=sys.stderr)
+        sys.exit(1)
+
+    if args.check:
+        from cloudarmor_mcp.server import health_check
+
+        result = health_check()
+        print(f"{result['status']} — {result['service']} {result['version']} project={result['project']}")
+        if result["probe"] != "ok":
+            print(f"probe: {result['probe']}", file=sys.stderr)
+        sys.exit(0 if result["status"] == "healthy" else 2)
+
+    if args.brief:
+        from cloudarmor_mcp.server import DEFAULT_SINCE_HOURS, _daily_brief_text
+
+        text, had_error = _daily_brief_text(DEFAULT_SINCE_HOURS)
+        print(text)
+        sys.exit(1 if had_error else 0)
+
+    from cloudarmor_mcp.server import mcp
+
+    try:
+        mcp.run()
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        # anyio's teardown on SIGINT dumps a 20-80 line traceback. What it
+        # raises out of mcp.run() is Python-version-dependent: a bare
+        # KeyboardInterrupt on 3.12/3.13, but asyncio.CancelledError on 3.10.
+        # Catch both and exit clean like the sibling fleet MCP servers.
+        os._exit(0)
+
+
+if __name__ == "__main__":
+    main()

cloudarmor_mcp-0.1.0/cloudarmor_mcp/client.py

@@ -0,0 +1,150 @@
+"""Cloud Logging queries for Cloud Armor (http_load_balancer) log entries.
+
+The Google client library is imported lazily so unit tests can exercise
+filter building and aggregation without the dependency installed or any
+network access.
+"""
+
+import os
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+
+
+class CloudArmorError(Exception):
+    """Raised for configuration or Cloud Logging API errors."""
+
+
+@dataclass
+class Config:
+    """Runtime configuration resolved from environment variables."""
+
+    project: str
+    backend_services: list[str] = field(default_factory=list)
+    home_region: str | None = None
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        project = os.environ.get("CLOUDARMOR_PROJECT", "")
+        if not project:
+            raise CloudArmorError("CLOUDARMOR_PROJECT is not set")
+        backends = [b.strip() for b in os.environ.get("CLOUDARMOR_BACKEND_SERVICES", "").split(",") if b.strip()]
+        region = os.environ.get("CLOUDARMOR_HOME_REGION", "").strip() or None
+        return cls(project=project, backend_services=backends, home_region=region)
+
+
+def _quote(value: str) -> str:
+    """Quote a value for the Cloud Logging filter language.
+
+    Values come from the operator's own environment, not from untrusted
+    input, but quoting keeps hyphens/dots in service names unambiguous.
+    """
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def start_time(since_hours: float, now: datetime | None = None) -> str:
+    """RFC3339 UTC timestamp for the start of the query window."""
+    now = now or datetime.now(timezone.utc)
+    start = now - timedelta(hours=since_hours)
+    return start.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def build_filter(
+    kind: str,
+    since_hours: float,
+    backend_services: list[str],
+    region_code: str | None = None,
+    now: datetime | None = None,
+) -> str:
+    """Build a Cloud Logging filter for Cloud Armor DENY entries.
+
+    kind: "enforced" (enforcedSecurityPolicy.outcome=DENY) or
+          "preview" (previewSecurityPolicy.configuredAction=DENY).
+    region_code: optionally restrict to requests whose source IP geolocates
+          to this ISO region code (e.g. "JP") — the false-positive lens.
+    """
+    parts = ['resource.type="http_load_balancer"']
+    if kind == "enforced":
+        parts.append('jsonPayload.enforcedSecurityPolicy.outcome="DENY"')
+    elif kind == "preview":
+        parts.append('jsonPayload.previewSecurityPolicy.configuredAction="DENY"')
+    else:
+        raise CloudArmorError(f"unknown filter kind: {kind!r}")
+    if region_code:
+        parts.append("jsonPayload.securityPolicyRequestData.remoteIpInfo.regionCode=" + _quote(region_code))
+    if backend_services:
+        if len(backend_services) == 1:
+            parts.append(f"resource.labels.backend_service_name={_quote(backend_services[0])}")
+        else:
+            joined = " OR ".join(_quote(b) for b in backend_services)
+            parts.append(f"resource.labels.backend_service_name=({joined})")
+    parts.append(f'timestamp >= "{start_time(since_hours, now)}"')
+    return " ".join(parts)
+
+
+@dataclass
+class DenyEntry:
+    """The fields of one DENY log entry that the tools report on."""
+
+    priority: str
+    remote_ip: str
+    request_url: str
+    outcome_kind: str  # "enforced" or "preview"
+
+
+def _normalize_priority(raw) -> str:
+    """Rule priorities arrive as JSON numbers (floats) from Cloud Logging.
+
+    "101.0" would break label lookup and known-normal matching against the
+    integer strings operators naturally write in the rules INI, so integral
+    floats are folded back to their integer form.
+    """
+    if isinstance(raw, float) and raw.is_integer():
+        return str(int(raw))
+    return str(raw)
+
+
+def _entry_to_deny(entry, kind: str) -> DenyEntry:
+    payload = entry.payload if isinstance(entry.payload, dict) else {}
+    policy_key = "enforcedSecurityPolicy" if kind == "enforced" else "previewSecurityPolicy"
+    priority = _normalize_priority(payload.get(policy_key, {}).get("priority", "?"))
+    http = entry.http_request or {}
+    return DenyEntry(
+        priority=priority,
+        remote_ip=str(http.get("remoteIp", "?")),
+        request_url=str(http.get("requestUrl", "?")),
+        outcome_kind=kind,
+    )
+
+
+class LogClient:
+    """Thin wrapper over google-cloud-logging list_entries."""
+
+    def __init__(self, project: str):
+        try:
+            from google.cloud import logging as gcl
+        except ImportError as e:  # pragma: no cover - import guard
+            raise CloudArmorError("google-cloud-logging is not installed (pip install cloudarmor-mcp)") from e
+        try:
+            self._client = gcl.Client(project=project)
+        except Exception as e:
+            raise CloudArmorError(f"failed to create Cloud Logging client: {e}") from e
+        self._descending = gcl.DESCENDING
+        self.project = project
+
+    def deny_entries(self, filter_str: str, kind: str, max_entries: int) -> Iterator[DenyEntry]:
+        """Yield up to max_entries DenyEntry rows for the filter, newest first."""
+        try:
+            it = self._client.list_entries(
+                filter_=filter_str,
+                order_by=self._descending,
+                page_size=min(max_entries, 1000),
+                max_results=max_entries,
+            )
+            for entry in it:
+                yield _entry_to_deny(entry, kind)
+        except CloudArmorError:
+            raise
+        except Exception as e:
+            raise CloudArmorError(f"Cloud Logging query failed: {e}") from e

cloudarmor_mcp-0.1.0/cloudarmor_mcp/rules.py

@@ -0,0 +1,60 @@
+"""Optional site-specific rule annotations for daily_brief.
+
+Loaded from an INI file pointed to by ``CLOUDARMOR_RULES_INI``. This keeps
+organization-specific Cloud Armor rule numbering out of the codebase so the
+server stays generic and publishable. When unset or missing, priorities are
+reported without labels and no home-region priority is treated as known-normal.
+
+Example::
+
+    [rules]
+    ; label shown next to each rule priority in reports
+    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
+"""
+
+import configparser
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Rules:
+    labels: dict[str, str] = field(default_factory=dict)
+    known_normal: set[str] = field(default_factory=set)
+
+    def label(self, priority: str) -> str:
+        name = self.labels.get(priority)
+        return f" ({name})" if name else ""
+
+    def is_known_normal(self, priority: str) -> bool:
+        return priority in self.known_normal
+
+
+def load_rules(path: str | None = None) -> Rules:
+    """Load rule annotations (env ``CLOUDARMOR_RULES_INI`` by default).
+
+    Returns empty Rules when no path is configured or the file is absent.
+    Raises ``configparser.Error``, ``OSError`` or ``UnicodeDecodeError`` when
+    the path exists but cannot be parsed — callers that must not crash on a
+    bad config should catch those.
+    """
+    path = path or os.environ.get("CLOUDARMOR_RULES_INI")
+    if not path or not os.path.isfile(path):
+        return Rules()
+    parser = configparser.ConfigParser()
+    with open(path, encoding="utf-8") as f:
+        parser.read_file(f)
+    labels: dict[str, str] = {}
+    if parser.has_section("rules"):
+        labels = {k.strip(): v.strip() for k, v in parser.items("rules")}
+    known: set[str] = set()
+    if parser.has_section("home"):
+        raw = parser.get("home", "known_normal_priorities", fallback="")
+        known = {p.strip() for p in raw.split(",") if p.strip()}
+    return Rules(labels=labels, known_normal=known)

cloudarmor_mcp-0.1.0/cloudarmor_mcp/server.py

@@ -0,0 +1,240 @@
+"""Cloud Armor WAF patrol MCP Server — tools."""
+
+import configparser
+import os
+from collections import Counter
+
+from mcp.server.fastmcp import FastMCP
+
+from cloudarmor_mcp.client import CloudArmorError, Config, LogClient, build_filter
+from cloudarmor_mcp.rules import Rules, load_rules
+
+mcp = FastMCP("cloudarmor-mcp")
+
+# Hard cap on entries fetched per query (CLOUDARMOR_MAX_ENTRIES overrides).
+# When the cap is hit the report says ">= N (capped)" instead of pretending
+# the count is exact — silent truncation must never read as "covered
+# everything".
+DEFAULT_MAX_ENTRIES = 2000
+
+
+def _max_entries() -> int:
+    try:
+        return max(1, int(os.environ.get("CLOUDARMOR_MAX_ENTRIES", DEFAULT_MAX_ENTRIES)))
+    except ValueError:
+        return DEFAULT_MAX_ENTRIES
+
+
+# How many home-region DENY detail lines to show before folding to a count.
+HOME_DETAIL_LIMIT = 40
+
+# Default patrol window (hours). 26 h keeps a daily patrol overlapping
+# yesterday's run instead of leaving a gap when start times drift.
+DEFAULT_SINCE_HOURS = 26.0
+
+# Cached client: a stdio server is long-lived and single-user, so build the
+# authenticated client once and reuse its connection pool across calls.
+_CLIENT: LogClient | None = None
+
+
+def _client() -> LogClient:
+    global _CLIENT
+    if _CLIENT is None:
+        _CLIENT = LogClient(Config.from_env().project)
+    return _CLIENT
+
+
+def reset_client() -> None:
+    """Drop the cached client so the next call rebuilds it."""
+    global _CLIENT
+    _CLIENT = None
+
+
+def _load_rules_safe() -> tuple[Rules, str | None]:
+    try:
+        return load_rules(), None
+    except (configparser.Error, OSError, UnicodeDecodeError) as e:
+        return Rules(), f"rules INI could not be read: {e}"
+
+
+def _count_fragment(shown: int, cap: int) -> str:
+    return f">= {shown} (capped at {cap})" if shown >= cap else str(shown)
+
+
+def _priority_table(counts: Counter, rules: Rules) -> list[str]:
+    lines = []
+    for priority, n in counts.most_common():
+        lines.append(f"  rule {priority}{rules.label(priority)}: {n}")
+    return lines
+
+
+def _collect(kind: str, since_hours: float, region_code: str | None = None) -> tuple[list, int]:
+    """Fetch entries for the window; returns (entries, cap) so reports can flag capping."""
+    cfg = Config.from_env()
+    cap = _max_entries()
+    filter_str = build_filter(kind, since_hours, cfg.backend_services, region_code)
+    return list(_client().deny_entries(filter_str, kind, cap)), cap
+
+
+@mcp.tool()
+def health_check() -> dict:
+    """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.
+    """
+    from cloudarmor_mcp import __version__
+
+    result = {
+        "status": "error",
+        "service": "cloudarmor-mcp",
+        "version": __version__,
+        "project": None,
+        "backend_services": [],
+        "home_region": None,
+        "rules_ini": False,
+        "probe": None,
+    }
+    try:
+        cfg = Config.from_env()
+    except CloudArmorError as e:
+        result["probe"] = str(e)
+        return result
+    result["project"] = cfg.project
+    result["backend_services"] = cfg.backend_services
+    result["home_region"] = cfg.home_region
+    rules, rules_err = _load_rules_safe()
+    result["rules_ini"] = bool(rules.labels or rules.known_normal)
+    try:
+        filter_str = build_filter("enforced", 0.1, cfg.backend_services)
+        list(_client().deny_entries(filter_str, "enforced", 1))
+        result["status"] = "healthy"
+        result["probe"] = "ok"
+    except CloudArmorError as e:
+        result["status"] = "degraded"
+        result["probe"] = str(e)
+    if rules_err:
+        result["probe"] = f"{result['probe']}; {rules_err}"
+    return result
+
+
+@mcp.tool()
+def enforce_denies(since_hours: float = DEFAULT_SINCE_HOURS) -> str:
+    """Enforced DENY counts per Cloud Armor rule priority over the window."""
+    rules, rules_err = _load_rules_safe()
+    entries, cap = _collect("enforced", since_hours)
+    counts = Counter(e.priority for e in entries)
+    lines = [f"Enforced DENY, last {since_hours:g}h: {_count_fragment(len(entries), cap)}"]
+    lines += _priority_table(counts, rules)
+    if rules_err:
+        lines.append(f"  [warn] {rules_err}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def preview_denies(since_hours: float = DEFAULT_SINCE_HOURS) -> str:
+    """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.
+    """
+    rules, rules_err = _load_rules_safe()
+    entries, cap = _collect("preview", since_hours)
+    counts = Counter(e.priority for e in entries)
+    lines = [f"Preview DENY, last {since_hours:g}h: {_count_fragment(len(entries), cap)}"]
+    lines += _priority_table(counts, rules)
+    if rules_err:
+        lines.append(f"  [warn] {rules_err}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def home_region_denies(since_hours: float = DEFAULT_SINCE_HOURS) -> str:
+    """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.
+    """
+    cfg = Config.from_env()
+    if not cfg.home_region:
+        return "CLOUDARMOR_HOME_REGION is not set — home-region check skipped."
+    rules, rules_err = _load_rules_safe()
+    entries, cap = _collect("enforced", since_hours, region_code=cfg.home_region)
+    lines = [
+        f"Enforced DENY from region {cfg.home_region}, last {since_hours:g}h: {_count_fragment(len(entries), cap)}"
+    ]
+    suspicious = [e for e in entries if not rules.is_known_normal(e.priority)]
+    normal = len(entries) - len(suspicious)
+    if normal:
+        lines.append(f"  known-normal priorities: {normal} (suppressed)")
+    for e in suspicious[:HOME_DETAIL_LIMIT]:
+        lines.append(f"  rule {e.priority}{rules.label(e.priority)}  {e.remote_ip}  {e.request_url}")
+    if len(suspicious) > HOME_DETAIL_LIMIT:
+        lines.append(f"  ... and {len(suspicious) - HOME_DETAIL_LIMIT} more")
+    if not suspicious:
+        lines.append("  no suspicious home-region denies — WAF looks clean")
+    if rules_err:
+        lines.append(f"  [warn] {rules_err}")
+    return "\n".join(lines)
+
+
+def _daily_brief_text(since_hours: float) -> tuple[str, bool]:
+    """Build the brief; returns (text, had_error)."""
+    cfg = Config.from_env()
+    rules, rules_err = _load_rules_safe()
+    sections: list[str] = [f"# Cloud Armor brief — project {cfg.project}, last {since_hours:g}h"]
+    had_error = False
+
+    try:
+        enforced, cap = _collect("enforced", since_hours)
+        counts = Counter(e.priority for e in enforced)
+        sections.append(f"## Enforced DENY: {_count_fragment(len(enforced), cap)}")
+        sections += _priority_table(counts, rules)
+    except CloudArmorError as e:
+        sections.append(f"## Enforced DENY: query failed — {e}")
+        had_error = True
+
+    if cfg.home_region:
+        try:
+            home, cap = _collect("enforced", since_hours, region_code=cfg.home_region)
+            suspicious = [e for e in home if not rules.is_known_normal(e.priority)]
+            sections.append(
+                f"## {cfg.home_region}-sourced DENY (false-positive lens): "
+                f"{_count_fragment(len(home), cap)}, suspicious {len(suspicious)}"
+            )
+            for e in suspicious[:HOME_DETAIL_LIMIT]:
+                sections.append(f"  rule {e.priority}{rules.label(e.priority)}  {e.remote_ip}  {e.request_url}")
+            if len(suspicious) > HOME_DETAIL_LIMIT:
+                sections.append(f"  ... and {len(suspicious) - HOME_DETAIL_LIMIT} more")
+            if not suspicious:
+                sections.append("  none outside known-normal priorities")
+        except CloudArmorError as e:
+            sections.append(f"## {cfg.home_region}-sourced DENY: query failed — {e}")
+            had_error = True
+
+    try:
+        preview, cap = _collect("preview", since_hours)
+        counts = Counter(e.priority for e in preview)
+        sections.append(f"## Preview DENY: {_count_fragment(len(preview), cap)}")
+        sections += _priority_table(counts, rules)
+    except CloudArmorError as e:
+        sections.append(f"## Preview DENY: query failed — {e}")
+        had_error = True
+
+    if rules_err:
+        sections.append(f"[warn] {rules_err}")
+    return "\n".join(sections), had_error
+
+
+@mcp.tool()
+def daily_brief(since_hours: float = DEFAULT_SINCE_HOURS) -> str:
+    """Morning patrol summary: enforced DENYs by rule, home-region
+
+    false-positive check, and preview DENYs, in one call.
+    """
+    text, _ = _daily_brief_text(since_hours)
+    return text

cloudarmor_mcp-0.1.0/cloudarmor_mcp.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: cloudarmor-mcp
+Version: 0.1.0
+Summary: MCP server for Google Cloud Armor WAF log patrol — deny summaries, false-positive checks, preview rules
+Author: AIKAWA Shigechika
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shigechika/cloudarmor-mcp
+Project-URL: Repository, https://github.com/shigechika/cloudarmor-mcp
+Project-URL: Issues, https://github.com/shigechika/cloudarmor-mcp/issues
+Keywords: cloud-armor,waf,gcp,mcp,model-context-protocol,security,monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-cloud-logging<4,>=3
+Requires-Dist: mcp<2,>=1.2
+Dynamic: license-file
+
+# cloudarmor-mcp
+
+MCP server for [Google Cloud Armor](https://cloud.google.com/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*.
+
+## 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.
+
+```bash
+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
+
+```bash
+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) |
+
+### 4. Optional rules INI
+
+Keep your rule numbering out of prompts and give the reports human-readable labels:
+
+```ini
+[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
+
+```bash
+claude mcp add cloudarmor -- cloudarmor-mcp
+```
+
+with the environment variables above in the server's env.
+
+## CLI
+
+```bash
+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

cloudarmor_mcp-0.1.0/cloudarmor_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+cloudarmor_mcp/__init__.py
+cloudarmor_mcp/__main__.py
+cloudarmor_mcp/client.py
+cloudarmor_mcp/rules.py
+cloudarmor_mcp/server.py
+cloudarmor_mcp.egg-info/PKG-INFO
+cloudarmor_mcp.egg-info/SOURCES.txt
+cloudarmor_mcp.egg-info/dependency_links.txt
+cloudarmor_mcp.egg-info/entry_points.txt
+cloudarmor_mcp.egg-info/requires.txt
+cloudarmor_mcp.egg-info/top_level.txt
+tests/test_client.py
+tests/test_server.py

cloudarmor_mcp-0.1.0/cloudarmor_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cloudarmor_mcp-0.1.0/cloudarmor_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cloudarmor-mcp = cloudarmor_mcp.__main__:main

cloudarmor_mcp-0.1.0/cloudarmor_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+google-cloud-logging<4,>=3
+mcp<2,>=1.2

cloudarmor_mcp-0.1.0/cloudarmor_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+cloudarmor_mcp

cloudarmor_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cloudarmor-mcp"
+dynamic = ["version"]
+description = "MCP server for Google Cloud Armor WAF log patrol — deny summaries, false-positive checks, preview rules"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "AIKAWA Shigechika"},
+]
+keywords = ["cloud-armor", "waf", "gcp", "mcp", "model-context-protocol", "security", "monitoring"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Topic :: Security",
+]
+dependencies = [
+    "google-cloud-logging>=3,<4",
+    "mcp>=1.2,<2",
+]
+
+[project.scripts]
+cloudarmor-mcp = "cloudarmor_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/shigechika/cloudarmor-mcp"
+Repository = "https://github.com/shigechika/cloudarmor-mcp"
+Issues = "https://github.com/shigechika/cloudarmor-mcp/issues"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+]
+
+[tool.setuptools]
+packages = ["cloudarmor_mcp"]
+
+[tool.setuptools.dynamic]
+version = {attr = "cloudarmor_mcp.__version__"}
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cloudarmor_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cloudarmor_mcp-0.1.0/tests/test_client.py

@@ -0,0 +1,95 @@
+"""Tests for filter building and configuration."""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from cloudarmor_mcp.client import CloudArmorError, Config, build_filter, start_time
+
+NOW = datetime(2026, 8, 6, 12, 0, 0, tzinfo=timezone.utc)
+
+
+def test_start_time_subtracts_window():
+    assert start_time(24, now=NOW) == "2026-08-05T12:00:00Z"
+
+
+def test_build_filter_enforced_single_backend():
+    f = build_filter("enforced", 26, ["web-backend"], now=NOW)
+    assert 'resource.type="http_load_balancer"' in f
+    assert 'jsonPayload.enforcedSecurityPolicy.outcome="DENY"' in f
+    assert 'resource.labels.backend_service_name="web-backend"' in f
+    assert 'timestamp >= "2026-08-05T10:00:00Z"' in f
+    assert "previewSecurityPolicy" not in f
+
+
+def test_build_filter_preview():
+    f = build_filter("preview", 1, [], now=NOW)
+    assert 'jsonPayload.previewSecurityPolicy.configuredAction="DENY"' in f
+    assert "enforcedSecurityPolicy" not in f
+    assert "backend_service_name" not in f
+
+
+def test_build_filter_region_code():
+    f = build_filter("enforced", 1, [], region_code="JP", now=NOW)
+    assert 'jsonPayload.securityPolicyRequestData.remoteIpInfo.regionCode="JP"' in f
+
+
+def test_build_filter_multiple_backends_or_group():
+    f = build_filter("enforced", 1, ["b-one", "b-two"], now=NOW)
+    assert 'resource.labels.backend_service_name=("b-one" OR "b-two")' in f
+
+
+def test_build_filter_unknown_kind():
+    with pytest.raises(CloudArmorError):
+        build_filter("nope", 1, [])
+
+
+def test_config_from_env_requires_project(monkeypatch):
+    monkeypatch.delenv("CLOUDARMOR_PROJECT", raising=False)
+    with pytest.raises(CloudArmorError):
+        Config.from_env()
+
+
+def test_config_from_env_parses_lists(monkeypatch):
+    monkeypatch.setenv("CLOUDARMOR_PROJECT", "proj")
+    monkeypatch.setenv("CLOUDARMOR_BACKEND_SERVICES", "a, b ,")
+    monkeypatch.setenv("CLOUDARMOR_HOME_REGION", "JP")
+    cfg = Config.from_env()
+    assert cfg.project == "proj"
+    assert cfg.backend_services == ["a", "b"]
+    assert cfg.home_region == "JP"
+
+
+def test_config_from_env_defaults(monkeypatch):
+    monkeypatch.setenv("CLOUDARMOR_PROJECT", "proj")
+    monkeypatch.delenv("CLOUDARMOR_BACKEND_SERVICES", raising=False)
+    monkeypatch.delenv("CLOUDARMOR_HOME_REGION", raising=False)
+    cfg = Config.from_env()
+    assert cfg.backend_services == []
+    assert cfg.home_region is None
+
+
+class _FakeEntry:
+    def __init__(self, payload, http_request=None):
+        self.payload = payload
+        self.http_request = http_request
+
+
+def test_entry_to_deny_normalizes_float_priority():
+    from cloudarmor_mcp.client import _entry_to_deny
+
+    entry = _FakeEntry(
+        {"enforcedSecurityPolicy": {"priority": 101.0}},
+        {"remoteIp": "203.0.113.9", "requestUrl": "https://example.org/"},
+    )
+    deny = _entry_to_deny(entry, "enforced")
+    assert deny.priority == "101"
+    assert deny.remote_ip == "203.0.113.9"
+
+
+def test_entry_to_deny_keeps_int_and_missing():
+    from cloudarmor_mcp.client import _entry_to_deny
+
+    assert _entry_to_deny(_FakeEntry({"enforcedSecurityPolicy": {"priority": 42}}), "enforced").priority == "42"
+    assert _entry_to_deny(_FakeEntry({}), "enforced").priority == "?"
+    assert _entry_to_deny(_FakeEntry(None, None), "preview").priority == "?"

cloudarmor_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,151 @@
+"""Tests for tool output shapes with a fake log client (no network)."""
+
+import pytest
+
+import cloudarmor_mcp.server as server
+from cloudarmor_mcp.client import DenyEntry
+
+
+class FakeClient:
+    """Returns canned entries; records the filters it was asked for."""
+
+    def __init__(self, entries_by_kind):
+        self.entries_by_kind = entries_by_kind
+        self.filters = []
+
+    def deny_entries(self, filter_str, kind, max_entries):
+        self.filters.append(filter_str)
+        yield from self.entries_by_kind.get(kind, [])[:max_entries]
+
+
+def _deny(priority, ip="203.0.113.1", url="https://example.org/x", kind="enforced"):
+    return DenyEntry(priority=priority, remote_ip=ip, request_url=url, outcome_kind=kind)
+
+
+@pytest.fixture
+def env(monkeypatch):
+    monkeypatch.setenv("CLOUDARMOR_PROJECT", "proj")
+    monkeypatch.setenv("CLOUDARMOR_BACKEND_SERVICES", "web-backend")
+    monkeypatch.setenv("CLOUDARMOR_HOME_REGION", "JP")
+    monkeypatch.delenv("CLOUDARMOR_RULES_INI", raising=False)
+    server.reset_client()
+    yield
+    server.reset_client()
+
+
+def _install(monkeypatch, fake):
+    monkeypatch.setattr(server, "_client", lambda: fake)
+
+
+def test_enforce_denies_aggregates_by_priority(env, monkeypatch):
+    fake = FakeClient({"enforced": [_deny("101"), _deny("101"), _deny("500")]})
+    _install(monkeypatch, fake)
+    out = server.enforce_denies(since_hours=24)
+    assert "Enforced DENY, last 24h: 3" in out
+    assert "rule 101: 2" in out
+    assert "rule 500: 1" in out
+
+
+def test_preview_denies_empty(env, monkeypatch):
+    fake = FakeClient({})
+    _install(monkeypatch, fake)
+    out = server.preview_denies(since_hours=24)
+    assert "Preview DENY, last 24h: 0" in out
+
+
+def test_home_region_denies_flags_suspicious(env, monkeypatch, tmp_path):
+    rules = tmp_path / "rules.ini"
+    rules.write_text("[rules]\n500 = AutoDiscover\n[home]\nknown_normal_priorities = 500\n")
+    monkeypatch.setenv("CLOUDARMOR_RULES_INI", str(rules))
+    fake = FakeClient({"enforced": [_deny("500"), _deny("500"), _deny("1002", ip="198.51.100.7")]})
+    _install(monkeypatch, fake)
+    out = server.home_region_denies(since_hours=24)
+    assert "known-normal priorities: 2 (suppressed)" in out
+    assert "rule 1002" in out
+    assert "198.51.100.7" in out
+    # region filter actually reached the query
+    assert any('regionCode="JP"' in f for f in fake.filters)
+
+
+def test_home_region_denies_without_region(env, monkeypatch):
+    monkeypatch.delenv("CLOUDARMOR_HOME_REGION")
+    fake = FakeClient({})
+    _install(monkeypatch, fake)
+    out = server.home_region_denies(since_hours=24)
+    assert "not set" in out
+
+
+def test_home_region_denies_all_normal(env, monkeypatch, tmp_path):
+    rules = tmp_path / "rules.ini"
+    rules.write_text("[home]\nknown_normal_priorities = 500\n")
+    monkeypatch.setenv("CLOUDARMOR_RULES_INI", str(rules))
+    fake = FakeClient({"enforced": [_deny("500")]})
+    _install(monkeypatch, fake)
+    out = server.home_region_denies(since_hours=24)
+    assert "no suspicious home-region denies" in out
+
+
+def test_daily_brief_contains_all_sections(env, monkeypatch):
+    fake = FakeClient(
+        {
+            "enforced": [_deny("101"), _deny("500")],
+            "preview": [_deny("1010", kind="preview")],
+        }
+    )
+    _install(monkeypatch, fake)
+    out = server.daily_brief(since_hours=26)
+    assert "# Cloud Armor brief — project proj, last 26h" in out
+    assert "## Enforced DENY: 2" in out
+    assert "## JP-sourced DENY" in out
+    assert "## Preview DENY: 1" in out
+
+
+def test_daily_brief_rule_labels(env, monkeypatch, tmp_path):
+    rules = tmp_path / "rules.ini"
+    rules.write_text("[rules]\n101 = deep-path crawler block\n")
+    monkeypatch.setenv("CLOUDARMOR_RULES_INI", str(rules))
+    fake = FakeClient({"enforced": [_deny("101")]})
+    _install(monkeypatch, fake)
+    out = server.daily_brief(since_hours=26)
+    assert "rule 101 (deep-path crawler block): 1" in out
+
+
+def test_capped_count_is_flagged(env, monkeypatch):
+    monkeypatch.setenv("CLOUDARMOR_MAX_ENTRIES", "5")
+    entries = [_deny("101") for _ in range(10)]
+    fake = FakeClient({"enforced": entries})
+    _install(monkeypatch, fake)
+    out = server.enforce_denies(since_hours=24)
+    assert ">= 5 (capped at 5)" in out
+
+
+def test_max_entries_env_invalid_falls_back(monkeypatch):
+    monkeypatch.setenv("CLOUDARMOR_MAX_ENTRIES", "not-a-number")
+    assert server._max_entries() == server.DEFAULT_MAX_ENTRIES
+
+
+def test_health_check_shape_without_project(monkeypatch):
+    monkeypatch.delenv("CLOUDARMOR_PROJECT", raising=False)
+    server.reset_client()
+    result = server.health_check()
+    assert result["status"] == "error"
+    assert result["service"] == "cloudarmor-mcp"
+    assert set(result) == {
+        "status",
+        "service",
+        "version",
+        "project",
+        "backend_services",
+        "home_region",
+        "rules_ini",
+        "probe",
+    }
+
+
+def test_health_check_healthy_with_fake(env, monkeypatch):
+    fake = FakeClient({"enforced": []})
+    _install(monkeypatch, fake)
+    result = server.health_check()
+    assert result["status"] == "healthy"
+    assert result["probe"] == "ok"
+    assert result["project"] == "proj"