assuredworkloads-environment-assessor

合规环境评估技能

此技能可针对 Google Cloud 文件夹（folders/{folder_id}）和项目（projects/{project_id}），以零风险、非变更的方式进行合规发现、物理遥测分析和数据边界框架建议。

使用归因

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

安全与执行等级（重要）

• 等级 R（严格只读）： 所有发现操作均执行只读查询 （gcloud asset search-all-resources、 gcloud compliance-manager frameworks list、 gcloud compliance-manager cloud-controls describe，以及 gcloud org-policies describe --effective）。 绝不能执行变更命令（gcloud compliance-manager framework-deployments create、 gcloud org-policies set-policy 或 gcloud resource-manager ...）。

---

依据约束：Google Cloud 与 Assured Workloads 优先级（重要）

为防止因大模型通用预训练而产生幻觉、不准确的合规评估和错误阻碍因素，Agent 受严格的依据约束规范管理：

1. 严格禁止使用通用大模型预训练先验：
   • 绝不能根据通用网络预训练内容推导合规规则、API 语义或部署限制（例如通用 NIST/FedRAMP 认证审计清单、AWS/Azure 架构或传统本地部署 IT 审计思维）。
   • 在传统 IT 审计中，不合规是一个非此即彼的准入门槛，会阻止部署。在 Google Cloud Assured Workloads v2 中，Monitor Mode 会部署侦测性控制措施，而不会更改现有 Organization Policies，因此可持续观测，同时不阻碍 Day 0 推出。绝不能混淆这两种模式。
2. 以 Google Cloud 权威 API 合约和适用范围为依据：
   • 所有 API 假设都必须以已发布的 Google Cloud API 合约为依据：
     • Assured Workloads v1 GA API（assuredworkloads.googleapis.com/v1）：仅适用于绿地部署。合约仅创建全新文件夹（resourceType: CONSUMER_FOLDER）。无法原地接管或绑定到现有棕地文件夹（folders/...）或项目。
     • Assured Workloads v2 API（assuredworkloads.googleapis.com/v2）：原生支持棕地部署。合约直接绑定到现有资源层级（existingFolder、existingProject），并支持非变更型 Monitor Mode（enforcementMode: DETECTIVE）。
3. 客户端组织政策就绪度与服务端 CES 边界：
   • 客户端范围：通过 scripts/evaluate_control_rules.py 进行部署前评估，仅评估绑定在 Framework.cloudControlDetails[].parameters 中的 3 组高置信度 Organization Policy 参数：
     1. 资源位置（builtin-restrict-resource-locations / constraints/gcp.resourceLocations）
     2. 服务用量限制 / SUR（builtin-enforce-service-usage-restrictions / constraints/gcp.restrictServiceUsage）
     3. CMEK 加密要求（builtin-require-cmek / constraints/gcp.restrictNonCmekServices）
   • 服务端 CES 范围：复杂的 Continuous Evaluation Service（ces_rule）和 REST API 规则（rest_api_measurement）由 Continuous Evaluation Service（CES）在框架部署后于服务端评估。
   • 术语约束：客户端发现必须表述为 部署前组织政策就绪度建议 / 潜在偏差指标（orgPolicyDriftIndicators），绝不能称为确定的合规“违规”或“部署阻碍因素”，以免与部署后实际运行的 CES 结果相矛盾。
4. 静态内置目录、会话缓存、支持路由与 KAJ 流程：
   • gcloud compliance-manager frameworks list 返回的内置框架（type: BUILT_IN）是各组织通用的静态配置。每个会话仅获取一次 frameworks.json，并在所有候选项评估和后续查询中重复使用缓存文件。
   • 人员支持模式：如果框架的 cloudControlDetails 中包含 builtin-restrict-technical-support-services（如其 displayName 和 description 所示），则需要付费的主权/受监管支持订阅。不含 builtin-restrict-technical-support-services 的框架（例如 builtin-us-data-boundary、builtin-eu-data-boundary）使用标准商业支持（支持费用增幅为 $0）。
   • 密钥访问理由（KAJ）与 EKM：仅在客户明确要求 KAJ/EKM，或需要在 frameworks.json 中区分匹配的区域变体时，才建议使用带 -with-access-justifications 的框架变体。
