From cd0b5629c0715cba7a44eb226011b7d6231db9ef Mon Sep 17 00:00:00 2001 From: Cloud IX Team Date: Mon, 24 Aug 2026 16:48:12 -0700 Subject: [PATCH] Migrate google-cloud-scc-query skill to 1P standards, add Data Residency (DRZ) support, and address review feedback. PiperOrigin-RevId: 970164147 --- README.md | 1 + skills/cloud/google-cloud-scc-query/SKILL.md | 254 ++++++++++++++++++ .../references/finding_schema.md | 85 ++++++ 3 files changed, 340 insertions(+) create mode 100644 skills/cloud/google-cloud-scc-query/SKILL.md create mode 100644 skills/cloud/google-cloud-scc-query/references/finding_schema.md diff --git a/README.md b/README.md index 4548f9164b..ac33b718d4 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,7 @@ repo to install. - **Security and identity** - [**GKE Platform Security**](./skills/cloud/gke-platform-security) - [**GKE Workload Security**](./skills/cloud/gke-workload-security) + - [**Google Cloud Security Command Center Query Skill**](./skills/cloud/google-cloud-scc-query) - [**IAM Policy Simulator (v1 Allow)**](./skills/cloud/iam-helper-for-policy-simulator) - [**Privileged Access Manager (PAM)**](./skills/cloud/iam-helper-for-privileged-access-management) - [**SecOps Detection Coverage Skill**](./skills/cloud/detection-engineering-coverage-evaluation) diff --git a/skills/cloud/google-cloud-scc-query/SKILL.md b/skills/cloud/google-cloud-scc-query/SKILL.md new file mode 100644 index 0000000000..03b1035abc --- /dev/null +++ b/skills/cloud/google-cloud-scc-query/SKILL.md @@ -0,0 +1,254 @@ +--- +name: google-cloud-scc-query +metadata: + category: Security +description: >- + Queries and retrieves active security findings, external exposures, toxic + combinations, vulnerabilities, threats, and sensitive data risks from Google + Cloud Security Command Center. Use when retrieving details for a security + finding by its name, validating finding scope (e.g., verifying findingClass is + TOXIC_COMBINATION, VULNERABILITY, EXTERNAL_EXPOSURE, or THREAT), or fetching + finding details for triage. Don't use to draft remediations, apply patches, + or execute configurations. +--- + +# Google Cloud Security Command Center Query Skill + +Provides guidelines and read-only `gcloud` CLI command patterns for querying and +retrieving security findings, external exposures, toxic combinations, +vulnerabilities, threats, and sensitive data risks from Google Cloud Security +Command Center. + +> [!IMPORTANT] There is NO `gcloud scc findings describe` command (`Invalid +> choice: 'describe'`). To retrieve details for a specific finding by its name, +> always use `gcloud scc findings list` with a filter on `name`. + +-------------------------------------------------------------------------------- + +## Core Execution Rules + +1. **Read-Only & Zero-Speculation (Parent Scope Required)**: Keep all + executions strictly read-only. Every `gcloud scc findings list` or `group` + command strictly requires an explicit `{parent}` scope + (`organizations/{id}`, `projects/{id}`, or `folders/{id}`). If the parent + scope is missing from the prompt and cannot be inferred from a full finding + name, **DO NOT run any `gcloud` commands** (do not execute queries without + parent, and never inspect `gcloud config`). Halt immediately before + executing commands and ask the user for the parent resource scope. +2. **Bounded Execution & No Runaway Loops**: + - Limit tool calls to what is strictly necessary to complete the query + (typically 1 call for direct queries, or 2 calls for List → Deep Dive + workflows). + - If a command fails due to permission/auth errors, or if a specific + finding query returns `[]`, halt immediately. Do not attempt blind + brute-force retries with different flags, and never search the local + workspace for credentials. +3. **Immediate Halt on Errors**: If any command fails with `PERMISSION_DENIED`, + `IAM_PERMISSION_DENIED`, credential expiration, or network timeouts, halt + immediately and report the verbatim error message. Do not search the + workspace for credentials or run diagnostic loops. +4. **Ambiguous or Multiple Findings**: If multiple finding names are provided + when a single finding report is requested, or if listing returns multiple + findings, do not investigate all of them or unilaterally pick one. Halt + immediately without running queries and ask the user to clarify which + specific finding name they want details for. If zero findings are returned + from a query, report that no active findings exist and halt immediately. +5. **Do Not Query Attack Path Resources**: Analyze only the data present in the + Security Command Center finding JSON payload. Do not run commands to + describe, verify, or query underlying Google Cloud resources (such as VMs, + Cloud Storage buckets, service accounts, or IAM policies). +6. **Parent Scope Resolution**: + - For listing and grouping, format the parent resource path as + `organizations/{org_id}`, `projects/{project_id}`, or + `folders/{folder_id}`. + - For deep dive queries on a specific finding name, extract the `{parent}` + resource prefix before `/sources/...`: + - `organizations/{org_id}/sources/...` → `{parent}` is + `organizations/{org_id}` + - `folders/{folder_id}/sources/...` → `{parent}` is + `folders/{folder_id}` + - `projects/{project_id}/sources/...` → `{parent}` is + `projects/{project_id}` Extract the parent prefix regardless of + whether the finding resource name is global (4-segment) or + location-qualified (5-segment with `/locations/{location}/`). + Execute the deep dive query using the extracted `{parent}`. Do not + reject or halt on project- or folder-level findings. + +-------------------------------------------------------------------------------- + +## Data Residency & Regional Endpoints + +When Data Residency (DRZ) is enabled, findings are stored and accessible only +within their designated regional location (`us`, `eu`, or `me-central2`). +Queries across different locations do not return findings from other regions. + +### 1. Location Parameterization + +All `gcloud scc findings` commands require specifying the target location via +`--location={location}`: + +- **Default**: `global` (used when data residency is not enabled or for global + findings). +- **Supported Regional Locations**: + - `us` (United States multi-region) + - `eu` (European Union multi-region) + - `me-central2` (Kingdom of Saudi Arabia regional location) + +### 2. API Endpoint Overrides + +When data residency (DRZ) is enabled for an organization in a regional location +(`us`, `eu`, or `me-central2`), configure the regional API endpoint override +before executing finding queries: + +```bash +gcloud config set api_endpoint_overrides/securitycenter https://securitycenter.{LOCATION}.rep.googleapis.com/ +``` + +Example for the European Union (`eu`) region: + +```bash +gcloud config set api_endpoint_overrides/securitycenter https://securitycenter.eu.rep.googleapis.com/ +``` + +To reset the endpoint back to default global routing: + +```bash +gcloud config unset api_endpoint_overrides/securitycenter +``` + +### 3. Location-Qualified Finding Resource Names + +Regional finding resource names include the `/locations/{location}/` path +segment: + +- Organization-level: + `organizations/{org_id}/sources/{source_id}/locations/{location}/findings/{finding_id}` +- Folder-level: + `folders/{folder_id}/sources/{source_id}/locations/{location}/findings/{finding_id}` +- Project-level: + `projects/{project_id}/sources/{source_id}/locations/{location}/findings/{finding_id}` + +When performing a Deep Dive on a location-qualified finding name: + +1. Extract the `{parent}` scope (the prefix before `/sources/...`, e.g., + `organizations/{org_id}`). +2. Extract the `{location}` from `/locations/{location}/` (e.g., `eu`, `us`, + `me-central2`). If not present in the finding name, default to `global` (or + the user-specified location). +3. Execute the query with `--location={location}` and + `--filter="name=\"{finding_name}\""`. + +-------------------------------------------------------------------------------- + +## Intent-Based Query Strategies + +### 1. Deep Dive (Specific Finding Details) + +**Intent**: User provides a specific finding name or explicitly asks to retrieve +all details for one finding. \ +**Action**: Execute `gcloud scc findings list` with a strict filter on `name` +and NO `--field-mask` to retrieve the complete JSON payload. Specify +`--location={location}` (default `global` unless a regional location is +indicated or present in the finding name). + +```bash +gcloud scc findings list {parent} \ + --location={location} \ + --filter="name=\"{finding_name}\"" \ + --format="json" --limit=1 +``` + +### 2. Listing (Filtered Projection) + +**Intent**: User wants to list active findings matching criteria without pulling +full nested payloads. \ +**Action**: Use `--field-mask` projection to restrict output size. Specify +`--location={location}` (default `global` unless querying a specific region). + +```bash +gcloud scc findings list {parent} \ + --location={location} \ + --filter="{filter_expression}" \ + --field-mask="finding.name,finding.parentDisplayName,finding.findingClass,finding.category,finding.state,finding.eventTime,finding.severity,finding.resourceName" \ + --format="json" --order-by="severity,event_time desc" --limit=100 +``` + +| Intent / Target Finding Class | `--filter` Expression | +| :---------------------------- | :----------------------------------------- | +| **All Active Findings** | `state="ACTIVE"` | +| **Vulnerabilities** | `state="ACTIVE" AND | +: : findingClass="VULNERABILITY"` : +| **Misconfigurations** | `state="ACTIVE" AND | +: : findingClass="MISCONFIGURATION"` : +| **Toxic Combinations** | `state="ACTIVE" AND | +: : findingClass="TOXIC_COMBINATION"` : +| **External Exposures** | `state="ACTIVE" AND | +: : findingClass="EXTERNAL_EXPOSURE"` : +| **Threats** | `state="ACTIVE" AND findingClass="THREAT"` | +| **Observations** | `state="ACTIVE" AND | +: : findingClass="OBSERVATION"` : +| **Sensitive Data Risks** | `state="ACTIVE" AND | +: : findingClass="SENSITIVE_DATA_RISK"` : +| **Chokepoints** | `state="ACTIVE" AND | +: : findingClass="CHOKEPOINT"` : +| **Posture Violations** | `state="ACTIVE" AND | +: : findingClass="POSTURE_VIOLATION"` : +| **Secrets** | `state="ACTIVE" AND findingClass="SECRET"` | +| **SCC Errors** | `state="ACTIVE" AND | +: : findingClass="SCC_ERROR"` : +| **Specific Category** | `state="ACTIVE" AND category="{category}"` | + +### 3. Discovery & Aggregation (Grouping) + +**Intent**: User wants high-level counts or landscape overview (e.g., "What are +the most common findings?", "Show me a summary by category"). \ +**Action**: Use `gcloud scc findings group`. Specify `--location={location}` +(default `global` unless querying a specific region). Allowed fields for +`--group-by` are strictly: `resource_name`, `category`, `state`, `parent`. + +```bash +gcloud scc findings group {parent} \ + --location={location} \ + --group-by="{group_by_field}" \ + --filter="state=\"ACTIVE\"" \ + --format="json" +``` + +-------------------------------------------------------------------------------- + +## Payload Analysis & Handoff + +Once the finding JSON payload is retrieved: + +* **For `TOXIC_COMBINATION` Findings**: + 1. Verify the `attackExposure` field is present and has a `score > 0`. + 2. Inspect the attack path nodes, edges, or referenced + `attackExposureResult` to identify exposed resources and attack + trajectories. +* **For `VULNERABILITY` Findings**: + 1. Extract CVSS scores, exploit signals (`exploitationActivity`, + `observedInTheWild`, `zeroDay`), upstream fix status + (`upstreamFixAvailable`), and affected package details from the + `vulnerability` object to evaluate risk: + - `vulnerability.cve.id` + - `vulnerability.cve.cvssv3.baseScore` + - `vulnerability.cve.cvssv3.attackVector` + - `vulnerability.cve.exploitationActivity` + - `vulnerability.cve.observedInTheWild` + - `vulnerability.cve.zeroDay` + - `vulnerability.cve.upstreamFixAvailable` + - `vulnerability.offendingPackage.packageName` + - `vulnerability.offendingPackage.packageVersion` + - `vulnerability.fixedPackage.packageVersion` + - `vulnerability.securityBulletin.suggestedUpgradeVersion` +* **Handoff**: Do not draft remediation plans, patch resources, or execute + configuration commands. Pass the extracted finding payload to the + appropriate remediation or IAM analyzer skill to manage the remediation + action loop. + +-------------------------------------------------------------------------------- + +## Reference Schema + +See [finding_schema.md](references/finding_schema.md) for the JSON structure of +a Security Command Center finding. diff --git a/skills/cloud/google-cloud-scc-query/references/finding_schema.md b/skills/cloud/google-cloud-scc-query/references/finding_schema.md new file mode 100644 index 0000000000..34fcefbf1d --- /dev/null +++ b/skills/cloud/google-cloud-scc-query/references/finding_schema.md @@ -0,0 +1,85 @@ +# Security Command Center Finding Schema Reference + +This reference describes the common fields returned in the JSON payload of a +Google Cloud Security Command Center finding. + +## Resource Name Patterns + +Finding resource names follow either a 4-segment global pattern or a 5-segment +regional pattern when Data Residency (DRZ) is enabled: + +### Global Resource Names (4 segments) + +- Organization-scoped: + `organizations/{org_id}/sources/{source_id}/findings/{finding_id}` +- Folder-scoped: + `folders/{folder_id}/sources/{source_id}/findings/{finding_id}` +- Project-scoped: + `projects/{project_id}/sources/{source_id}/findings/{finding_id}` + +### Regional Resource Names (5 segments) + +- Organization-scoped: + `organizations/{org_id}/sources/{source_id}/locations/{location}/findings/{finding_id}` +- Folder-scoped: + `folders/{folder_id}/sources/{source_id}/locations/{location}/findings/{finding_id}` +- Project-scoped: + `projects/{project_id}/sources/{source_id}/locations/{location}/findings/{finding_id}` + +Supported locations include `global`, `us`, `eu`, and `me-central2`. + +## Sample JSON Payload + +```json +{ + "name": "organizations/{org_id}/sources/{source_id}/locations/{location}/findings/{finding_id}", + "parent": "organizations/{org_id}", + "parentDisplayName": "Cloud Armor", + "resourceName": "//compute.googleapis.com/projects/{project_id}/zones/{zone}/instances/{instance_name}", + "findingClass": "TOXIC_COMBINATION", + "category": "TOXIC_COMBINATION_PUBLIC_VM_WITH_EXCESSIVE_PERMISSIONS", + "state": "ACTIVE", + "severity": "CRITICAL", + "eventTime": "2026-06-16T17:41:31Z", + "createTime": "2026-06-16T17:41:31Z", + "attackExposure": { + "score": 0.85, + "attackExposureResult": "organizations/{org_id}/simulations/{sim_id}/attackExposureResults/{result_id}" + }, + "description": "Publicly accessible instance with exploitable software vulnerability and the ability to assume service accounts" +} +``` + +## Field Explanations + +* `name`: The unique identifier for the finding (either 4-segment global or + 5-segment regional format). +* `parent`: The organization, folder, or project under which this finding is + grouped. +* `parentDisplayName`: The display name of the detector or source provider + that emitted the finding (e.g., `"Cloud Armor"`, `"Vulnerability + Assessment"`, `"Sensitive Data Protection"`, `"Event Threat Detection"`). +* `findingClass`: The high-level classification of the finding. Valid enum + values from `google/cloud/securitycenter/v2/finding.proto` are: + - `THREAT`: Unwanted or malicious activity. + - `VULNERABILITY`: Potential software weaknesses (CVEs, CVSS scores, + packages). + - `MISCONFIGURATION`: Weaknesses in resource/asset configuration. + - `OBSERVATION`: Informational security observations. + - `SCC_ERROR`: Errors preventing SCC functionality. + - `POSTURE_VIOLATION`: Security posture drift or compliance violations. + - `TOXIC_COMBINATION`: Multiple security issues creating a severe attack + path. + - `SENSITIVE_DATA_RISK`: Risks to assets containing sensitive data. + - `CHOKEPOINT`: Attack path simulation convergence resources. + - `EXTERNAL_EXPOSURE`: Public internet access exposures. + - `SECRET`: Exposed plaintext credentials, keys, or tokens. +* `state`: The current status of the finding (`ACTIVE` or `MUTED`). +* `severity`: Finding severity level (`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`). +* `description`: Contains more details or explanation about the finding. +* `attackExposure`: Holds information about the computed exposure risk and + simulation result identifiers. +* `vulnerability`: Holds authentic CVE details (`cve.id`, `cve.cvssv3`, + `cve.exploitationActivity`, `cve.observedInTheWild`, `cve.zeroDay`, + `cve.upstreamFixAvailable`), package details (`offendingPackage`, + `fixedPackage`), and `securityBulletin`.