From 04b3188bdb8c7f627d605d02428d578dab41b700 Mon Sep 17 00:00:00 2001 From: Cloud IX Team Date: Thu, 9 Jul 2026 11:05:24 -0700 Subject: [PATCH] Migrate google-cloud-scc-query skill to 1P standards. PiperOrigin-RevId: 945213172 --- skills/cloud/google-cloud-scc-query/SKILL.md | 283 ++++++++++++++++++ .../references/finding_schema.md | 36 +++ 2 files changed, 319 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/skills/cloud/google-cloud-scc-query/SKILL.md b/skills/cloud/google-cloud-scc-query/SKILL.md new file mode 100644 index 0000000000..6992c08589 --- /dev/null +++ b/skills/cloud/google-cloud-scc-query/SKILL.md @@ -0,0 +1,283 @@ +--- +name: google-cloud-scc-query +description: >- + Queries and retrieves active security findings, toxic combinations, or vulnerabilities from Google Cloud Security Command Center (SCC). Use when retrieving details for a security finding by its name, validating finding scope (e.g., verifying findingClass is TOXIC_COMBINATION or VULNERABILITY), or fetching finding details for triage. Always keep executions read-only and never guess missing parameters. +--- + + + + +# Security Command Center (SCC) Query Skill + +This skill provides guidelines and gcloud CLI command patterns for retrieving +and querying security findings, toxic combinations, and vulnerabilities from +Google Cloud Security Command Center (SCC). + +> [!IMPORTANT] **CRITICAL GOTCHA**: There is NO `gcloud scc findings describe` +> command. Any attempt to run it will fail with `Invalid choice: 'describe'`. To +> describe or retrieve details for a specific finding by its name, you MUST use +> `gcloud scc findings list` with a filter on `name`. + +## 3-Tier Consent Gate + +* **Tier R (Read-Only)**: Listing active findings, retrieving finding details, + and fetching attack path simulation metadata. +* **Tier M (Mutating)**: None. This skill is strictly read-only. +* **Tier D (Destructive)**: None. + +## When to Use + +* To retrieve the detailed JSON representation of a Security Command Center + finding using its unique finding name. +* To list active findings, toxic combinations, or vulnerabilities in a project + or organization. +* To retrieve the attack path simulation (APS) details embedded in toxic + combination findings, or the vulnerability details (like CVE context) + embedded in vulnerability findings. + +## Execution Rules & Constraints + +1. **HITL (Human-in-the-Loop) Escalation**: You MUST immediately halt execution + and ask the user to provide guidance when encountering ambiguous user + intent, conflicting SCC facts, or missing `gcloud` or API configuration + permissions. +2. **Read-Only Operations**: All executions are strictly Read-Only. You MUST + NOT execute mutating `gcloud` or Terraform commands under any circumstances. +3. **Zero-Speculation**: Security findings, resource states, and remediation + actions MUST NEVER be speculated or assumed. If data is missing, ambiguous, + or outside vetted bounds, you MUST immediately halt and ask the user for + clarification. +4. **Handling Missing IDs**: + * If the project ID, organization ID, or folder ID is missing or not + provided in the user's prompt or context, you **MUST** halt execution + immediately and ask the user to provide the correct ID, unless the + finding name itself implies it. You **MUST NOT** speculate, guess, or + attempt to look up missing identifiers via `gcloud config` (e.g., + `gcloud config get-value project`). +5. **Missing Finding Details**: + * If the user specifies a unique finding name in their request, and the + `gcloud scc findings list` command filtered by that name returns an + empty result, you **MUST** immediately stop, return a final response to + the user stating that the specified finding could not be found, and halt + execution. You **MUST NOT** attempt to list all findings in the + organization/project, ask the user to choose from other findings, or + fall back to any other skills or tools. +6. **Ambiguous or Missing Finding Name**: + + * If the user asks for details of the active finding in a + project/organization but does not specify the unique finding name, you + should list the active findings. You **MUST** format the parent ID into + the fully qualified parent resource path (e.g., + `organizations/{org_id}`, `projects/{project_id}`, or + `folders/{folder_id}`) and use the exact syntax: + + ```bash + gcloud scc findings list {parent} \ + --location=global \ + --filter="state=\"ACTIVE\"" \ + --field-mask="finding.name,finding.findingClass,finding.category,finding.state,finding.eventTime" \ + --format="json" --order-by="event_time desc" --limit=100 + ``` + + * If the user specifically asks to list active vulnerabilities or active + toxic combinations, you **MUST** filter by `findingClass`: + + - For Vulnerabilities: + + ```bash + gcloud scc findings list {parent} \ + --location=global \ + --filter="state=\"ACTIVE\" AND findingClass=\"VULNERABILITY\"" \ + --field-mask="finding.name,finding.findingClass,finding.category,finding.state,finding.eventTime,finding.severity,finding.resourceName" \ + --format="json" --order-by="event_time desc" --limit=100 + ``` + + - For Toxic Combinations: + + ```bash + gcloud scc findings list {parent} \ + --location=global \ + --filter="state=\"ACTIVE\" AND findingClass=\"TOXIC_COMBINATION\"" \ + --field-mask="finding.name,finding.findingClass,finding.category,finding.state,finding.eventTime,finding.severity,finding.resourceName" \ + --format="json" --order-by="event_time desc" --limit=100 + ``` + + * If the user asks to filter findings by a specific category, you **MUST** + use the exact syntax: + + ```bash + gcloud scc findings list {parent} \ + --location=global \ + --filter="state=\"ACTIVE\" AND category=\"{category}\"" \ + --field-mask="finding.name,finding.findingClass,finding.category,finding.state,finding.eventTime,finding.severity,finding.resourceName" \ + --format="json" --order-by="event_time desc" --limit=100 + ``` + + * If multiple findings are provided in the user's prompt or context, or if + multiple findings are returned by the list command, you **MUST NOT** + unilaterally pick one to describe, nor attempt to retrieve details for + multiple findings. You **MUST** immediately halt execution and ask the + user to specify which finding name they want details for. + + * If the list command returns **zero findings** (empty result), you + **MUST** immediately stop, return a final response to the user stating + that no active findings were found in the specified + project/organization, and halt execution. You **MUST NOT** search the + workspace, try to find it elsewhere, or invoke other skills. + +7. **Do NOT verify or describe attack path resources**: + + * This skill is strictly for retrieving and extracting details *from the + SCC finding payload itself*. + * You **MUST NOT** attempt to run any commands to describe, verify, or + query the actual GCP resources (such as GCS buckets, service accounts, + VMs, or IAM policies) mentioned in the finding's attack path. + * Resource analysis must be delegated to other skills (like + `security-iam-analyzer`) or skipped entirely if not explicitly requested + by the user. + +8. **Immediate Halt on Execution Errors**: + + * If any `gcloud` command fails due to permission, authorization, + authentication, configuration, or connectivity issues (for example, + receiving `PERMISSION_DENIED`, `IAM_PERMISSION_DENIED`, credential + expiration, or API endpoint connection timeouts), you **MUST** halt + execution immediately. + * You **MUST NOT** attempt to troubleshoot, resolve, or search for + credentials/configs. Specifically, do not: + * Search the workspace or look for local configuration/credentials + files. + * Query gcloud configuration or authentication states (e.g., `gcloud + config ...` or `gcloud auth ...`). + * Enter any debugging or diagnostic loops (like running `grep`, + `find`, or custom scripts). + * Report the failure and the verbatim error message from the failed + command to the user immediately. + +9. **Strict Turn Budget (Single-Attempt)**: + + - You are allowed a maximum of **1 tool-execution turn** (a single + attempt/turn) to retrieve the finding payload. Under no circumstances + are you allowed a second turn or any additional tool calls. If after + this **single tool-execution turn** you have not successfully retrieved + the finding details (e.g., the command fails or returns empty), you + **MUST** immediately stop all tool calls, explain the situation, and + halt execution. Do NOT attempt any other commands or variations. + +10. **No Retries or Variations on Empty/Failure Results**: + + - If the `gcloud scc findings list` command returns an empty array `[]` or + fails with an error, you **MUST NOT** attempt to run it again with + different filters, different parent parameters, or different arguments. + You **MUST NOT** run other listing or diagnostic commands. Treat the + empty result or error as final, halt execution immediately, and report + the verbatim outcome to the user. + +## Intent-Based Query Strategies + +When querying SCC, you must first determine the user's intent. Do not default to +retrieving the full finding payload unless specifically asked for a single +finding. + +### 1. Discovery Strategy (High-Level Aggregation) + +**Intent**: The user wants to understand the landscape, count findings, or see +the most common issues (e.g., "What are the most common findings?", "Show me a +summary by category"). **Action**: Use `gcloud scc findings group` to aggregate. +Allowed fields for `--group-by` are strictly: `resource_name`, `category`, +`state`, `parent`. Do not group by other fields. **Command Pattern**: + +```bash +gcloud scc findings group {parent} \ + --location=global \ + --group-by="{group_by_field}" \ + --filter="state=\"ACTIVE\"" \ + --format="json" +``` + +### 2. Listing Strategy (Filtered Projection) + +**Intent**: The user wants to see a list of findings matching criteria, but does +not explicitly ask for a deep dive into a single finding (e.g., "List my active +vulnerabilities", "Show me recent toxic combinations"). **Action**: Use `gcloud +scc findings list` with `--field-mask` projection to avoid massive payloads. +**Command Pattern**: + +```bash +gcloud scc findings list {parent} \ + --location=global \ + --filter="state=\"ACTIVE\"" \ + --field-mask="finding.name,finding.findingClass,finding.category,finding.state,finding.eventTime,finding.severity,finding.resourceName" \ + --format="json" --order-by="event_time desc" --limit=100 +``` + +*(Append `AND findingClass=\"{class}\"` to the filter if a specific class is +requested).* + +### 3. Deep Dive Strategy (Specific Finding Details) + +**Intent**: The user provides a specific finding name or explicitly asks to +retrieve all details for one finding. **Action**: First, verify the **Parent +Scope**. Confirm the parent starts with `organizations/`. If it is `projects/` +or `folders/`, you MUST immediately halt and inform the user that automated +triage is only supported for organization-level findings. Do not attempt to run +any commands. If it is `organizations/`, use `gcloud scc findings list` with a +strict filter on the name, and NO `--field-mask` to get the full payload. +**Command Pattern**: + +```bash +gcloud scc findings list {parent} \ + --filter="name=\"{finding_name}\"" \ + --location=global \ + --format="json" --order-by="event_time desc" --limit=100 +``` + +* **Safety Warning**: NEVER run `gcloud scc findings describe {finding_name}`. + +### Validation and Routing (After Retrieval) + +Once a full payload is retrieved (Deep Dive), analyze the payload based on the +finding class: + +1. **TOXIC_COMBINATION**: Analyze the payload and generate a non-mutating + remediation draft based on the finding context and attack path. +2. **VULNERABILITY**: Extract CVE/EPSS/CVSS and use this context to prioritize + the risk and propose non-mutating remediation steps. +3. **MISCONFIGURATION**: Analyze the misconfiguration and generate a + non-mutating remediation draft. + +### Extract Attack Path or Vulnerability Details + +**For `TOXIC_COMBINATION` findings:** The attack path is described in the +`attackExposure` object inside the finding details. + +1. Verify the `attackExposure` field is present and has a `score > 0`. +2. Examine the attack path nodes and edges in the finding payload or referenced + `attackExposureResult` to identify exposed resources and attack + trajectories. + +**For `VULNERABILITY` findings:** + +1. Extract CVSS, EPSS, CISA KEV, and affected package details from the + `vulnerability.cve` object. +2. Use this extracted context to evaluate and prioritize the vulnerability + risk. + +### Declarative Handoff (Toxic Combinations / Misconfigurations) + +If the finding relates to a "Publicly Accessible VM" or "Open Firewall Port", +you **MUST** rely entirely on the Attack Path or misconfiguration context within +the payload to confirm the exposure. Then, end your response by explicitly +asking the user to choose the next step: + +* **Mute:** Ask if they want to mute the finding. If they choose this, draft + the `gcloud scc findings set-mute --organization= + --source= --location=global --mute=MUTED` command. +* **Mitigate:** Ask if they want to draft right-sized firewall rules (via + `gcloud` or Terraform) to restrict the exposed ports. Always output + non-mutating drafts and never execute them without explicit permission. + +## 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..261376e6ec --- /dev/null +++ b/skills/cloud/google-cloud-scc-query/references/finding_schema.md @@ -0,0 +1,36 @@ +# SCC Finding Schema Reference + +This reference describes the common fields returned in the JSON payload of a +Security Command Center finding. + +```json +{ + "name": "organizations/{org_id}/sources/{source_id}/findings/{finding_id}", + "parent": "organizations/{org_id}", + "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}" + }, + "findingDetails": { + "description": "Publicly accessible instance with exploitable software vulnerability and the ability to assume service accounts" + } +} +``` + +## Field Explanations + +* `name`: The unique identifier for the finding. +* `parent`: The organization, folder, or project under which this finding is + grouped. +* `findingClass`: The high-level classification of the finding. Automated + triaging requires this to be `TOXIC_COMBINATION` or `VULNERABILITY`. +* `state`: The current status of the finding. Typically `ACTIVE` or `MUTED`. +* `attackExposure`: Holds information about the computed exposure risk and + simulation result identifiers.