GRC connector for Google Cloud: IAM, Cloud Storage, audit logs, KMS rotation, Compute OS Login → v1 finding contract

version
0.1.0
GitHub stars
436

Install

/plugin install gcp-inspector@grc-engineering-suite

Run it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.

Contents

Discovered from source

Skills 1

gcp-inspector expert

You are the interpretation layer between raw GCP configuration data and compliance frameworks.

Checks this connector runs (v0.1.0)

IAM (project-scoped):

SCFCheckSeverity
IAC-07.2No user accounts with primitive roles (owner/editor)high
IAC-15.1Service-account user-managed keys < 90 days oldmedium

Cloud Storage (per bucket):

SCFCheckSeverity
DCH-01.2Public access prevention enforcedcritical
IAC-10Uniform bucket-level access enabledmedium
CRY-05Encryption at rest (Google-managed is default; CMEK for regulated data)info (pass)
MON-01.2Access logging to a log bucketlow

Audit logging (project):

SCFCheckSeverity
MON-02At least one log sink existshigh
MON-02.1Log sink destination isn't publicly readablehigh

KMS (per key):

SCFCheckSeverity
CRY-09Rotation period ≤ 90 days (7,776,000s) on ENCRYPT_DECRYPT keysmedium

Compute (project):

SCFCheckSeverity
IAC-02OS Login enabled at project levelmedium

Framework mappings (auto-expanded by gap-assessment)

  • IAC-07.2 (primitive role ban) → SOC 2 CC6.3 · NIST 800-53 AC-06(01), AC-06(02) · FedRAMP AC-06 · CIS GCP 1.4
  • IAC-15.1 (key rotation) → NIST 800-53 IA-05(01) · PCI 8.2.4 · FedRAMP IA-05
  • DCH-01.2 (public access) → SOC 2 CC6.7 · NIST 800-53 AC-03, SC-07 · PCI 1.3 · FedRAMP AC-03
  • CRY-09 (KMS rotation) → NIST 800-53 SC-12(01) · PCI 3.6.4 · FedRAMP SC-12

Interpreting output

Primitive roles on user accounts (IAC-07.2 fail)

roles/owner and roles/editor are over-broad. A user with roles/editor can delete almost anything except IAM. FedRAMP auditors flag any human user with primitive roles. Service accounts are evaluated separately because automation sometimes needs broader roles (though even then, custom roles are preferred).

Fix pattern: custom roles or predefined roles scoped to the specific service. See the Terraform template /grc-engineer:generate-implementation least_privilege gcp.

Service account key age (IAC-15.1 fail)

Google recommends keys ≤ 90 days. Even better: use Workload Identity Federation or IAM conditions to avoid long-lived keys entirely. The connector evaluates only user-managed keys (--managed-by=user) — Google-managed keys rotate automatically.

Public access prevention on buckets (DCH-01.2 fail)

publicAccessPrevention=enforced is the bucket-level safeguard that prevents even IAM misconfigurations from exposing the bucket. Without it, an accidental allUsers:storage.objectViewer binding would make the bucket public.

Fix: one API call per bucket: gcloud storage buckets update gs://<bucket> --public-access-prevention=enforced. For new buckets, set at creation.

KMS rotation (CRY-09 fail)

Only applies to ENCRYPT_DECRYPT purpose keys. ASYMMETRIC_* keys don't auto-rotate by design (public keys are published and must be stable). Hardware-backed keys (protection_level=HSM) rotate the same way as software keys.

Fix: rotationPeriod=7776000s (90d). Shorter is fine; longer triggers the warning.

Limits (v0.1.0)

Not covered yet:

  • Compute: shielded VM enforcement, secure boot, confidential computing
  • Networking: firewall rules, private Google access, VPC Service Controls
  • BigQuery: dataset access, CMEK, data retention
  • Pub/Sub: message encryption, schema enforcement
  • GKE: Workload Identity, Binary Authorization, private clusters, shielded nodes
  • Cloud SQL: encryption, backup, private IP
  • Secret Manager: optional metadata-only inventory and version history is separate evidence, not a control evaluation. It does not establish that rotation occurred or that a policy is satisfied; automatic replication is not evaluated.
  • Cloud Functions: execution service account scope

When a user asks about these, say "v0.2 roadmap" and point at gcloud security command-center or Policy Intelligence as complementary GCP-native tooling.

Common pitfalls

  • Multi-project environments: this connector runs per-project. Automate by looping over your project list.
  • Org-level policies: checks see project-effective state, not where the policy is set. A project may pass because an org policy enforces public-access-prevention even though the bucket config itself is silent.
  • Workload Identity: if the caller is a service account running in GKE or Cloud Run with Workload Identity, gcloud auth list may show it indirectly. Setup still works.
  • Long key lists: projects with 100+ service accounts can take 30-60s to scan. Use --services=storage,logging,kms,compute if you want a faster run and will do IAM separately.

