assuredworkloads-environment-assessor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Compliance Environment Assessor Skill

合规环境评估 Skill

This skill performs zero-risk, non-mutating compliance discovery, physical telemetry profiling, and data boundary framework recommendation across Google Cloud Folders (

folders/{folder_id}

) and Projects (

projects/{project_id}

此 skill 跨 Google Cloud Folders (

folders/{folder_id}

) 和 Projects (

projects/{project_id}

)，执行零风险、非变更式的合规发现、物理遥测画像分析和数据边界框架推荐。

Safety & Execution Tier (CRITICAL)

安全与执行层级（关键）

Tier R (Strictly Read-Only): All discovery operations execute read-only queries (

gcloud asset search-all-resources

gcloud compliance-manager frameworks list

gcloud compliance-manager cloud-controls describe

, and

gcloud org-policies describe --effective

). You MUST NEVER execute mutating commands (

gcloud compliance-manager framework-deployments create

gcloud org-policies set-policy

, or

gcloud resource-manager ...

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

）。

Grounding Guardrails: Google Cloud & Assured Workloads Precedence (CRITICAL)

事实依据防护规则：Google Cloud 与 Assured Workloads 的优先级（关键）

To prevent hallucinations, incorrect compliance assessments, and false blockers derived from generic LLM pre-training, the agent is governed by strict Grounding Guardrails:

Strict Prohibition on Generic LLM Pre-Training Priors:
- You MUST NOT derive compliance rules, API semantics, or deployment constraints from generic web pre-training (e.g., generic NIST/FedRAMP certification audit checklists, AWS/Azure architectures, or legacy on-prem IT auditor mindsets).
- In traditional IT audits, non-compliance is a binary go/no-go gate that blocks deployment. In Google Cloud Assured Workloads v2, Monitor Mode deploys detective controls without mutating existing Organization Policies, allowing continuous observability without halting Day 0 rollout. You MUST NOT confuse these paradigms.
Authoritative Google Cloud API Contracts & Scope Grounding:
- All API assumptions MUST be grounded in published Google Cloud API contracts:
  - Assured Workloads v1 GA API (
```
assuredworkloads.googleapis.com/v1
```
    ): Greenfield-only. Contract only creates a brand-new folder (
```
resourceType: CONSUMER_FOLDER
```
    ). It CANNOT adopt or bind to existing brownfield folders (
```
folders/...
```
    ) or projects in-place.
  - Assured Workloads v2 API (
```
assuredworkloads.googleapis.com/v2
```
    ): Brownfield-native. Contract binds directly to existing resource hierarchies (
```
existingFolder
```
    ,
```
existingProject
```
    ) and supports non-mutating Monitor Mode (
```
enforcementMode: DETECTIVE
```
    ).
Client-Side Org Policy Readiness vs. Server-Side CES Boundary:
- Client-Side Scope: Pre-flight evaluation via
```
scripts/evaluate_control_rules.py
```
  assesses ONLY the 3 high-confidence Organization Policy parameter sets bound in
```
Framework.cloudControlDetails[].parameters
```
  :
  1. Resource Locations (
```
builtin-restrict-resource-locations
```
    /
```
constraints/gcp.resourceLocations
```
    )
  2. Service Usage Restrictions / SUR (
```
builtin-enforce-service-usage-restrictions
```
    /
```
constraints/gcp.restrictServiceUsage
```
    )
  3. CMEK Encryption Requirements (
```
builtin-require-cmek
```
    /
```
constraints/gcp.restrictNonCmekServices
```
    )
- Server-Side CES Scope: Complex Continuous Evaluation Service (
```
ces_rule
```
  ) and REST API rules (
```
rest_api_measurement
```
  ) are evaluated server-side by the Continuous Evaluation Service (CES) after the framework is deployed.
- Terminology Invariant: You MUST frame client-side findings as Pre-Flight Org Policy Readiness Recommendations / Potential Drift Indicators (
```
orgPolicyDriftIndicators
```
  ), NEVER as definitive compliance "violations" or "deployment blockers" that could contradict an actual post-deployment CES run.
Static Built-In Catalog, Session Caching, Support Routing & KAJ Flow:
- Built-in Frameworks (
```
type: BUILT_IN
```
  ) returned by
```
gcloud compliance-manager frameworks list
```
  are static configurations uniform across organizations. Fetch
```
frameworks.json
```
  once per session and reuse the cached file across all candidate evaluations and follow-up queries.
- Personnel Support Model: A framework requires a Paid Sovereign/Regulated Support Subscription when
```
builtin-restrict-technical-support-services
```
  is present in its
```
cloudControlDetails
```
  (as reflected in its
```
displayName
```
  and
```
description
```
  ). Frameworks without
```
builtin-restrict-technical-support-services
```
  (e.g.,
```
builtin-us-data-boundary
```
  ,
```
builtin-eu-data-boundary
```
  ) use Standard Commercial Support ($0 support uplift).
- Key Access Justifications (KAJ) & EKM: Recommend
```
-with-access-justifications
```
  framework variants only when the customer explicitly requests KAJ/EKM, or when disambiguating between matching regional variants in
```
frameworks.json
```
  .
Deterministic Tool Gating:
- You MUST NOT guess compatibility scores ($$S_{\text{composite}}$$) or resource inventories.
- You MUST execute
```
scripts/evaluate_control_rules.py
```
  with
```
--frameworks-file=frameworks.json
```
  and
```
scripts/validate_workload_payload.py
```
  with
```
--frameworks-file=frameworks.json
```
  .

为防止产生幻觉、错误的合规评估，以及基于通用 LLM 预训练知识得出错误阻塞项，该 agent 受以下严格的事实依据防护规则约束：

严格禁止采用通用 LLM 预训练先验：
- 不得根据通用 Web 预训练知识推导合规规则、API 语义或部署约束（例如通用的 NIST/FedRAMP 认证审计检查清单、AWS/Azure 架构，或传统本地部署 IT 审计思维）。
- 在传统 IT 审计中，不合规是阻止部署的二元 go/no-go 门禁。而在 Google Cloud Assured Workloads v2 中，Monitor Mode 会在不修改现有 Organization Policies 的情况下部署检测型控制，从而实现持续可观测性，同时不会中止 Day 0 rollout。不得混淆这两种范式。
权威 Google Cloud API 契约与范围依据：
- 所有 API 假设均必须以已发布的 Google Cloud API 契约为依据：
  - Assured Workloads v1 GA API (
```
assuredworkloads.googleapis.com/v1
```
    )：仅支持 Greenfield。该契约只能创建全新的 folder (
```
resourceType: CONSUMER_FOLDER
```
    )。不能就地采用或绑定现有 brownfield folders (
```
folders/...
```
    ) 或 projects。
  - Assured Workloads v2 API (
```
assuredworkloads.googleapis.com/v2
```
    )：原生支持 Brownfield。该契约可直接绑定现有资源层级 (
```
existingFolder
```
    、
```
existingProject
```
    )，并支持非变更式 Monitor Mode (
```
enforcementMode: DETECTIVE
```
    )。
客户端 Org Policy 就绪度与服务端 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) 在服务端进行评估。
- 术语约束：必须将客户端侧发现表述为 Pre-Flight Org Policy Readiness Recommendations / Potential Drift Indicators（
```
orgPolicyDriftIndicators
```
  ），绝不能表述为确定性的合规 “违规”或可能与实际部署后 CES 运行结果相矛盾的“部署阻塞项”。
静态内置目录、会话缓存、支持路由与 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 支持附加费用）。
- Key Access Justifications (KAJ) 与 EKM：仅当客户明确要求 KAJ/EKM，或需要在
```
frameworks.json
```
  中匹配的区域变体之间进行消歧时，才推荐
```
-with-access-justifications
```
  框架变体。
确定性工具门控：
- 不得猜测兼容性分数 ($$S_{\text{composite}}$$) 或资源清单。
- 必须使用
```
--frameworks-file=frameworks.json
```
  执行
```
scripts/evaluate_control_rules.py
```
  和
```
scripts/validate_workload_payload.py
```
  。

Prerequisites

前置条件

Before executing environment assessment, ensure your local or Cloud Shell environment meets the following prerequisites:

Google Cloud SDK:
- Install and initialize the latest Google Cloud CLI (
```
gcloud
```
  ): https://docs.cloud.google.com/sdk/docs/install.md.txt
Project Setup & Target Selection:
- Select or configure an administrative project for running assessment queries:
  bash
```
gcloud config set project PROJECT_ID
```
Region Configuration & Availability:
- Configure a well-supported default region (e.g.
```
us-central1
```
  ):
  bash
```
gcloud config set compute/region us-central1
```
- Consult official region availability documentation: Google Cloud Locations. Note that preview models or APIs are often restricted to
```
global
```
  or
```
us-central1
```
  .

Required API Enablement:

Enable the required Google Cloud APIs on the administrative project:

bash

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

Authentication Setup:
- Authenticate your user or service account identity and establish application default credentials:
  bash
```
gcloud auth login
gcloud auth application-default login
```

Billing & Quota Project Setup (Zero Billing Impact):

Zero-Cost Assessment Guarantee: Running this assessment incurs $0 in Google Cloud infrastructure and API billing charges. All discovery operations (
```
gcloud asset search-all-resources
```
,
```
gcloud compliance-manager frameworks list
```
, and
```
gcloud org-policies describe --effective
```
) are free read-only metadata queries.
Quota Project Requirement: Google Cloud Service Infrastructure requires an administrative project with an active Cloud Billing account attached to allocate API rate limits and meter service usage (sent via the
```
X-Goog-User-Project
```
header), even for free APIs.

Pre-Flight Verification:

bash

# 1. Verify active Cloud Billing account is attached to administrative project
gcloud billing projects describe PROJECT_ID --format="value(billingEnabled)"

# 2. If using a shared project, ensure your user identity has permission to consume project quota
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:USER_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"

# 3. Synchronize Application Default Credentials quota project
gcloud auth application-default set-quota-project PROJECT_ID

Commands & Payloads Reference:
- Consult the Google Cloud CLI Commands Reference for full server-side projection masks, field filters, and API payload definitions.

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

Google Cloud SDK：
- 安装并初始化最新版本的 Google Cloud CLI (
```
gcloud
```
  )：https://docs.cloud.google.com/sdk/docs/install.md.txt
项目设置与目标选择：
- 选择或配置用于运行评估查询的管理项目：
  bash
```
gcloud config set project PROJECT_ID
```
区域配置与可用性：
- 配置支持完善的默认区域（例如
```
us-central1
```
  ）：
  bash
```
gcloud config set compute/region us-central1
```
*查阅官方区域可用性文档：Google Cloud Locations。请注意，预览版模型或 API 通常仅限使用
```
global
```
或
```
us-central1
```
。

启用所需 API：

在管理项目上启用所需的 Google Cloud API：

bash

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

身份验证设置：
- 验证用户或服务账号身份，并建立 Application Default Credentials：
  bash
```
gcloud auth login
gcloud auth application-default login
```

Billing 与 Quota Project 设置（零 Billing 影响）：

零成本评估保证：运行此评估在 Google Cloud 基础设施和 API 计费方面产生 $0 费用。所有发现操作（
```
gcloud asset search-all-resources
```
、
```
gcloud compliance-manager frameworks list
```
和
```
gcloud org-policies describe --effective
```
）均为免费的只读元数据查询。
Quota Project 要求：Google Cloud 服务基础架构要求管理项目关联有效的 Cloud Billing 账号，以分配 API 速率限制并计量服务使用量（通过
```
X-Goog-User-Project
```
header 发送），即使 API 本身免费。

部署前验证：

bash

# 1. Verify active Cloud Billing account is attached to administrative project
gcloud billing projects describe PROJECT_ID --format="value(billingEnabled)"

# 2. If using a shared project, ensure your user identity has permission to consume project quota
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:USER_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"

# 3. Synchronize Application Default Credentials quota project
gcloud auth application-default set-quota-project PROJECT_ID

命令与 Payload 参考：
- 查阅 Google Cloud CLI Commands Reference，了解完整的服务端 projection masks、字段过滤条件和 API payload 定义。

Step-by-Step Operating Workflow

分步操作工作流

Step 1: Ingest Scope & Resolve Organization ID

Step 1：接收范围并解析 Organization ID

Accept or prompt for the target scope (
```
folders/{folder_id}
```
or
```
projects/{project_id}
```
). If the user provides an open-ended scope without stating a regulatory regime, DO NOT block on broad questionnaires. Proceed immediately to ingest telemetry.
Automatically resolve the parent Organization ID from the scope to drive downstream catalog queries:
- For Folders:
  bash
```
gcloud resource-manager folders describe FOLDER_ID --format="value(parent)"
```
  (If the parent is another folder, traverse up ancestors until
  organizations/{org_id}
  is found)
- For Projects:
  bash
```
gcloud projects get-ancestors PROJECT_ID --format="value(id,type)"
```

接受或提示输入目标范围（
```
folders/{folder_id}
```
或
```
projects/{project_id}
```
）。如果用户提供了开放式的目标范围，但未说明适用的监管制度，不要使用冗长的问卷阻塞流程。立即开始摄取遥测数据。
自动从目标范围解析父级 Organization ID，以驱动后续目录查询：
- 对于 Folders：
  bash
```
gcloud resource-manager folders describe FOLDER_ID --format="value(parent)"
```
  （如果父级仍是另一个 folder，则持续向上遍历祖先节点，直至找到
  organizations/{org_id}
  ）
- 对于 Projects：
  bash
```
gcloud projects get-ancestors PROJECT_ID --format="value(id,type)"
```

Step 2: Ingest Asset Telemetry & Effective Org Policies via Two-Pass Telescoping Protocol

Step 2：通过两遍范围递进协议摄取资产遥测与有效 Org Policies

To guarantee 100% coverage across the scope hierarchy while keeping payloads compact, telemetry ingestion executes in two telescoping passes (see Google Cloud CLI Commands Reference):

Pass 1: Macro Footprint & API Enumeration (100% Scope Coverage):
bash
```
gcloud asset search-all-resources \
  --scope="folders/FOLDER_ID" \
  --page-size=500 \
  --format="json(name,assetType,location)" > macro_telemetry.json
```
- Pagination & Scope Semantics:
```
--page-size=500
```
  fetches 500 cloud assets per HTTP API page (the maximum batch size permitted by Cloud Asset Inventory), automatically paginating through all assets strictly inside
```
folders/FOLDER_ID
```
  and its descendant projects.
- Full Location & SUR Coverage:
```
macro_telemetry.json
```
  captures 100% of active
```
location
```
  and
```
assetType
```
  values required to evaluate both
```
builtin-restrict-resource-locations
```
  (
```
allowedLocations
```
  ) and
```
builtin-enforce-service-usage-restrictions
```
  (
```
allowedServices
```
  / SUR).
- If
```
PERMISSION_DENIED
```
  is returned:
  - If the error states
```
USER_PROJECT_DENIED
```
    or references
```
roles/serviceusage.serviceUsageConsumer
```
    , the error is on the administrative quota project (it lacks an attached billing account or caller lacks
```
serviceUsageConsumer
```
    ). Follow the Quota Project Recovery playbook and stop running further commands.
  - If the error references the target scope (
```
folders/...
```
    or
```
projects/...
```
    ), HALT ALL TOOL CALLS IMMEDIATELY (do not run Step 2.2, Step 3, or any further commands) and inform the user they require
```
roles/cloudasset.viewer
```
    and
```
roles/orgpolicy.policyViewer
```
    on that scope.
- If 0 resources are returned, inform the user the target scope is empty.

Inspect Effective Universal Org Policies on Scope (
38/38
Frameworks):

bash

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

为确保完整覆盖目标范围层级并控制 payload 大小，遥测摄取采用两遍范围递进方式执行（参见 Google Cloud CLI Commands Reference）：

第 1 遍：宏观资产足迹与 API 枚举（100% 范围覆盖）：
bash
```
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
```
  及其后代 projects 内的所有资产。
- 完整位置与 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
```
    ，则问题出在管理配额项目上（未关联 billing account，或调用者缺少
```
serviceUsageConsumer
```
    ）。按照 Quota Project Recovery 手册操作并停止执行后续命令。
  - 如果错误信息引用了目标范围（
```
folders/...
```
    或
```
projects/...
```
    ），立即停止所有工具调用（不要运行 Step 2.2、Step 3 或任何后续命令），并告知用户需要在该范围上拥有
```
roles/cloudasset.viewer
```
    和
```
roles/orgpolicy.policyViewer
```
    。
- 如果返回 0 个资源，告知用户目标范围为空。

检查范围内的通用有效 Org Policies（38/38 个框架）：

bash

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

Step 3: Fetch & Cache Built-In Framework Catalog and Filter by Location + SUR

Step 3：获取并缓存内置框架目录，按位置与 SUR 进行筛选

Fetch & Cache Built-In Framework Catalog (with Bound Parameters):

bash

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

Session Caching: Because built-in
```
ASSURED_WORKLOADS
```
frameworks are static definitions uniform across organizations, cache the output in
```
frameworks.json
```
and reuse it for all candidate evaluations, payload validations, and follow-up questions.

Filter Candidates by Location + SUR Footprint & Clarify Intent:
- Exclude location-less control-plane management metadata (
```
cloudresourcemanager.googleapis.com/*
```
  ,
```
orgpolicy.googleapis.com/*
```
  ,
```
cloudasset.googleapis.com/*
```
  ,
```
accesscontextmanager.googleapis.com/*
```
  , and
```
location: "global"
```
  hierarchy nodes) from data-plane location checks.
- Match active data-plane regions (
```
location
```
  ) and active service prefixes (
```
assetType
```
  ) from
```
macro_telemetry.json
```
  against each framework's
```
builtin-restrict-resource-locations
```
  (
```
allowedLocations
```
  ) and
```
builtin-enforce-service-usage-restrictions
```
  (
```
allowedServices
```
  / SUR) parameters in
```
frameworks.json
```
  :
  - US-Only Regions (
    us-central1
    ,
    us-east4
    ): Candidates include DoD IL5 (
```
builtin-il5
```
    , adjudicated support), ITAR (
```
builtin-itar
```
    , US persons support), FedRAMP High/Moderate, or US Regional Data Boundary (
```
builtin-us-data-boundary
```
    , standard commercial support).
  - EU-Only Regions (
    europe-west3
    ,
    europe-west1
    ): Candidates include EU Data Boundary and Support (
```
builtin-eu-data-boundary-and-support
```
    ) vs. standard EU Regional Boundary (
```
builtin-eu-data-boundary
```
    ).
- Targeted Disambiguation:
  - If multiple frameworks match the physical footprint and user regulatory intent is unstated (e.g., an open-ended request with no regime specified), DO NOT finalize a single primary recommendation yet — present the matching candidate frameworks and STOP to ask the user a targeted clarifying question about their regulatory intent (e.g., EU Sovereignty, US FedRAMP/IL5) and personnel support model (Standard Commercial Support vs. Paid Sovereign/Regulated Support).
  - Recommend
```
-with-access-justifications
```
    (KAJ/EKM) framework variants only if the customer explicitly asks for KAJ/EKM or when disambiguating between matching regional variants.
  - Out-of-Scope / Non-Catalog Compliance Standards (e.g., CMMC, UK GDPR): If the user asks to evaluate a compliance standard or legal certification that is not present as a built-in
```
ASSURED_WORKLOADS
```
    framework in
```
frameworks.json
```
    (such as CMMC, UK GDPR, SOC 2, or PCI-DSS), DO NOT fabricate or pass non-existent framework IDs (e.g.,
```
builtin-cmmc
```
    or
```
builtin-uk-gdpr
```
    ) to
```
evaluate_control_rules.py
```
    or
```
validate_workload_payload.py
```
    . Explicitly state that the requested standard is not a standalone Assured Workloads Data Boundary framework, explain the catalog scope boundary (Data Boundary enforces regional data residency, SUR, CMEK, and sovereign support routing rather than legal privacy or third-party certification audits), and offer the closest adjacent
```
ASSURED_WORKLOADS
```
    frameworks from
```
frameworks.json
```
    that match their active regional footprint (e.g.,
```
builtin-il5
```
    or
```
builtin-fedramp-high
```
    for US defense/CUI workloads, or
```
builtin-eu-data-boundary-and-support
```
    /
```
builtin-eu-data-boundary
```
    /
```
builtin-uk-data-boundary
```
    for European/UK regional residency).

获取并缓存内置框架目录（包含绑定参数）：

bash

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
```
，并在所有候选评估、payload 验证和后续问题中复用。

根据位置与 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，或 US Regional Data Boundary (
```
builtin-us-data-boundary
```
    ，标准商业支持)。
  - 仅限 EU 的区域（
    europe-west3
    、
    europe-west1
    ）：候选框架包括 EU Data Boundary and Support (
```
builtin-eu-data-boundary-and-support
```
    ) 与标准 EU Regional Boundary (
```
builtin-eu-data-boundary
```
    )。
- 有针对性的消歧：
  - 如果多个框架与物理资产足迹匹配，且用户未说明监管意图（例如开放式请求中未指定监管制度），不要立即确定唯一的主要推荐方案——应展示匹配的候选框架，并停止操作，向用户提出一个有针对性的澄清问题，询问其监管意图（例如 EU Sovereignty、US FedRAMP/IL5）和人员支持模型（Standard Commercial Support 与 Paid Sovereign/Regulated Support）。
  - 仅当客户明确要求 KAJ/EKM，或需要在匹配的区域变体之间进行消歧时，才推荐
```
-with-access-justifications
```
    （KAJ/EKM）框架变体。
  - 范围外或目录中不存在的合规标准（例如 CMMC、UK GDPR）：如果用户要求评估的合规标准或法律认证并未作为内置
```
ASSURED_WORKLOADS
```
    框架出现在
```
frameworks.json
```
    中（例如 CMMC、UK GDPR、SOC 2 或 PCI-DSS），不得虚构或不存在的 framework ID（例如
```
builtin-cmmc
```
    或
```
builtin-uk-gdpr
```
    ），也不得将其传给
```
evaluate_control_rules.py
```
    或
```
validate_workload_payload.py
```
    。应明确说明所请求的标准不是独立的 Assured Workloads Data Boundary framework，解释目录的范围边界（Data Boundary 负责实施区域数据驻留、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
```
    ）。

Step 4: Conditional Pass 2 CMEK Ingestion & Org Policy Evaluation

Step 4：按需执行第 2 遍 CMEK 摄取与 Org Policy 评估

Pass 2: Conditional Targeted Deep Ingestion for CMEK Resource Types: Derive

TARGET_TYPES

(the intersection of active CAI

assetType

s in

macro_telemetry.json

and CMEK-governed services in

builtin-require-cmek

from

frameworks.json

). Only 6 of the 38 Data Boundary frameworks include

builtin-require-cmek

; if

TARGET_TYPES

is non-empty, fetch

kmsKeys

bash

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

Execute High-Confidence Org Policy Evaluator: Run

scripts/evaluate_control_rules.py

over

macro_telemetry.json

(and optional

deep_telemetry.json

) with

frameworks.json

to compute the 3 quantitative scores (

locationScore

serviceScore

cmekScore

compositeScore

) and

orgPolicyDriftIndicators

(when

cmekRequired

false

, always display the CMEK Readiness column as

N/A

in the scorecard):

bash

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

Evaluate Operational & Governance Impact:

Review

cloudControlDetails

frameworks.json

for parameterized and operational controls (

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

, and

*-regulatory-settings

controls like

builtin-cloud-logging-regulatory-settings

) and summarize their workflow impact in the final report.

Validate Turnkey Assured Workloads Payload:

bash

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

第 2 遍：针对 CMEK 资源类型进行条件式深度摄取：推导

TARGET_TYPES

，即

macro_telemetry.json

中的有效 CAI

assetType

与

frameworks.json

中

builtin-require-cmek

所涵盖服务之间的交集。38 个 Data Boundary frameworks 中只有 6 个包含

builtin-require-cmek

；如果

TARGET_TYPES

非空，则获取

kmsKeys

：

bash

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

执行高置信度 Org Policy 评估器：使用

frameworks.json

，通过

scripts/evaluate_control_rules.py

对

macro_telemetry.json

（以及可选的

deep_telemetry.json

）执行评估，以计算 3 个定量分数（

locationScore

、

serviceScore

、

cmekScore

、

compositeScore

）和

orgPolicyDriftIndicators

。当

cmekRequired

为

false

时，评分卡中的 CMEK Readiness 列必须始终显示为

N/A

：

bash

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

评估运营与治理影响：

检查

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

），并在最终报告中总结其对工作流的影响。

验证即用型 Assured Workloads Payload：

bash

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

Step 5: Render Executive Assessment Report (Minto Pyramid Structure)

Step 5：按照 Minto 金字塔结构呈现高管评估报告

Present an executive report structured around the Minto Pyramid Principle (Bottom Line Up Front -> Core Value Pillars -> Supporting Evidence -> Action Plan):

markdown

undefined

以 Minto Pyramid Principle（结论先行 → 核心价值支柱 → 支撑证据 → 行动计划）为核心结构呈现高管报告：

markdown

undefined

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.

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

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

Residency & Boundary Alignment (
gcp.resourceLocations
): Active regional workloads are evaluated against allowed regions ([e.g. 100% US-contained]).
Service & API Compatibility (
gcp.restrictServiceUsage
/ SUR): Active service APIs are evaluated against accredited service allowlists ([e.g. 100% approved services]).
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]

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

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

builtin-cloud-logging-regulatory-settings

[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

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

undefined

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

undefined

Step 6: Handling Customer Follow-Up Questions on Specific Services

Step 6：处理客户针对特定服务的后续问题

When a customer follows up with a specific question about how a recommended or candidate framework affects a particular Google Cloud service (e.g., Cloud Run, Cloud Storage, Spanner, GKE, Cloud SQL, Vertex AI, Cloud Logging):

Inspect Cached
frameworks.json
Locally (or Fetch via Step 3
frameworks list
if Not Cached):

If
```
frameworks.json
```
is not yet present in the current working directory, run the Step 3
```
gcloud compliance-manager frameworks list
```
command first to populate
```
frameworks.json
```
.

Check whether

<service>.googleapis.com

is permitted in

builtin-enforce-service-usage-restrictions

(

allowedServices

) and whether CMEK is required in

builtin-require-cmek

(

services

Identify all service-specific

cloudControlDetails[].name

entries bound in that framework (e.g.,

builtin-run-disable-ephemeral-disk

builtin-restrict-cloudstorage-auth-types

builtin-disable-spanner-multi-region

builtin-cloud-logging-regulatory-settings

) and any bound

parameters

Fetch Authoritative Control Details On Demand:

Because

Framework.cloudControlDetails

omits control descriptions, enforcement modes, and remediation steps, run

cloud-controls describe

for the relevant control ID(s):

bash

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

Extract the exact underlying Organization Policy constraint (e.g.,

run.managed.disableEphemeralDisk

storage.restrictAuthTypes

supportedEnforcementModes

(

PREVENTIVE

vs.

DETECTIVE

), and

remediationSteps

from the response.

Check Effective Folder/Project Policy If Requested:
- If the customer asks whether their folder already enforces that service-specific Org Policy constraint, run:
  bash
```
gcloud org-policies describe CONSTRAINT_NAME \
  --folder=FOLDER_ID \
  --effective \
  --format="json(name,spec.rules)"
```

当客户就推荐或候选框架如何影响特定 Google Cloud 服务（例如 Cloud Run、Cloud Storage、Spanner、GKE、Cloud SQL、Vertex AI、Cloud Logging）提出具体问题时：

在本地检查缓存的
frameworks.json
（如果尚未缓存，则通过 Step 3 的
frameworks list
获取）：

如果当前工作目录中不存在
```
frameworks.json
```
，先运行 Step 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

。

按需获取权威控制详情：

由于

Framework.cloudControlDetails

不包含控制说明、强制执行模式和修复步骤，应针对相关控制 ID 运行

cloud-controls describe

：

bash

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

从响应中提取底层的确切 Organization Policy constraint（例如

run.managed.disableEphemeralDisk

、

storage.restrictAuthTypes

）、

supportedEnforcementModes

（

PREVENTIVE

与

DETECTIVE

）和

remediationSteps

。

按需检查有效的 Folder/Project Policy：
- 如果客户询问其 folder 是否已强制执行特定服务的 Org Policy constraint，请运行：
  bash
```
gcloud org-policies describe CONSTRAINT_NAME \
  --folder=FOLDER_ID \
  --effective \
  --format="json(name,spec.rules)"
```

Failure Modes & Error Recovery Playbook

失败模式与错误恢复手册

Error Condition	Immediate Action	User Recovery Guidance
`USER_PROJECT_DENIED` or `serviceusage.serviceUsageConsumer`	HALT discovery. Do not confuse with target scope permissions. Check administrative project billing status and caller quota permissions.	"The administrative project `PROJECT_ID` cannot be used for API quota. 1) Verify a Cloud Billing account is attached ( `gcloud billing projects describe PROJECT_ID` ), 2) Grant `roles/serviceusage.serviceUsageConsumer` on `PROJECT_ID` to your identity, or 3) Switch to a project you own: `gcloud config set project <PROJECT_ID>` ."
`PERMISSION_DENIED` on CAIS	HALT discovery immediately. Do not speculate or guess resources.	"To analyze this environment, grant `roles/cloudasset.viewer` on `folders/123` to your active identity."
`PERMISSION_DENIED` on Org Policies	HALT policy inspection. Do not guess effective constraints.	"To inspect effective organization policies, grant `roles/orgpolicy.policyViewer` on `folders/123` ."
Empty Scope (0 Resources)	HALT evaluation. Inform user the scope contains no active assets.	"No active resources found in `folders/123` . Provision resources or select an active scope."
Conflicting Regulatory Intent	Engage user in focused clarification probe.	Present distinct requirements (e.g. DoD IL5 Adjudicated Support vs. ITAR US Persons) and ask for business requirement.
Zero Catalog Match	Detail multi-regional drift indicator.	Explain why single-region sovereign data boundary frameworks were ruled out (e.g. multi-continental resource footprint spanning unapproved regions).
Out-of-Scope / Non-Catalog Standard (e.g., CMMC, UK GDPR)	Do not invent framework IDs ( `builtin-cmmc` , `builtin-uk-gdpr` ). Explain catalog boundary and map to adjacent `ASSURED_WORKLOADS` candidates.	"Assured Workloads does not include a standalone `[CMMC / UK GDPR]` framework in `frameworks.json` . However, based on your active resources, we can evaluate an adjacent Assured Workloads Data Boundary framework such as `builtin-il5` / `builtin-fedramp-high` (for US defense/federal workloads) or `builtin-eu-data-boundary-and-support` / `builtin-uk-data-boundary` (for European/UK regional residency)."

错误情况	立即操作	用户恢复指导
`USER_PROJECT_DENIED` 或 `serviceusage.serviceUsageConsumer`	停止发现操作。不要将其与目标范围的权限问题混淆。检查管理项目的 billing 状态和调用者的配额权限。	"管理项目 `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` 。"
Org Policies 上出现 `PERMISSION_DENIED`	停止策略检查。不得猜测有效 constraints。	"要检查有效的 Organization Policies，请授予 `folders/123` 上的 `roles/orgpolicy.policyViewer` 。"
范围为空（0 个资源）	停止评估。告知用户该范围不包含任何有效资产。	"未在 `folders/123` 中找到有效资源。请预配资源或选择有效范围。"
监管意图冲突	与用户进行聚焦式澄清。	展示不同的明确要求（例如 DoD IL5 Adjudicated Support 与 ITAR US Persons），并询问其业务需求。
目录中无匹配项	详细说明多区域 drift indicator。	解释为何已排除单一区域的主权数据边界框架，例如资源足迹横跨多个大洲并包含未批准区域。
范围外或目录中不存在的标准（例如 CMMC、UK GDPR）	不得虚构 framework ID（ `builtin-cmmc` 、 `builtin-uk-gdpr` ）。解释目录边界并映射到相邻的 `ASSURED_WORKLOADS` 候选框架。	" `frameworks.json` 中不包含独立的 `[CMMC / UK GDPR]` Assured Workloads framework。不过，根据当前有效资源，可以评估相邻的 Assured Workloads Data Boundary framework，例如用于美国国防或联邦工作负载的 `builtin-il5` / `builtin-fedramp-high` ，或用于欧洲或英国区域驻留的 `builtin-eu-data-boundary-and-support` / `builtin-eu-data-boundary` / `builtin-uk-data-boundary` 。"