google-cloud-scc-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Cloud Security Command Center Query Skill

Google Cloud Security Command Center 查询技能

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
.

本技能提供从Google Cloud Security Command Center查询并检索安全检测结果、外部暴露风险、有害组合、漏洞、威胁以及敏感数据风险的指南和只读

gcloud

CLI命令模式。

[!IMPORTANT] 不存在
gcloud scc findings describe
命令（会提示
Invalid choice: 'describe'
）。要通过名称检索特定检测结果的详情，请始终使用带
name
过滤器的
gcloud scc findings list
命令。

Core Execution Rules

核心执行规则

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.
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.
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.
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.
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).
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.

只读操作与无推测（必须指定父级范围）：所有执行操作严格保持只读。每个
```
gcloud scc findings list
```
或
```
group
```
命令都必须明确指定
```
{parent}
```
范围（
```
organizations/{id}
```
、
```
projects/{id}
```
或
```
folders/{id}
```
）。如果提示中缺少父级范围且无法从完整的检测结果名称中推断出来，请勿运行任何
gcloud
命令（不要在没有父级范围的情况下执行查询，也不要查看
```
gcloud config
```
）。在执行命令前立即停止，并向用户请求父级资源范围。
有限执行与无循环失控：
- 将工具调用限制为完成查询严格必需的操作（直接查询通常1次调用，列表→深度分析工作流通常2次调用）。
- 如果命令因权限/认证错误失败，或特定检测结果查询返回
```
[]
```
  ，立即停止。不要尝试使用不同标志盲目重试，也绝不要在本地工作区搜索凭据。
错误立即停止：如果任何命令因
```
PERMISSION_DENIED
```
、
```
IAM_PERMISSION_DENIED
```
、凭据过期或网络超时失败，立即停止并报告原始错误消息。不要在工作区搜索凭据或运行诊断循环。
模糊或多个检测结果：当请求单个检测结果报告但提供了多个检测结果名称，或列表返回多个检测结果时，不要全部调查或单方面选择一个。立即停止不运行查询，并要求用户明确他们想要哪个特定检测结果的详情。如果查询返回零个检测结果，报告不存在活跃检测结果并立即停止。
请勿查询攻击路径资源：仅分析Security Command Center检测结果JSON负载中存在的数据。不要运行命令来描述、验证或查询底层Google Cloud资源（如VM、Cloud Storage存储桶、服务账号或IAM策略）。
父级范围解析：
- 对于列表和分组操作，父级资源路径格式为
```
organizations/{org_id}
```
  、
```
projects/{project_id}
```
  或
```
folders/{folder_id}
```
  。
- 对于特定检测结果名称的深度分析查询，提取
```
/sources/...
```
  之前的
```
{parent}
```
  资源前缀：
  - ```
  organizations/{org_id}/sources/...
```
  →
```
  {parent}
```
  为
```
  organizations/{org_id}
```
- ```
folders/{folder_id}/sources/...
```
    →
```
{parent}
```
    为
```
folders/{folder_id}
```
  - ```
  projects/{project_id}/sources/...
```
  →
```
  {parent}
```
  为
```
  projects/{project_id}
```
  无论检测结果资源名称是全局（4段）还是带位置限定（5段，包含
```
  /locations/{location}/
```
  ），都提取父级前缀。使用提取的
```
  {parent}
```
  执行深度分析查询。不要拒绝或停止处理项目或文件夹级别的检测结果。

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.

当启用数据驻留（DRZ）时，检测结果仅存储并可访问于指定的区域位置（

us

、

eu

或

me-central2

）。跨不同位置的查询不会返回其他区域的检测结果。

1. Location Parameterization

1. 位置参数化

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)

所有

gcloud scc findings

命令都需要通过

--location={location}

指定目标位置：

默认值：
```
global
```
（未启用数据驻留或针对全局检测结果时使用）。
支持的区域位置：
- ```
us
```
  （美国多区域）
- ```
eu
```
  （欧盟多区域）
- ```
me-central2
```
  （沙特阿拉伯王国区域位置）

2. API Endpoint Overrides

2. API端点覆盖

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

当组织在区域位置（

us

、

eu

或

me-central2

）启用数据驻留（DRZ）时，在执行检测结果查询前配置区域API端点覆盖：

bash

gcloud config set api_endpoint_overrides/securitycenter https://securitycenter.{LOCATION}.rep.googleapis.com/

欧盟（

eu

）区域示例：

bash

gcloud config set api_endpoint_overrides/securitycenter https://securitycenter.eu.rep.googleapis.com/

将端点重置回默认全局路由：

bash

gcloud config unset api_endpoint_overrides/securitycenter

3. Location-Qualified Finding Resource Names