5. 确定性工具门控：
   • 绝不能猜测兼容性分数（$$S_{\text{composite}}$$）或资源清单。
   • 必须执行 scripts/evaluate_control_rules.py 并指定 --frameworks-file=frameworks.json，同时执行 scripts/validate_workload_payload.py 并指定 --frameworks-file=frameworks.json。

先决条件

在执行环境评估之前，请确保本地环境或 Cloud Shell 环境满足以下先决条件：

1. Google Cloud SDK：
   • 安装并初始化最新版本的 Google Cloud CLI（gcloud）：https://docs.cloud.google.com/sdk/docs/install.md.txt
2. 项目设置与目标选择：
   • 选择或配置一个用于运行评估查询的管理项目：

     gcloud config set project PROJECT_ID
     

3. 区域配置与可用性：
   • 配置一个支持良好的默认区域（例如 us-central1）：

     gcloud config set compute/region us-central1
     

   • 查阅官方区域可用性文档：Google Cloud Locations。请注意，预览版模型或 API 通常仅限于 global 或 us-central1。
4. 启用必需的 API：
   • 在管理项目中启用必需的 Google Cloud API：

     gcloud services enable \
       cloudasset.googleapis.com \
       orgpolicy.googleapis.com \
       assuredworkloads.googleapis.com \
       cloudsecuritycompliance.googleapis.com
     

5. 身份验证设置：
   • 对用户或服务账号身份进行身份验证，并设置应用默认凭据：

     gcloud auth login
     gcloud auth application-default login
     

6. 结算与配额项目设置（不产生结算费用）：
   • 零成本评估保证：运行此评估不会产生 $0 的 Google Cloud 基础设施和 API 结算费用。所有发现操作（gcloud asset search-all-resources、gcloud compliance-manager frameworks list 和 gcloud org-policies describe --effective）均为免费的只读元数据查询。
   • 配额项目要求：Google Cloud Service Infrastructure 要求管理项目关联一个有效的 Cloud Billing 账号，以便分配 API 速率限制并计量服务用量（通过 X-Goog-User-Project 标头发送），即使使用的是免费 API 也是如此。
   • 预检验证：

     # 1. 验证管理项目是否关联了有效的 Cloud Billing 账号
     gcloud billing projects describe PROJECT_ID --format="value(billingEnabled)"
     
     # 2. 如果使用共享项目，请确保你的用户身份有权限使用项目配额
     gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="user:USER_EMAIL" \
       --role="roles/serviceusage.serviceUsageConsumer"
     
     # 3. 同步应用默认凭据的配额项目
     gcloud auth application-default set-quota-project PROJECT_ID
     

7. 命令与负载参考：
   • 查阅 Google Cloud CLI Commands Reference，获取完整的服务端投影掩码、字段筛选器和 API 负载定义。

---

分步操作工作流

步骤 1：获取范围并解析组织 ID

1. 接受或询问目标范围（folders/{folder_id} 或 projects/{project_id}）。如果用户提供的范围较宽泛，但未说明监管制度，不要因广泛的问卷而阻止流程。应立即开始获取遥测数据。
2. 从范围自动解析父级组织 ID，以供后续目录查询使用：
   • 对于文件夹：

     gcloud resource-manager folders describe FOLDER_ID --format="value(parent)"
     

     （如果父级是另一个文件夹，则沿祖先逐级向上查找，直到找到 organizations/{org_id}）
   • 对于项目：

     gcloud projects get-ancestors PROJECT_ID --format="value(id,type)"
     

步骤 2：通过双遍伸缩协议摄取资产遥测数据和有效组织政策

为确保覆盖范围层级中的 100% 范围，同时保持负载精简，遥测数据摄取分为两遍伸缩处理（参见 Google Cloud CLI 命令参考）：

