gcp-abuse-scanner

Preventive GCP security scanner for crypto mining and Gemini API abuse vectors.

gcp-abuse-scanner is an open source CLI tool that scans Google Cloud Platform organizations and projects for security misconfigurations that can be exploited for:

• 🪙 Crypto mining — unauthorized compute resource abuse
• 🤖 Gemini API abuse — unauthorized or uncontrolled access to Generative AI APIs

The tool is read-only and preventive: it never modifies resources, never disables APIs, and never revokes permissions. It produces a prioritized remediation report so you know exactly what to fix and in what order.

Features

• 🔍 50 security checks across Compute, GKE, Cloud Run, IAM, Networking, API Keys, Vertex AI, Billing, and Org Policies
• 🏢 Organization-wide or per-project scanning
• 🔐 Service account authentication (impersonation recommended, key file supported)
• 📊 Multiple output formats: Console (rich), JSON, Markdown, HTML, SARIF 2.1.0
• ⚡ Concurrent collection with retry/backoff — handles large orgs with thousands of projects
• 🎯 Prioritized findings with CRITICAL / HIGH / MEDIUM / LOW severity
• 🚫 Allowlist support for known exceptions
• 🔌 Plugin architecture — add new checks without touching the core

Quickstart

Installation

# Recommended: pipx (isolated environment)
pipx install gcp-abuse-scanner

# Or pip
pip install gcp-abuse-scanner

# Or Docker
docker run --rm -v ~/.config/gcloud:/root/.config/gcloud \
  ghcr.io/ucloud-global/gcp-abuse-scanner:latest scan --org YOUR_ORG_ID

Authentication

Recommended: Service Account Impersonation

gcp-abuse-scanner scan --org 123456789012 \
  --impersonate-service-account scanner-sa@your-project.iam.gserviceaccount.com

Alternative: Service Account Key File

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json
gcp-abuse-scanner scan --org 123456789012

⚠️ Using key files is an anti-pattern. Prefer impersonation or Workload Identity Federation.

Basic Usage

# Scan entire organization
gcp-abuse-scanner scan --org 123456789012

# Scan specific projects
gcp-abuse-scanner scan --project my-project-1 --project my-project-2

# Output as JSON
gcp-abuse-scanner scan --org 123456789012 --format json --output report.json

# Output as Markdown
gcp-abuse-scanner scan --org 123456789012 --format markdown --output report.md

# Output as self-contained HTML report
gcp-abuse-scanner scan --org 123456789012 --format html --output report.html

# Output as SARIF 2.1.0 (GitHub Advanced Security, VS Code)
gcp-abuse-scanner scan --org 123456789012 --format sarif --output results.sarif

# All formats at once (auto-named files)
gcp-abuse-scanner scan --org 123456789012 --format all

# Scan only Gemini abuse vector
gcp-abuse-scanner scan --org 123456789012 --vector gemini_abuse

# Speed up re-runs with inventory cache (1h TTL)
gcp-abuse-scanner scan --org 123456789012 --cache

# List all available checks
gcp-abuse-scanner list-checks

# Dry run (resolve scope without scanning)
gcp-abuse-scanner scan --org 123456789012 --dry-run

If a scan stalls or collects nothing

The discovery-based collectors talk HTTP over requests with an explicit per-request timeout (default 30 s). httplib2 — the older default — takes its timeout when the client is built, so one stalled socket could hang an org scan indefinitely; if you hit a timeout, raise the limit instead of removing it:

# Longer timeout for a slow/large org (0 disables the limit entirely)
gcp-abuse-scanner scan --org 123456789012 --request-timeout 120

# Escape hatch: revert to the legacy httplib2 transport (or use GCP_ABUSE_SCANNER_TRANSPORT)
gcp-abuse-scanner scan --org 123456789012 --transport httplib2

A client that could not be built, an API that is not enabled and a failed collector are recorded in coverage (and in risk_assessment.coverage_gaps) — a scan never turns "could not read" into "no findings" silently.

Prerequisites — GCP APIs

