google · copybara-service · Aug 24, 2026 · Aug 24, 2026
diff --git 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
@@ -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
@@ -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`.