1. 第一遍：宏观范围与 API 枚举（100% 范围覆盖）：

   gcloud asset search-all-resources \
     --scope="folders/FOLDER_ID" \
     --page-size=500 \
     --format="json(name,assetType,location)" > macro_telemetry.json
   

   • 分页与范围语义：--page-size=500 会按每个 HTTP API 页面获取 500 个云资产（Cloud Asset Inventory 允许的最大批次大小），并自动分页遍历 folders/FOLDER_ID 及其后代项目中的所有资产。
   • 完整位置与 SUR 覆盖范围：macro_telemetry.json 会捕获评估 builtin-restrict-resource-locations（allowedLocations）和 builtin-enforce-service-usage-restrictions（allowedServices / SUR）所需的 100% 活跃 location 和 assetType 值。
   • 如果返回 PERMISSION_DENIED：
     • 如果错误指出 USER_PROJECT_DENIED 或提及 roles/serviceusage.serviceUsageConsumer，则问题出在管理配额项目（该项目未关联结算账号，或调用者缺少 serviceUsageConsumer）。请遵循配额项目恢复操作指南，并停止运行后续命令。
     • 如果错误提及目标范围（folders/... 或 projects/...），请立即停止所有工具调用（不要运行步骤 2.2、步骤 3 或任何后续命令），并告知用户，他们需要在该范围拥有 roles/cloudasset.viewer 和 roles/orgpolicy.policyViewer。
   • 如果返回的资源数为 0，请告知用户目标范围为空。

2. 检查范围内有效的通用组织政策（38/38 个框架）：

   gcloud org-policies describe gcp.resourceLocations \
     --folder=FOLDER_ID \
     --effective \
     --format="json(name,spec.rules)" > effective_locations.json
   
   gcloud org-policies describe gcp.restrictServiceUsage \
     --folder=FOLDER_ID \
     --effective \
     --format="json(name,spec.rules)" > effective_services.json
   
   gcloud org-policies describe gcp.restrictTLSVersion \
     --folder=FOLDER_ID \
     --effective \
     --format="json(name,spec.rules)" > effective_tls.json
   

步骤 3：获取并缓存内置框架目录，然后按位置和 SUR 筛选

1. 获取并缓存内置框架目录（使用绑定参数）：

   if [ ! -s frameworks.json ]; then
     gcloud compliance-manager frameworks list \
       --organization=ORGANIZATION_ID \
       --location=global \
       --filter="category:ASSURED_WORKLOADS" \
       --format="json(name,majorRevisionId,displayName,description,category,cloudControlDetails)" > frameworks.json
   fi
   

   • 会话缓存：由于内置的 ASSURED_WORKLOADS 框架是在各组织间通用的静态定义，因此将输出缓存在 frameworks.json 中，并在所有候选项评估、载荷验证和后续问题中重复使用。
