
gcp-inspector
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-suiteRun it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.
Contents
Discovered from sourceSkills 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):
| SCF | Check | Severity |
|---|---|---|
| IAC-07.2 | No user accounts with primitive roles (owner/editor) | high |
| IAC-15.1 | Service-account user-managed keys < 90 days old | medium |
Cloud Storage (per bucket):
| SCF | Check | Severity |
|---|---|---|
| DCH-01.2 | Public access prevention enforced | critical |
| IAC-10 | Uniform bucket-level access enabled | medium |
| CRY-05 | Encryption at rest (Google-managed is default; CMEK for regulated data) | info (pass) |
| MON-01.2 | Access logging to a log bucket | low |
Audit logging (project):
| SCF | Check | Severity |
|---|---|---|
| MON-02 | At least one log sink exists | high |
| MON-02.1 | Log sink destination isn't publicly readable | high |
KMS (per key):
| SCF | Check | Severity |
|---|---|---|
| CRY-09 | Rotation period ≤ 90 days (7,776,000s) on ENCRYPT_DECRYPT keys | medium |
Compute (project):
| SCF | Check | Severity |
|---|---|---|
| IAC-02 | OS Login enabled at project level | medium |
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 listmay 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,computeif 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 ofiam,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--servicesflags 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):
| SCF | Check | Severity |
|---|---|---|
| IAC-07.2 | No user accounts with primitive roles (roles/owner, roles/editor) | high |
| IAC-15.1 | Service account key rotation (< 90 days) | medium |
| IAC-15.1 | No unused service account keys | medium |
| IAC-01.2 | Organization policy service enabled | low |
Storage (Cloud Storage):
| SCF | Check | Severity |
|---|---|---|
| CRY-05 | Bucket encryption (default or CMEK) | pass if any encryption; medium if only Google-managed for sensitive buckets |
| DCH-01.2 | Uniform bucket-level access enabled | medium |
| DCH-01.2 | Public access prevention enforced | critical if bucket is public |
| MON-01.2 | Bucket logging enabled | low |
Audit logs (Logging):
| SCF | Check | Severity |
|---|---|---|
| MON-02 | Admin Activity logs going to a retained sink | high |
| MON-02 | Data Access logs enabled for sensitive services (Storage, IAM) | medium |
| MON-02.1 | Log sink destination is not publicly accessible | high |
KMS:
| SCF | Check | Severity |
|---|---|---|
| CRY-09 | All CMEK keys have rotation period ≤ 90 days | medium |
Compute:
| SCF | Check | Severity |
|---|---|---|
| IAC-02 | OS Login enabled at project level | medium |
| CFG-03 | Default 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>.jsoncontains a separate metadata-only inventory and version history. JSON output and the run log includesecret_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
0success2usage error or credentials invalid3rate-limited (GCP quota exhausted)4partial (some services inaccessible; report still written)5config 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:
--project/--regionflags (written to config)GOOGLE_APPLICATION_CREDENTIALSenv var pointing at a service-account JSONgcloud config get-value projectandgcloud config get-value compute/region- 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
-
Check
gcloudCLI is installed (gcloud --version). -
Resolve credentials (
gcloud auth list --filter=status:ACTIVE). -
Resolve project (from
--project,CLOUDSDK_CORE_PROJECT, orgcloud config). -
Verify the caller can at least
gcloud projects describethe project (read IAM policy check). -
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-sdkor https://cloud.google.com/sdk/docs/install. - No active account: exit 2. Run
gcloud auth loginthengcloud 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 minimumroles/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 gonot-configured— setup not runcredentials-expired—gcloud auth listshows no active accountproject-inaccessible— caller can't describe the configured projectstale— 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- gcp-secret-metadatav0.1.0
- gdprv0.1.0
- github-inspectorv0.1.0
- glbav0.1.0
- grc-auditorv0.1.0
- grc-diagramsv0.1.0
- grc-engineerv0.1.0
- grc-internalv0.1.0
- grc-loopv0.1.0
- grc-portfoliov0.1.0
- grc-reporterv0.1.0
- grc-tprmv0.1.0
- hitrustv0.1.0
- ind-dpdpav0.1.0
- irapv0.1.0
- ismapv0.1.0
- iso27001v0.1.0
- jp-appiv0.1.0
- nist-800-53v0.1.0
- nist-ai-600-1v0.1.0
- nist-ai-rmfv0.1.0
- nist-csf-20v0.1.0
- nydfsv0.1.0
- okta-inspectorv0.1.0