The scanner calls GCP APIs to collect resource inventory. These APIs must be enabled before running a scan.

Quick setup (recommended)

# Clone the repo to get the script, then run:
bash scripts/enable_apis.sh \
  --org YOUR_ORG_ID \
  --scanner-project YOUR_SCANNER_PROJECT

# Dry-run first to preview changes:
bash scripts/enable_apis.sh \
  --org YOUR_ORG_ID \
  --scanner-project YOUR_SCANNER_PROJECT \
  --dry-run

Manual setup

In the scanner project (enable once):

gcloud services enable \
  cloudasset.googleapis.com \
  cloudbilling.googleapis.com \
  billingbudgets.googleapis.com \
  orgpolicy.googleapis.com \
  --project=YOUR_SCANNER_PROJECT

In each scanned project:

gcloud services enable \
  serviceusage.googleapis.com \
  iam.googleapis.com \
  compute.googleapis.com \
  container.googleapis.com \
  run.googleapis.com \
  aiplatform.googleapis.com \
  apikeys.googleapis.com \
  recommender.googleapis.com \
  --project=PROJECT_ID

What happens if an API is disabled? The scanner skips that resource type for that project — it does not fail the scan. Use --verbose to see which APIs were skipped. See docs/apis.md for the full dependency map.

Required IAM Roles

The service account running this tool needs the following read-only roles, assigned at the organization level (for org-wide scans) or project level:

See docs/iam-setup.md for step-by-step setup instructions and docs/apis.md for the complete API reference.

Security Checks

Crypto Mining Vector (27 checks)

Gemini API Abuse Vector (17 checks)

Common Checks (6 checks)

Risk level and coverage gate

Every report carries a risk_assessment object that translates the scan into the SOP risk score (1–4) and states whether the result can be approved without human review:

Because the scanner is read-only and fails open, it also records when it could not look: if API keys, IAM or network input was missing (API not enabled, 403, collector error, inaccessible project), coverage_complete and auto_approval_eligible go false and coverage_gaps[] names the gap. An incomplete scan is never approved automatically — "no findings" from an API the scanner could not read is not a pass.

jq '.risk_assessment | {level, label, auto_approval_eligible, blockers: .auto_approval_blockers}' report.json

posture_score (0–100) is not the decision metric. It is normalized by project count and floors at 0 — one CRITICAL already reports 0.0 on a single-project scan, so it saturates and cannot distinguish "a bit off" from "very bad". Use risk_assessment.level to decide and executive_summary.penalty_points (raw severity sum, scope-independent) to compare two scans. Details and the arithmetic: docs/risk-model.md.

Full rule, decision table and the SOP-requirement mapping: docs/risk-model.md.

Report Format

Each finding includes:

• Severity: CRITICAL / HIGH / MEDIUM / LOW
• Priority rank: Global ordering for the remediation plan
• Evidence: Exact resource details that triggered the finding
• Impact: What an attacker can do with this misconfiguration
• Remediation: Step-by-step fix with gcloud commands, Terraform reference, and effort estimate

Example finding (JSON):

{
  "check_id": "GEM-002",
  "title": "API key has no application restrictions",
  "severity": "CRITICAL",
  "priority_rank": 1,
  "resource": {"project_id": "my-project", "resource_id": "..."},
  "remediation": {
    "summary": "Add HTTP referrer or IP restrictions to the key.",
    "effort": "LOW",
    "gcloud_commands": ["gcloud services api-keys update KEY_UID --allowed-referrers=..."]
  }
}

Configuration

Create a config.yaml to customize behavior:

# See examples/config.example.yaml for full reference
allowlist:
  - check_id: CM-001
    project_id: my-legacy-project
    reason: "External IP required for on-prem VPN — reviewed 2024-01-15"

Contributing

See CONTRIBUTING.md for how to add new checks, collectors, and reporters.

License

Apache 2.0 — see LICENSE.

Disclaimer: This tool is read-only and preventive. It does not guarantee detection of all security issues. Always combine with other security controls and monitoring.