2. 按位置和 SUR 覆盖范围筛选候选项并明确意图：
   • 在数据平面位置检查中，排除没有位置的控制平面管理元数据 （cloudresourcemanager.googleapis.com/*、orgpolicy.googleapis.com/*、 cloudasset.googleapis.com/*、accesscontextmanager.googleapis.com/*，以及 location: "global" 层级节点）。
   • 将 macro_telemetry.json 中的活跃数据平面区域（location）和活跃服务前缀（assetType），与 frameworks.json 中各框架的 builtin-restrict-resource-locations（allowedLocations）和 builtin-enforce-service-usage-restrictions（allowedServices / SUR）参数进行匹配：
     • 仅限美国区域（us-central1、us-east4）：候选项包括 DoD IL5（builtin-il5，经裁定支持）、ITAR（builtin-itar，支持美国人员）、FedRAMP High/Moderate，或美国区域数据边界（builtin-us-data-boundary，标准商业支持）。
     • 仅限欧盟区域（europe-west3、europe-west1）：候选项包括欧盟数据边界和支持（builtin-eu-data-boundary-and-support）与标准欧盟区域边界（builtin-eu-data-boundary）。
   • 有针对性地消除歧义：
     • 如果多个框架符合物理覆盖范围，且用户未说明法规意图（例如，未指定合规制度的开放式请求），则暂时不要确定单一的首选建议，而应列出符合条件的候选框架，并暂停以询问用户有针对性的澄清问题，了解其法规意图（例如，欧盟主权、美国 FedRAMP/IL5）和人员支持模式（标准商业支持还是付费主权/受监管支持）。
     • 仅当客户明确要求 KAJ/EKM，或在匹配的区域变体之间消除歧义时，才建议使用 -with-access-justifications（KAJ/EKM）框架变体。
     • 范围外／目录中未收录的合规标准（例如 CMMC、UK GDPR）： 如果用户要求评估 frameworks.json 中不存在的内置 ASSURED_WORKLOADS 框架所对应的合规标准或法律认证（例如 CMMC、UK GDPR、SOC 2 或 PCI-DSS），则不要编造或将不存在的框架 ID（例如 builtin-cmmc 或 builtin-uk-gdpr）传递给 evaluate_control_rules.py 或 validate_workload_payload.py。应明确说明，所请求的标准并非独立的 Assured Workloads 数据边界框架，并解释目录的范围边界（数据边界执行区域数据驻留、SUR、CMEK 和主权支持路由，而非法律隐私要求或第三方认证审计），然后提供 frameworks.json 中与其活跃区域覆盖范围相符、最接近的 ASSURED_WORKLOADS 框架（例如，适用于美国国防／CUI 工作负载的 builtin-il5 或 builtin-fedramp-high，或适用于欧洲／英国区域驻留的 builtin-eu-data-boundary-and-support／builtin-eu-data-boundary／builtin-uk-data-boundary）。

第 4 步：有条件的第二轮 CMEK 数据摄取与组织政策评估

1. 第二轮：针对 CMEK 资源类型的有条件定向深度数据摄取： 根据 macro_telemetry.json 中活跃的 CAI assetType 与 frameworks.json 中 builtin-require-cmek 管理的服务的交集，推导 TARGET_TYPES。38 个 Data Boundary 框架中只有 6 个包含 builtin-require-cmek；如果 TARGET_TYPES 非空，则获取 kmsKeys：

   TARGET_TYPES=$(python3 scripts/evaluate_control_rules.py \
     --get-target-asset-types \
     --framework=FRAMEWORK_ID \
     --telemetry-file=macro_telemetry.json \
     --frameworks-file=frameworks.json)
   
   if [ -n "${TARGET_TYPES}" ]; then
     gcloud asset search-all-resources \
       --scope="folders/FOLDER_ID" \
       --asset-types="${TARGET_TYPES}" \
       --page-size=500 \
       --format="json(name,assetType,location,kmsKeys)" > deep_telemetry.json
   fi
   

2. 运行高置信度组织政策评估器： 使用 frameworks.json 对 macro_telemetry.json（以及可选的 deep_telemetry.json）运行 scripts/evaluate_control_rules.py，以计算 3 个 定量分数（locationScore、serviceScore、cmekScore、 compositeScore）以及 orgPolicyDriftIndicators（当 cmekRequired 为 false 时，始终在评分卡中将 CMEK 就绪情况列显示为 N/A）：

   python3 scripts/evaluate_control_rules.py \
     --telemetry-file=macro_telemetry.json \
     --deep-telemetry-file=deep_telemetry.json \
     --framework=FRAMEWORK_ID \
     --frameworks-file=frameworks.json
   

3. 评估运营与治理影响：
   • 查看 frameworks.json 中的 cloudControlDetails，了解参数化和 运营控制（builtin-restrict-kms-protection-levels、 builtin-enforce-allowed-cmek-crypto-key-projects、 builtin-restrict-cloud-function-generations、 builtin-restrict-cloudstorage-auth-types、 builtin-iam-disable-service-account-key-creation、 builtin-disable-ssh-in-browser、builtin-enable-axt，以及 *-regulatory-settings 控制，例如 builtin-cloud-logging-regulatory-settings），并在最终报告中总结其对工作流的 影响。
4. 验证 Turnkey Assured Workloads 载荷：

   python3 scripts/validate_workload_payload.py \
     --payload-json='{"displayName":"Sovereign-Workload-Enclave","resourceConfig":{"existingFolder":"folders/FOLDER_ID"},"framework":{"framework":"organizations/ORGANIZATION_ID/locations/global/frameworks/FRAMEWORK_ID"}}' \
     --org-id=ORGANIZATION_ID \
     --frameworks-file=frameworks.json
   

第 5 步：生成高管评估报告（明托金字塔结构）

按照明托金字塔原理（先说结论 -> 核心价值支柱 -> 支持证据 -> 行动 计划）撰写高管报告：

# Compliance Environment Assessment Report: [Scope URI]

## 1. Executive Conclusion & Recommendation (Bottom Line Up Front)
* **Primary Recommendation**: [Framework Name] (`organizations/{org_id}/locations/global/frameworks/{framework_id}`)
* **Org Policy Readiness Alignment**: [Composite Fit %]
* **Value & Safety Invariant**: In-place brownfield adoption via Assured Workloads v2 in **Monitor Mode** (`enforcementMode: DETECTIVE`).
  * **Zero Production Outage Risk**: Mutates zero Organization Policies on Day 0.
  * **Continuous Server-Side CES Observability**: Activates real-time Continuous Evaluation Service (CES) monitoring across all framework controls.
  * **No Migration Required**: Protects existing resources in-place without provisioning separate folders.

---

## 2. Core Value Drivers: Why Assured Workloads Fits This Scope
1. **Residency & Boundary Alignment (`gcp.resourceLocations`)**: Active regional workloads are evaluated against allowed regions ([e.g. 100% US-contained]).
2. **Service & API Compatibility (`gcp.restrictServiceUsage` / SUR)**: Active service APIs are evaluated against accredited service allowlists ([e.g. 100% approved services]).
3. **Non-Disruptive Posture Hardening**: Enrolling in Monitor Mode provides server-side CES posture evaluation while allowing your team to triage Org Policy readiness safely.

---

## 3. Objective Assessment Scorecard & Org Policy Readiness Triage

### Quantitative Org Policy Readiness Scorecard
| Candidate Framework | Location Residency (`locationScore`) | Service Usage / SUR (`serviceScore`) | CMEK Readiness (`cmekScore`) | Composite Alignment | Personnel Support Model |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **[Framework 1]** | [XX%] | [XX%] | [XX% or N/A] | **[XX%]** | [Support Model] |
| **[Framework 2]** | [XX%] | [XX%] | [XX% or N/A] | **[XX%]** | [Support Model] |

### Active Resource & Effective Org Policy Baseline
* **Discovered Inventory**: [Total Assets count] across [Active resource types and regions].
* **Effective Org Policy Baseline**: [Effective `gcp.resourceLocations`, `gcp.restrictServiceUsage`, and `gcp.restrictTLSVersion` posture].

### Pre-Flight Org Policy Readiness Recommendations (Prior to Enforced Mode)
*Pre-flight drift indicators do NOT block Day 0 deployment in Monitor Mode. Address these prior to enabling preventive policy enforcement (authoritative CES and REST control evaluations run server-side after deployment):*
* **[Priority 1]**: [e.g. Configure CMEK keys on unencrypted resources before toggling `builtin-require-cmek` to `PREVENTIVE`].
* **[Priority 2]**: [e.g. Operational impact of bound controls such as `builtin-restrict-kms-protection-levels` or `builtin-cloud-logging-regulatory-settings`].

---

## 4. Deployment Action Plan & Commercial Advisory

### Deploy via Google Cloud Console (Recommended)
Review and deploy the recommended framework directly in the Google Cloud Console:
👉 **[Open Assured Workloads Console](https://console.cloud.google.com/compliance/assuredworkloads?organizationId=ORGANIZATION_ID)**
*(The Console deployment wizard binds composing controls in Monitor Mode with zero infrastructure mutations).*

### Commercial & Licensing Advisory
* Assured Workloads compliance regimes may carry support routing or licensing entitlements depending on whether `builtin-restrict-technical-support-services` is bound (standard commercial support vs. paid sovereign/regulated support).
* Review full pricing details and entitlement tiers at: https://cloud.google.com/assured-workloads/pricing

步骤 6：处理客户关于特定服务的后续问题

当客户进一步询问某个推荐或候选框架会如何影响特定 Google Cloud 服务（例如 Cloud Run、 Cloud Storage、Spanner、GKE、Cloud SQL、Vertex AI、Cloud Logging）时：

1. 在本地检查缓存的 frameworks.json（如果未缓存，则通过步骤 3 的 frameworks list 获取）：
   • 如果当前工作目录中尚不存在 frameworks.json，先运行步骤 3 中的 gcloud compliance-manager frameworks list 命令，以生成 frameworks.json。
   • 检查 <service>.googleapis.com 是否被 builtin-enforce-service-usage-restrictions（allowedServices）允许，以及 builtin-require-cmek（services）是否要求 CMEK。
   • 找出该框架中绑定的所有特定服务的 cloudControlDetails[].name 条目（例如 builtin-run-disable-ephemeral-disk、 builtin-restrict-cloudstorage-auth-types、 builtin-disable-spanner-multi-region、 builtin-cloud-logging-regulatory-settings）及任何绑定的 parameters。
2. 按需获取权威控制详情：
   • 由于 Framework.cloudControlDetails 不包含控制说明、 强制执行模式和补救步骤，因此对相关控制 ID 运行 cloud-controls describe：

     gcloud compliance-manager cloud-controls describe CONTROL_ID \
       --organization=ORGANIZATION_ID \
       --location=global \
       --format="json(name,displayName,description,supportedEnforcementModes,remediationSteps,parameterSpec)"
     

   • 从响应中提取确切的底层组织政策约束（例如 run.managed.disableEphemeralDisk、storage.restrictAuthTypes）、 supportedEnforcementModes（PREVENTIVE 与 DETECTIVE），以及 remediationSteps。
3. 按需检查生效的文件夹/项目政策：
   • 如果客户询问其文件夹是否已强制执行该特定服务的组织政策约束，请运行：

     gcloud org-policies describe CONSTRAINT_NAME \
       --folder=FOLDER_ID \
       --effective \
       --format="json(name,spec.rules)"
     

---

故障模式与错误恢复指南

错误情况	立即操作	用户恢复指导
USER_PROJECT_DENIED 或 serviceusage.serviceUsageConsumer	停止发现。不要与目标范围权限混淆。检查管理项目的结算状态和调用方的配额权限。	"管理项目 PROJECT_ID 不能用于 API 配额。1）验证是否已关联 Cloud Billing 账号（gcloud billing projects describe PROJECT_ID）；2）向你的身份授予 PROJECT_ID 上的 roles/serviceusage.serviceUsageConsumer；或者 3）切换到你拥有的项目：gcloud config set project <PROJECT_ID>。"
CAIS 上出现 PERMISSION_DENIED	立即停止发现。不要推测或猜测资源。	"如需分析此环境，请向你的当前身份授予 folders/123 上的 roles/cloudasset.viewer。"
组织政策上出现 PERMISSION_DENIED	停止政策检查。不要猜测生效的约束条件。	"如需检查生效的组织政策，请授予 folders/123 上的 roles/orgpolicy.policyViewer。"
范围为空（0 个资源）	停止评估。告知用户该范围内没有有效资产。	"folders/123 中未找到有效资源。请配置资源或选择一个有效范围。"
监管意图冲突	针对性地向用户询问以澄清。	列出不同的要求（例如，DoD IL5 裁定支持与 ITAR 美国人员），并询问业务需求。
目录中无匹配项	详细说明多区域漂移指标。	解释为何排除了单区域主权数据边界框架（例如，资源分布跨越多个大洲，涉及未经批准的区域）。
超出范围／目录中不存在的标准（例如，CMMC、UK GDPR）	不要编造框架 ID（builtin-cmmc、builtin-uk-gdpr）。说明目录范围，并映射到相邻的 ASSURED_WORKLOADS 候选项。	"frameworks.json 中没有独立的 [CMMC / UK GDPR] Assured Workloads 框架。不过，根据你当前的资源，我们可以评估相邻的 Assured Workloads 数据边界框架，例如 builtin-il5 / builtin-fedramp-high（适用于美国国防／联邦工作负载），或 builtin-eu-data-boundary-and-support / builtin-uk-data-boundary（适用于欧洲／英国区域驻留）。"