Commands 3

/gcp-inspector:collect

Scans a GCP project for compliance-relevant resources and configurations.

How to run

node "${CLAUDE_PLUGIN_ROOT}/scripts/collect.js" [options]

Arguments

  • --project=<id> — override the configured project
  • --services=<csv> — subset of iam,storage,logging,kms,compute,secret-manager (default: first five only). Secret Manager must be explicitly selected on the command line, not just in config. Duplicate services (including in config defaults) and repeated --services flags are usage errors before collection or run artifacts.
  • --output=<fmt> — silent | summary (default) | json
  • --refresh — ignore any cached data; re-query GCP
  • --quiet — no stderr progress

What it evaluates

Project-level (IAM):

SCFCheckSeverity
IAC-07.2No user accounts with primitive roles (roles/owner, roles/editor)high
IAC-15.1Service account key rotation (< 90 days)medium
IAC-15.1No unused service account keysmedium
IAC-01.2Organization policy service enabledlow

Storage (Cloud Storage):

SCFCheckSeverity
CRY-05Bucket encryption (default or CMEK)pass if any encryption; medium if only Google-managed for sensitive buckets
DCH-01.2Uniform bucket-level access enabledmedium
DCH-01.2Public access prevention enforcedcritical if bucket is public
MON-01.2Bucket logging enabledlow

Audit logs (Logging):

SCFCheckSeverity
MON-02Admin Activity logs going to a retained sinkhigh
MON-02Data Access logs enabled for sensitive services (Storage, IAM)medium
MON-02.1Log sink destination is not publicly accessiblehigh

KMS:

SCFCheckSeverity
CRY-09All CMEK keys have rotation period ≤ 90 daysmedium

Compute:

SCFCheckSeverity
IAC-02OS Login enabled at project levelmedium
CFG-03Default encryption on disks (usually automatic but verified)low

Output

  • ~/.cache/claude-grc/findings/gcp-inspector/<run_id>.json — array of Findings

  • ~/.cache/claude-grc/runs.log — run manifest appended

  • With explicit --services=secret-manager, ~/.cache/claude-grc/evidence/gcp-inspector/<run_id>.json contains a separate metadata-only inventory and version history. JSON output and the run log include secret_manager_evidence_path. This is not a Finding or compliance evaluation; a rotation schedule is not proof a rotation occurred. Names and timestamps can be sensitive; protect and retain the evidence accordingly. New files are mode 0600.

  • stdout summary unless --quiet:

    gcp-inspector: 18 resources, 64 evaluations, 7 failing (1 critical, 3 high, 3 medium).
    

Exit codes

  • 0 success
  • 2 usage error or credentials invalid
  • 3 rate-limited (GCP quota exhausted)
  • 4 partial (some services inaccessible; report still written)
  • 5 config missing — run setup

Minimum IAM role

roles/iam.securityReviewer        # IAM policies, service accounts
roles/cloudkms.viewer             # KMS keys + rotation
roles/logging.viewer              # log sinks
roles/compute.viewer              # instance + metadata
roles/storage.objectViewer        # bucket settings
roles/resourcemanager.folderViewer  # (optional; multi-project)

Alternatively, roles/viewer covers the basics.

For opt-in Secret Manager evidence, the required metadata-only helpers are bundled with this plugin; no separate plugin installation is needed. Grant secretmanager.secrets.list, secretmanager.secrets.get, and secretmanager.versions.list on the selected project/resources. Numeric resource names also require permission to describe the selected project to bind its project number to its ID. The collector calls only metadata list/describe commands, never version access. It uses gcloud's automatic pagination without a limit; successful collection reflects what the caller can list, not proof of broader visibility or an atomic snapshot. Permission, malformed-response, project mismatch, or helper errors cause a partial exit (4) and no Secret Manager evidence file. Review other services' results separately.

Secret Manager collection rejects inventories over 100 secrets rather than producing incomplete evidence. It has a five-minute time budget checked before and after each sequential helper; a helper already running can extend the elapsed time beyond five minutes, and is subject to its own 120-second timeout. These limits apply only to Secret Manager collection, not the whole multi-service run. Exceeding either limit causes exit 4 with no Secret Manager evidence; findings and a run manifest may still be written for the run.

