gcp-cost-anomaly-scan

GCP Cost Anomaly Scan (READ-ONLY)

Overview

For every billing account the caller can see, determines whether any project has experienced an abnormal spend spike in the last LOOKBACK_DAYS days (default 60). Uses the gcp-finops MCP server when available; otherwise falls back to direct bq query against billing-export tables.

Related native feature (July 2026): Google's Early Anomalies (Preview) now does forward-looking, pre-invoice anomaly alerting with root-cause SKU attribution — but only for Gemini API, Agent Platform, Cloud Run, and Cloud Run functions, per project, in the console's Anomalies section. This skill remains the historical sweep across all services and billing accounts, and produces the anomalies.json later phases consume. When reporting, mention enabling Early Anomalies review as a complementary forward-looking control.

When to Use

• Triggered by the gcp-ironclad driver as Phase 1b.
• Or invoked standalone when you suspect past abuse you may have missed.

Inputs

• SESSION_DIR env var.
• LOOKBACK_DAYS env var (default 60).
• THRESHOLD_PCT env var (default 200 — daily spend must be ≥200% over the 7-day rolling average to flag).
• ACTIVE_HOURS env var (default 24 — used to mark anomalies as still-active).

Outputs

Writes ${SESSION_DIR}/anomalies.json matching output.schema.json.

Execution

Step A: Establish session dir + list billing accounts

SESSION_DIR="${SESSION_DIR:-/tmp/gcp-ironclad/standalone-$(date -u +%Y-%m-%dT%H-%M-%SZ)}"
mkdir -p "${SESSION_DIR}/raw"
gcloud billing accounts list --format=json > "${SESSION_DIR}/raw/billing-accounts.json"

Step B: For each billing account, determine export availability

For each account B:

1. First, try the gcp-finops MCP server (call its discover_billing_tables tool). If it returns a table for B, mark hasExport: true.
2. If MCP is unavailable, fall back to:

   bq ls --format=prettyjson "${QUOTA_PROJECT}:billing_export" 2>/dev/null \
     | jq -r '.[].tableReference.tableId' \
     | grep -E "gcp_billing_export_(resource_)?v1_${B//-/_}"
   

   where ${QUOTA_PROJECT} is the project that owns the billing-export dataset. If the user doesn't know it, default to gcloud config get-value project.
3. If nothing is found, mark hasExport: false and emit an info-class error: "no_billing_export".