assuredworkloads-environment-assessor

# Compliance Environment Assessor 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}`). ## 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 ...`). --- ## Grounding Guardrails: Google Cloud & Assured Workloads Precedence (CRITICAL) To prevent hallucinations, incorrect compliance assessments, and false blockers derived from generic LLM pre-training, the agent is governed by strict **Grounding Guardrails**: 1. **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. 2. **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`). 3. **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. 4. **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`. 5. **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`. ## Prerequisites Before executing environment assessment, ensure your local or Cloud Shell environment meets the following prerequisites: 1. **Google Cloud SDK**: * Install and initialize the latest Google Cloud CLI (`gcloud`): https://docs.cloud.google.com/sdk/docs/install.md.txt 2. **Project Setup & Target Selection**: * Select or configure an administrative project for running assessment queries: ```bash gcloud config set project PROJECT_ID ``` 3. **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](https://cloud.google.com/about/locations). Note that preview models or APIs are often restricted to `global` or `us-central1`. 4. **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 ``` 5. **Authentication Setup**: * Authenticate your user or service account identity and establish application default credentials: ```bash gcloud auth login gcloud auth application-default login ``` 6. **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 ``` 7. **Commands & Payloads Reference**: * Consult the [Google Cloud CLI Commands Reference](references/gcloud-commands.md) for full server-side projection masks, field filters, and API payload definitions. --- ## Step-by-Step Operating Workflow ### Step 1: Ingest Scope & Resolve Organization ID 1. 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. 2. 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)" ``` ### Step 2: Ingest Asset Telemetry & Effective Org Policies via Two-Pass Telescoping Protocol 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](references/gcloud-commands.md)): 1. **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. 2. **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 ``` ### Step 3: Fetch & Cache Built-In Framework Catalog and Filter by Location + SUR 1. **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. 2. **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). ### Step 4: Conditional Pass 2 CMEK Ingestion & Org Policy Evaluation 1. **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 ``` 2. **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` is `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 ``` 3. **Evaluate Operational & Governance Impact**: * Review `cloudControlDetails` in `frameworks.json` for parameterized and