google-cloud-scc-query

Google Cloud 上的 Security Command Center 查询技能

提供只读 gcloud CLI 命令模式指南，用于从 Google Cloud 上的 Security Command Center 查询和检索安全发现项、外部暴露、毒性组合、漏洞、威胁和敏感数据风险。

重要

没有 gcloud scc findings describe 命令（Invalid choice: 'describe'）。要按名称检索特定发现项的详细信息，请始终使用带有 name 筛选条件的 gcloud scc findings list。

使用归因

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，你必须阅读并遵循使用归因中的说明。

---

核心执行规则

1. 只读且绝不臆测（必须提供父级范围）：所有执行操作都必须严格保持只读。每个 gcloud scc findings list 或 group 命令都必须明确指定 {parent} 范围（organizations/{id}、projects/{id} 或 folders/{id}）。如果提示中缺少父级范围，且无法从完整发现项名称中推断出来，不要运行任何 gcloud 命令（不要在未指定父级范围的情况下执行查询，也绝不要检查 gcloud config）。执行命令前立即停止，并向用户询问父级资源范围。
2. 限制执行范围，避免失控循环：
   • 仅调用完成查询所必需的工具（直接查询通常调用 1 次；List → Deep Dive 工作流通常调用 2 次）。
   • 如果命令因权限／身份验证错误而失败，或特定发现项查询返回 []，请立即停止。不要盲目尝试使用不同标志进行暴力重试，也绝不要在本地工作区中搜索凭据。
3. 遇到错误立即停止：如果任何命令因 PERMISSION_DENIED、IAM_PERMISSION_DENIED、凭据过期或网络超时而失败，请立即停止并报告原始错误消息。不要在工作区中搜索凭据，也不要运行诊断循环。
4. 发现项存在歧义或数量多个：如果用户要求报告单个发现项，却提供了多个发现项名称，或者列表查询返回多个发现项，不要全部调查，也不要擅自选择其中一个。请立即停止，不运行查询，并询问用户想查看哪个特定发现项的详细信息。如果查询未返回任何发现项，请报告不存在活动发现项，并立即停止。
5. 不要查询攻击路径资源：仅分析 Security Command Center 发现项 JSON 载荷中已有的数据。不要运行命令来描述、验证或查询底层 Google Cloud 资源（例如虚拟机、Cloud Storage 存储桶、服务账号或 IAM 政策）。
6. 解析父级范围：
   • 对于列表和分组，将父级资源路径格式化为 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} 执行深入查询。不要拒绝或因项目级、文件夹级发现项而停止。

---

数据驻留与区域端点

启用数据驻留（DRZ）后，发现项仅存储在指定的区域位置（us、eu 或 me-central2），并且只能在该位置访问。 跨位置查询不会返回其他区域的发现项。

1. 位置参数设置

所有 gcloud scc findings 命令都必须通过 --location={location} 指定目标位置：

• 默认值：global（未启用数据驻留或用于全局发现项时使用）。
• 支持的区域位置：
  • us（美国多区域）
  • eu（欧盟多区域）
  • me-central2（沙特阿拉伯王国区域位置）

2. API 端点覆盖

为组织在区域位置（us、eu 或 me-central2）启用数据驻留（DRZ）后，请在执行发现项查询前配置区域 API 端点覆盖：

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

欧盟（eu）区域的示例：

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

若要将端点重置为默认的全局路由：

gcloud config unset api_endpoint_overrides/securitycenter

3. 带位置限定的发现项资源名称

区域发现项资源名称包含 /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}

对带位置限定的发现项名称执行深度分析时：

1. 提取 {parent} 范围（/sources/... 前缀，例如： organizations/{org_id}）。
2. 从 /locations/{location}/ 中提取 {location}（例如 eu、us、 me-central2）。如果发现项名称中没有该位置，则默认为 global（或 用户指定的位置）。
3. 使用 --location={location} 和 --filter="name=\"{finding_name}\"" 执行查询。

---

基于意图的查询策略

1. 深度分析（特定发现项详情）

意图：用户提供特定发现项名称，或明确要求检索某个发现项的全部详情。
操作：执行 gcloud scc findings list，使用针对 name 的严格筛选条件，且不使用 --field-mask，以检索完整的 JSON 载荷。指定 --location={location}（默认值为 global，除非已指明区域位置或发现项名称中包含区域位置）。

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

2. 列表（筛选投影）

意图：用户希望列出符合条件的活动发现项，而不获取完整的嵌套负载。
操作：使用 --field-mask 投影来限制输出大小。指定 --location={location}（查询特定区域时除外，默认值为 global）。

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. 发现与聚合（分组）

意图：用户希望了解高层级计数或全局概览（例如：“最常见的发现项是什么？”、“按类别显示摘要”）。
操作：使用 gcloud scc findings group。指定 --location={location} （查询特定区域时除外，默认值为 global）。--group-by 允许使用的字段严格限定为：resource_name、category、state、parent。

gcloud scc findings group {parent} \
  --location={location} \
  --group-by="{group_by_field}" \
  --filter="state=\"ACTIVE\"" \
  --format="json"

---

载荷分析与移交

检索到发现项 JSON 载荷后：

• 对于 TOXIC_COMBINATION 发现项：
  1. 确认存在 attackExposure 字段，且其 score > 0。
  2. 检查攻击路径节点、边或引用的 attackExposureResult，以识别暴露的资源和攻击轨迹。
• 对于 VULNERABILITY 发现项：
  1. 从 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 分析器技能，以管理修复操作流程。

---

参考架构

有关 Security Command Center 发现项的 JSON 结构，请参阅 finding_schema.md。