3. 带位置限定的检测结果资源名称

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:

Extract the
```
{parent}
```
scope (the prefix before
```
/sources/...
```
, e.g.,
```
organizations/{org_id}
```
).
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).

Execute the query with

--location={location}

and

--filter="name=\"{finding_name}\""

区域检测结果资源名称包含

/locations/{location}/

路径段：

组织级别：

organizations/{org_id}/sources/{source_id}/locations/{location}/findings/{finding_id}

文件夹级别：

folders/{folder_id}/sources/{source_id}/locations/{location}/findings/{finding_id}

项目级别：

projects/{project_id}/sources/{source_id}/locations/{location}/findings/{finding_id}

对带位置限定的检测结果名称执行深度分析时：

提取
```
{parent}
```
范围（
```
/sources/...
```
之前的前缀，例如
```
organizations/{org_id}
```
）。
从
```
/locations/{location}/
```
中提取
```
{location}
```
（例如
```
eu
```
、
```
us
```
、
```
me-central2
```
）。如果检测结果名称中不存在，默认使用
```
global
```
（或用户指定的位置）。

使用

--location={location}

和

--filter="name=\"{finding_name}\""

执行查询。

Intent-Based Query Strategies

基于意图的查询策略

1. Deep Dive (Specific Finding Details)

1. 深度分析（特定检测结果详情）

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

意图：用户提供特定检测结果名称或明确要求检索某一检测结果的所有详情。
操作：执行带

name

严格过滤器的

gcloud scc findings list

命令，不使用

--field-mask

以获取完整JSON负载。指定

--location={location}

（默认

global

，除非指示或检测结果名称中包含区域位置）。

bash

gcloud scc findings list {parent} \
  --location={location} \
  --filter="name=\"{finding_name}\"" \
  --format="json" --limit=1

2. Listing (Filtered Projection)

2. 列表查询（过滤投影）

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

意图：用户希望列出符合条件的活跃检测结果，无需获取完整嵌套负载。
操作：使用

--field-mask

投影限制输出大小。指定

--location={location}

（默认

global

，除非查询特定区域）。

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

意图 / 目标检测结果类别	`--filter` 表达式
所有活跃检测结果	`state="ACTIVE"`
漏洞	`state="ACTIVE" AND
: : findingClass="VULNERABILITY"` :
配置错误	`state="ACTIVE" AND
: : findingClass="MISCONFIGURATION"` :
有害组合	`state="ACTIVE" AND
: : findingClass="TOXIC_COMBINATION"` :
外部暴露风险	`state="ACTIVE" AND
: : findingClass="EXTERNAL_EXPOSURE"` :
威胁	`state="ACTIVE" AND findingClass="THREAT"`
观测结果	`state="ACTIVE" AND
: : findingClass="OBSERVATION"` :
敏感数据风险	`state="ACTIVE" AND
: : findingClass="SENSITIVE_DATA_RISK"` :
瓶颈点	`state="ACTIVE" AND
: : findingClass="CHOKEPOINT"` :
合规姿态违规	`state="ACTIVE" AND
: : findingClass="POSTURE_VIOLATION"` :
密钥	`state="ACTIVE" AND findingClass="SECRET"`
SCC错误	`state="ACTIVE" AND
: : findingClass="SCC_ERROR"` :
特定类别	`state="ACTIVE" AND category="{category}"`

3. Discovery & Aggregation (Grouping)

3. 发现与聚合（分组）

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"

意图：用户需要高级统计或整体概览（例如，“最常见的检测结果有哪些？”、“按类别显示摘要”）。
操作：使用

gcloud scc findings group

命令。指定

--location={location}

（默认

global

，除非查询特定区域）。

--group-by

允许使用的字段严格限定为：

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:

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.

检索到检测结果JSON负载后：

针对
TOXIC_COMBINATION
检测结果：
1. 验证
```
attackExposure
```
  字段存在且
```
score > 0
```
  。
2. 检查攻击路径节点、边或引用的
```
attackExposureResult
```
  ，以识别暴露的资源和攻击路径。

针对
VULNERABILITY
检测结果：

从

vulnerability

对象中提取CVSS评分、利用信号（

exploitationActivity

、

observedInTheWild

、

zeroDay

）、上游修复状态（

upstreamFixAvailable

）以及受影响包的详细信息，以评估风险：

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

移交：请勿起草修复计划、修补资源或执行配置命令。将提取的检测结果负载传递给相应的修复或IAM分析技能，以管理修复操作流程。

Reference Schema

参考 Schema

See finding_schema.md for the JSON structure of a Security Command Center finding.

请查看finding_schema.md获取Security Command Center检测结果的JSON结构。