google-cloud-scc-query

Files (3)

• SKILL.md
• attribution.md · references/
• finding_schema.md · references/

SKILL.md (first lines)

# Security Command Center Query Skill on Google Cloud

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 Security Command Center
on Google Cloud.

> [!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`.

## Usage Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you
MUST read and follow the instructions in
[Usage Attribution](references/attribution.md).

--------------------------------------------------------------------------------

## 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}`

From google/skills, Apache-2.0.

More from google/skills