Evidence is written to an exclusively created mode-0600 temporary file in the same directory, closed, then published with an atomic hard link that cannot overwrite an existing destination. A filesystem that does not support hard links causes publication to fail with exit 4; there is no unsafe copy or overwrite fallback. Write, close, or publication failures do not publish a partial final file. Cleanup is best effort: interruption or cleanup failure may leave a hidden .tmp file containing sensitive metadata, even after successful publication; protect and remove orphaned temporary files before retrying. This is an atomic visibility guarantee, not a power-loss durability guarantee (no fsync).

Examples

# Current project, all services
/gcp-inspector:collect

# Multi-project scan
for p in prod-01 prod-02 stage-01; do
  /gcp-inspector:collect --project=$p
done

# Storage only
/gcp-inspector:collect --services=storage

# Metadata-only Secret Manager inventory and version history
/gcp-inspector:collect --project=example-project --services=secret-manager --output=json

CI/CD usage

Set CLAUDE_PLUGIN_ROOT to the installed gcp-inspector plugin directory when running outside Claude Code. The gap-assessment command below assumes a marketplace checkout as its working directory.

gcloud auth activate-service-account --key-file=sa.json
node "${CLAUDE_PLUGIN_ROOT}/scripts/collect.js" --quiet
node plugins/grc-engineer/scripts/gap-assessment.js FedRAMP-Moderate --sources=gcp-inspector --output=sarif --quiet > gcp-gap.sarif

/gcp-inspector:setup

Prepares the gcp-inspector connector. Confirms gcloud CLI is installed and authenticated, writes ~/.config/claude-grc/connectors/gcp-inspector.yaml, and runs a read-only health check.

How to run

bash plugins/connectors/gcp-inspector/scripts/setup.sh [--project=<id>] [--region=<region>]

Exits 0 on success, 2 on missing/invalid credentials, 5 on missing gcloud binary.

Credential precedence

Honors the standard gcloud credential chain:

  1. --project / --region flags (written to config)
  2. GOOGLE_APPLICATION_CREDENTIALS env var pointing at a service-account JSON
  3. gcloud config get-value project and gcloud config get-value compute/region
  4. Application Default Credentials (ADC) via gcloud auth application-default login

The setup script runs gcloud auth list and gcloud projects describe to verify the resolved identity has access before writing the config.

What it does

  1. Check gcloud CLI is installed (gcloud --version).

  2. Resolve credentials (gcloud auth list --filter=status:ACTIVE).

  3. Resolve project (from --project, CLOUDSDK_CORE_PROJECT, or gcloud config).

  4. Verify the caller can at least gcloud projects describe the project (read IAM policy check).

  5. Write config:

    version: 1
    source: gcp-inspector
    source_version: "0.1.0"
    project_id: "<project>"
    project_number: "<number>"
    caller: "<email-or-sa>"
    default_region: "us-central1"
    defaults:
      services: ["iam", "storage", "logging", "kms", "compute"]
    

Typical output

gcp-inspector:setup ✓
  gcloud:          557.0.0
  project:         acme-prod (number 1234567890)
  caller:          ethan@example.com
  default region:  us-central1
  config:          ~/.config/claude-grc/connectors/gcp-inspector.yaml

Next: /gcp-inspector:collect

Failure modes

  • gcloud not installed: exit 5. brew install --cask google-cloud-sdk or https://cloud.google.com/sdk/docs/install.
  • No active account: exit 2. Run gcloud auth login then gcloud auth application-default login.
  • Project not accessible: exit 2. Either the project doesn't exist or the caller lacks resourcemanager.projects.get. Required role: at minimum roles/viewer; for a full scan, roles/iam.securityReviewer + roles/cloudkms.viewer + roles/logging.viewer.

Safe to re-run

Yes. Overwrites config; preserves cached findings.

/gcp-inspector:status

Non-destructive health check. Shows whether the connector is configured, whether credentials still work, and when it last produced findings.

How to run

bash plugins/connectors/gcp-inspector/scripts/status.sh

Output

gcp-inspector
  status:         ready
  gcloud:         557.0.0
  project:        acme-prod (1234567890)
  caller:         compliance-scanner@acme-prod.iam.gserviceaccount.com
  default region: us-central1
  config:         ~/.config/claude-grc/connectors/gcp-inspector.yaml
  last run:       4h ago (run_id 20260413-a1b2c3d4)
  cached:         18 resources, 64 evaluations

Status values

  • ready — all systems go
  • not-configured — setup not run
  • credentials-expired — gcloud auth list shows no active account
  • project-inaccessible — caller can't describe the configured project
  • stale — last run > 7 days ago

Sponsors

Details

Marketplace
GRCEngClub/claude-grc-engineering
Source
plugins/connectors/gcp-inspector
Category
Community

More from GRCEngClub/claude-grc-engineering

All 70