From 34c2477b6a1346c73c0db075b0027566e5525faa Mon Sep 17 00:00:00 2001 From: Cloud IX Team Date: Wed, 17 Jun 2026 13:14:14 -0700 Subject: [PATCH] Decouple security agent skills to third_party. PiperOrigin-RevId: 933885045 --- skills/cloud/security-iam-analyzer/SKILL.md | 210 ++++++++++++++++++ .../cloud/security-remediation-draft/SKILL.md | 208 +++++++++++++++++ .../references/presentation_template.md | 26 +++ skills/cloud/security-scc-query/SKILL.md | 161 ++++++++++++++ .../references/finding_schema.md | 36 +++ 5 files changed, 641 insertions(+) create mode 100644 skills/cloud/security-iam-analyzer/SKILL.md create mode 100644 skills/cloud/security-remediation-draft/SKILL.md create mode 100644 skills/cloud/security-remediation-draft/references/presentation_template.md create mode 100644 skills/cloud/security-scc-query/SKILL.md create mode 100644 skills/cloud/security-scc-query/references/finding_schema.md diff --git a/skills/cloud/security-iam-analyzer/SKILL.md b/skills/cloud/security-iam-analyzer/SKILL.md new file mode 100644 index 0000000000..0ed84320df --- /dev/null +++ b/skills/cloud/security-iam-analyzer/SKILL.md @@ -0,0 +1,210 @@ +--- +name: security-iam-analyzer +description: >- + Analyzes IAM policies, service accounts, and policy bindings to detect and mitigate excessive or troublesome permissions on Google Cloud. Use when identifying which roles and permissions present security risks, listing IAM policy bindings for a service account, or querying IAM policy recommender. Do not use when querying general SCC findings (use security-scc-query), drafting non-IAM remediations (use security-remediation-draft), or editing local build configurations. +--- + + + + +# Security IAM Analyzer Skill + +This skill guides the agent in identifying service accounts with excessive +permissions, analyzing assigned roles, querying IAM policy recommenders, and +executing remediation plans (Remove Role, Replace Role, or Custom Role +Creation). + +## 3-Tier Consent Gate + +* **Tier R (Read-Only)**: Searching IAM policies, describing service accounts, + listing recommendations or insights. +* **Tier M (Mutating)**: Creating custom roles, adding or removing + project-level or organization-level IAM bindings. +* **Tier D (Destructive)**: None. + +## Execution Rules & Constraints + +1. **Zero-Speculation Gating**: + * The project ID and service account email MUST be explicitly provided in + the user's initial request. You MUST NOT speculate or guess them. + * You MUST NOT attempt to run any gcloud commands (such as gcloud config + get-value project, gcloud projects list, or gcloud iam service-accounts + list) to discover or guess them if they are missing from the request. + * If the project ID or service account email is missing from the user + request, you MUST immediately halt execution and ask the user to provide + them. +2. **NEVER search the workspace or codebase for configuration or resource + details**: + * All project IDs, service account emails, IAM policies, role definitions, + recommendations, and finding details MUST come strictly from the user's + prompt or from successfully executed read-only Google Cloud diagnostic + commands. + * You **MUST NOT** use any workspace search or codebase query tools + (including `code_search`, `grep`, `grep_search`, `find`, or custom + Python/bash scripts) to locate project IDs, service account emails, role + names, finding details, or configs. + * You **MUST NOT** access, read, or search any files in the workspace + ending in `.yaml`, `.yml`, or containing `EVAL` (such as `EVAL.yaml`), + as they contain test case definitions. +3. **No Recommendations Handling**: + * If no recommendations (REMOVE_ROLE or REPLACE_ROLE) and no recommender + insights are available for the service account, you **MUST** stop and + report to the user that no active IAM recommendations or insights could + be found for this service account, and halt execution. Do NOT attempt to + guess permissions or create custom roles without active + recommendations/insights. +4. **Terminal Command Failure**: + * If any read-only Google Cloud diagnostic command or tool execution fails + (returns non-zero exit code, permission denied, authentication error, + command not found, timeout, or any tool failure), you **MUST** + immediately treat it as a terminal failure, halt all execution, and + notify the user. + * You **MUST NOT** attempt to troubleshoot, retry, recover, switch active + accounts, list credentials, search the workspace, or execute fallback + search/discovery loops. + * You **MUST NOT** execute any shell scripts, bash scripts, or bash loops + (such as trying to run commands under bash or other shells) to + troubleshoot, retry, or recover from the failure. +5. **Mutating Actions Consent (Tier M)**: + * All remediations that modify IAM policies (e.g. adding roles, removing + roles, creating custom roles) are Tier M. + * You **MUST** format the proposed remediation plan showing the exact + roles to be added or removed, and the exact commands to be executed, and + request the user's explicit approval. + * You **MUST NOT** execute any mutating command (including role creation, + binding removal, or binding addition) in the same turn that you propose + the remediation plan. You **MUST** halt execution immediately after + proposing the plan and asking for approval. + * When execution is resumed, you **MUST** inspect the preceding message + for explicit, positive user consent (e.g., "yes", "approve", "proceed"). + * An empty message, a system message, or a continuation prompt without + explicit positive approval does NOT constitute consent. You **MUST NOT** + execute any mutating commands on such continuations; instead, you must + repeat your request for explicit approval and halt execution again. +6. **No Manual Waiting via Timers**: + * The system automatically notifies you and resumes execution when + background tasks (such as gcloud commands) complete. + * You **MUST NOT** call the schedule tool or create timers to check on + command status, as this causes unnecessary timeouts. +7. **MCP Tool Call Prohibition**: + * You **MUST NOT** call or use any MCP search or knowledge tools, + including but not limited to + `google-developer-knowledge/search_documents`, `get_documents`, + `answer_query`, or other lazy-loaded or eager MCP tools. + * All external documentation, Web, or MCP search queries are strictly + prohibited during the execution of this skill. + +## Execution Workflow + +### Step 1: Resolve Project ID + +The user request might provide the project display name (e.g., "test-project") +instead of the project ID. You MUST first resolve it to the correct GCP project +ID: + +```bash +gcloud projects list \ + --filter="name={project_id}" \ + --format="value(projectId)" +``` + +If this returns a resolved project ID, use it as the `{project_id}` for all +subsequent commands. Otherwise, use the original `{project_id}` provided in the +request. + +### Step 2: Query Policy Bindings + +To identify where the service account holds permissions across the project, run: + +```bash +gcloud asset search-all-iam-policies \ + --scope="projects/{project_id}" \ + --query="policy:\"serviceAccount:{sa_email}\"" \ + --format="json" +``` + +* **Edge Case**: If this returns empty, the service account might have been + deleted. Verify its existence: + + ```bash + gcloud iam service-accounts describe {sa_email} + ``` + + If this command fails with a `NOT_FOUND` error, inform the user that the + service account is already deleted and the finding is resolved. + +### Step 3: Identify Problematic Roles + +Examine the policies returned in Step 2. Match the service account's assigned +roles against `{troublesome_permissions}` to determine which roles grant those +permissions. + +### Step 4: Query IAM Recommender + +Query active recommendations to find the safest fix. + +1. **Search for REMOVE_ROLE recommendations**: + + ```bash + gcloud recommender recommendations list \ + --recommender=google.iam.policy.Recommender \ + --location=global \ + --project="{project_id}" \ + --filter="stateInfo.state=\"ACTIVE\" AND content.overview.member=\"serviceAccount:{sa_email}\" AND recommenderSubtype=\"REMOVE_ROLE\"" \ + --format="json" + ``` + +2. **Search for REPLACE_ROLE recommendations** (fallback if no REMOVE_ROLE + recommendation exists): + + ```bash + gcloud recommender recommendations list \ + --recommender=google.iam.policy.Recommender \ + --location=global \ + --project="{project_id}" \ + --filter="stateInfo.state=\"ACTIVE\" AND content.overview.member=\"serviceAccount:{sa_email}\" AND recommenderSubtype=\"REPLACE_ROLE\"" \ + --format="json" + ``` + +### Step 5: Formulate and Execute Remediation Plan + +Present the feasible plans to the user. Do not perform any mutating action +without explicit approval. You MUST propose the plan and request approval, and +you MUST NOT execute any mutating commands in the same turn or on an empty +resume/system continuation. + +#### Plan A: Remove Role + +If a `REMOVE_ROLE` recommendation is active and targets a role containing +troublesome permissions: + +1. Add new roles with lesser privileges (if recommended). +2. Remove the excessive role. + +#### Plan B: Replace Role + +If a `REPLACE_ROLE` recommendation is active: + +1. Add the new roles suggested by the recommendation. +2. Remove the old excessive roles. +3. *Safety Note*: Add new roles BEFORE removing old ones to prevent service + disruption. + +#### Plan C: Create Custom Role + +If recommender insights exist but no recommendations are available, and the +exercised/inferred permissions do not include the troublesome permission: + +1. Create a custom role with all required permissions: + + ```bash + gcloud iam roles create {role_id} \ + --project="{project_id}" \ + --title="{role_title}" \ + --permissions="{permissions_comma_separated}" \ + --stage="GA" + ``` + +2. Bind the custom role to the service account. + +3. Remove the old excessive roles. diff --git a/skills/cloud/security-remediation-draft/SKILL.md b/skills/cloud/security-remediation-draft/SKILL.md new file mode 100644 index 0000000000..f0b794d79d --- /dev/null +++ b/skills/cloud/security-remediation-draft/SKILL.md @@ -0,0 +1,208 @@ +--- +name: security-remediation-draft +description: >- + Formulates, summarizes, and drafts remediation options for Toxic Combination security issues. Covers business impact synthesis, extraction of exposed resources, and routing to specialized remediation paths (Public Bucket, User Managed Key, IAM Troublesome Permissions, or Public Instance). Use when triaging Toxic Combinations, summarizing attack paths, and presenting remediation choices. Don't use for querying SCC findings (use security-scc-query), analyzing service account IAM permissions (use security-iam-analyzer), or executing changes directly. +--- + + + + +# Security Remediation Draft Skill + +This skill guides the agent in identifying risks, synthesizing business impact, +formatting findings, and preparing structured remediation choices for Toxic +Combination security issues on Google Cloud. + +## 3-Tier Consent Gate + +* **Tier R (Read-Only)**: Analyzing and summarizing finding data, attack + paths, and resource configurations. +* **Tier M (Mutating)**: Drafting terraform config or gcloud commands for + remediation. No commands should be executed without explicit user + confirmation. +* **Tier D (Destructive)**: None. + +## Execution Rules & Constraints + +1. **Zero-Speculation Gating**: + * You **MUST NOT** speculate, guess, or use any placeholder or hardcoded + IDs, resource names, bucket names, key IDs, or service account emails. + All values used MUST come directly from the user's input context or the + output of a successfully executed read-only diagnostic command. + * You **MUST NOT** run any Google Cloud diagnostic commands if the + parameters needed to draft the remediation (such as project ID, bucket + ID, service account email, firewall rules, or troublesome permissions) + are already present in the user prompt or input context. + * You **MUST NOT** call any MCP search or knowledge tools (such as + `google-developer-knowledge/search_documents` or other lazy-loaded MCP + tools) under any circumstances, as they are disabled in this + environment. + * If any critical context parameter (e.g. project ID, bucket ID) is + missing, halt execution and ask the user to provide it. + * If the finding payload or context is missing the `nextSteps` field or if + it is empty/null, you **MUST NOT** run any Google Cloud diagnostic + commands, query SCC, or search the workspace to find it or to retrieve + other missing parameters (such as service account emails or firewall + rules). + * You **MUST** immediately halt and ask the user to provide the missing + next steps or parameters, or propose a generic fallback remediation + option based on the category without executing or drafting specific + commands. + * If any read-only Google Cloud diagnostic command, delegated subagent + analysis, tool execution, or command fails, errors, or times out + (including **permission prompt timeouts** and **MCP tool + connection/Forbidden errors**), you **MUST** immediately treat it as a + terminal failure, halt all execution, and notify the user. You **MUST + NOT** attempt to troubleshoot, retry, recover, or call `schedule` or + other tools to wait. + * Under no circumstances should you run queries in a loop, search + workspace files, or run global search/list commands (such as `gcloud scc + findings list`, `gcloud scc findings group`, `gcloud asset + search-all-resources`, or `gcloud asset search-all-iam-policies`) to + guess or find missing payload fields or resource parameters. +2. **NEVER search the workspace or codebase for finding or resource details**: + * All SCC findings, toxic combinations, and active resource metadata + reside strictly in the cloud or in the provided user prompt. + * You **MUST NOT** use any workspace search or codebase query tools + (including `code_search`, `grep`, `grep_search`, `find`, or custom + Python/bash scripts) to locate finding details, resource definitions, + category behaviors, logs, service accounts, project IDs, or test + specifications. Running `code_search` or reading workspace files to find + mock service accounts, project IDs, or finding details is strictly + forbidden and constitutes cheating. + * You **MUST NOT** access, read, or search any files in the workspace + ending in `.yaml`, `.yml`, or containing `EVAL` (such as `EVAL.yaml`), + as they contain test case definitions. Accessing these files constitutes + an integrity violation. +3. **Remediation Action Gating**: + + * You **MUST** present the identified remediation paths to the user as + clear, distinct choices. + * You **MUST NOT** unilaterally select a single remediation path if + multiple distinct options are available, OR draft multiple configuration + remediations, without the user's explicit confirmation or selection, + **UNLESS**: + 1. The user prompt explicitly requests multiple options, e.g., using + plural words like "options", "remediations", or "all options". + 2. The `nextSteps` field in the finding payload or context lists + multiple alternative remediation paths or commands (e.g., separated + by "or" or listed as bullet points). In either of these cases, you + **MUST** draft remediations for **all** identified options/paths at + once without halting to ask the user to select. + +4. **Handling Missing nextSteps**: + + * If the input finding payload does not contain a `nextSteps` field, or if + the `nextSteps` field is null or empty, you **MUST** detect this missing + information. + * You **MUST** immediately halt and ask the user to provide the next steps + or the specific resource parameters. + * You **MUST NOT** run any Google Cloud diagnostic commands, query SCC, or + search the workspace/codebase to try to find the missing details or + parameters. + * You may propose a generic, non-executable fallback remediation option + based on the category (e.g., advising to restrict firewall rules for + public VMs), but you must still halt and ask the user for the specific + parameters needed to draft the commands. + +5. **Strict Prohibition on Mutating Commands**: + + * You **MUST NOT** run or execute any mutating Google Cloud commands under + any circumstances (such as `gcloud ... update ...`, `gcloud iam ...`, + `gcloud storage ... update`, or any command that writes, modifies, or + updates Google Cloud resource configurations or states). + * Your role is strictly to **draft** the remediation. You must never + attempt to apply or execute the modifications directly on the live + infrastructure or resources. + +## Execution Workflow + +### Step 0: Gating Check for nextSteps and Parameters + +Before taking any other actions or running any commands: + +1. Check if the input finding payload contains a non-empty `nextSteps` field. +2. If `nextSteps` is missing, null, or empty, and you do not have the required + resource parameters (e.g. project ID, bucket ID) present in the prompt: + - Do NOT run any gcloud or diagnostic commands. + - Do NOT run any search or directory list commands. + - Immediately halt and formulate the finding summary using the template + (with generic fallback options based on the category) and ask the user + to provide the missing details using the `ask_question` tool. + - Stop execution here. + +### Step 1: Risk Factor Analysis + +Analyze the attack path vector data to identify which of the following risk +factors are present: + +1. **Publicly Exposed Bucket**: GCS bucket allowing public read or write access + (`allUsers` or `allAuthenticatedUsers`). +2. **User Managed Key**: Service account using user-managed keys that could be + leaked or compromised. +3. **IAM Troublesome Permissions**: Service account with highly permissive or + risky roles/permissions (e.g. `iam.serviceAccounts.actAs`). +4. **Publicly Exposed Instance**: VM instances with external IP addresses and + permissive firewall rules. + +### Step 2: Context and Parameter Extraction + +Extract the specific context required to formulate the remediation plan: + +* **nextSteps**: Extract the `nextSteps` field if available. If missing, + follow the "Handling Missing nextSteps" rule. +* **For Public Buckets**: Extract the `bucket_id` of the exposed GCS bucket. +* **For User Managed Keys**: Extract the `key_name` of the service account + key. +* **For IAM Troublesome Permissions**: + * Find the service account's email (`service_account_email`) and its + `project_id`. + * Compile the specific risky permissions (e.g., + `iam.serviceAccounts.actAs`, `storage.objects.list`) into + `troublesome_permissions`. +* **For Public Instances**: Extract the firewall rules (`firewall_rules`) that + expose the instance. + +### Step 3: Business Impact Synthesizing + +Formulate the `finding_summary` by explaining the business impact of this Toxic +Combination (e.g., "A publicly exposed compute instance has software +vulnerabilities and can assume a highly privileged service account, potentially +allowing an attacker to read sensitive GCS buckets."). + +### Step 4: Presentation Formatting + +Format the summary exactly as shown in +[presentation_template.md](references/presentation_template.md). + +### Step 5: Remediation Action Routing + +Depending on whether a path has been pre-selected or multiple options need to be +drafted: + +* **If multiple options are requested/provided** (e.g., in the user prompt or + `nextSteps`): Draft the remediation configurations for all requested options + in parallel (e.g., draft the command to remove public members AND draft the + command to enable public access prevention). +* **If a specific path is selected by the user** (or specified in the prompt): + Route directly to that remediation path. +* **Otherwise**: Present the identified risk factors as choices to the user, + and wait for their selection before routing. + +Route the remediation drafting as follows: + +* **Public Bucket Remediation**: Pass `bucket_id` and `finding_summary` to + draft a bucket policy update (e.g., removing public members). +* **User Managed Key Remediation**: Pass `key_name` and `finding_summary` to + draft a key rotation or deletion plan. +* **IAM Troublesome Permissions**: You **MUST** use the `invoke_subagent` tool + with `TypeName="security-iam-analyzer"` to analyze and remediate this + finding. Before calling `invoke_subagent`, you **MUST** read the relative + path of the skill file at + `third_party/skills/skills/cloud/security-iam-analyzer/SKILL.md` using + `view_file` first to understand the subagent's expected execution loop. You + **MUST NOT** formulate the remediation commands yourself, and you **MUST + NOT** delegate this task to generic research subagents (such as + `research-google`). +* **Public Instance Remediation**: Pass `firewall_rules` and `finding_summary` + to draft firewall rule modifications to isolate the instance. diff --git a/skills/cloud/security-remediation-draft/references/presentation_template.md b/skills/cloud/security-remediation-draft/references/presentation_template.md new file mode 100644 index 0000000000..04dbef6885 --- /dev/null +++ b/skills/cloud/security-remediation-draft/references/presentation_template.md @@ -0,0 +1,26 @@ +# Toxic Combination Presentation Template + +When presenting the triaged Toxic Combination, use this exact format: + +-------------------------------------------------------------------------------- + +I have analyzed a high-severity issue from Security Command Center regarding a +**Toxic Combination** in {project_name}. + +{finding_summary} + +**Finding Details:** + +- **Finding:** {finding_display_name} +- **Resource:** {resource_id} +- **Location:** {location} +- **Organization ID:** {org_id} +- **Attack Path Vector:** {attack_path_vector} + +**The following high value resources are exposed:** + +Resource display name | Resource value | Resource type | Project / Org +:-------------------- | :------------- | :-------------- | :--------------- +{resource_name} | 🔴 High | {resource_type} | {project_or_org} + +-------------------------------------------------------------------------------- diff --git a/skills/cloud/security-scc-query/SKILL.md b/skills/cloud/security-scc-query/SKILL.md new file mode 100644 index 0000000000..2e3e5ad505 --- /dev/null +++ b/skills/cloud/security-scc-query/SKILL.md @@ -0,0 +1,161 @@ +--- +name: security-scc-query +description: >- + Queries and retrieves active security findings or toxic combinations from Google Cloud Security Command Center (SCC). Use when retrieving details for a security finding by its name, validating finding scope (e.g., verifying findingClass is TOXIC_COMBINATION), or fetching finding details for triage. Don't use for drafting remediation configurations (use security-remediation-draft), analyzing service account IAM permissions (use security-iam-analyzer), or executing resource changes. +--- + + + + +# Security Command Center (SCC) Query Skill + +This skill provides guidelines and gcloud CLI command patterns for retrieving +and querying security findings and toxic combinations from Google Cloud Security +Command Center (SCC). + +> [!IMPORTANT] **CRITICAL GOTCHA**: There is NO `gcloud scc findings describe` +> command. Any attempt to run it will fail with `Invalid choice: 'describe'`. To +> describe or retrieve details for a specific finding by its name, you MUST use +> `gcloud scc findings list` with a filter on `name`. + +## 3-Tier Consent Gate + +* **Tier R (Read-Only)**: Listing active findings, retrieving finding details, + and fetching attack path simulation metadata. +* **Tier M (Mutating)**: None. This skill is strictly read-only. +* **Tier D (Destructive)**: None. + +## When to Use + +* To retrieve the detailed JSON representation of a Security Command Center + finding using its unique finding name. +* To list active findings or toxic combinations in a project or organization. +* To retrieve the attack path simulation (APS) details embedded in toxic + combination findings. + +## Execution Rules & Constraints + +1. **Zero-Speculation Gating**: + * You **MUST NOT** speculate, guess, or use any placeholder or hardcoded + IDs for Project, Organization, Folder, Source, or Finding. Every ID used + MUST come directly from the user's prompt or context. + * If the project ID, organization ID, or folder ID is missing or not + provided in the user's prompt or context, you **MUST** halt execution + immediately and ask the user to provide the correct project, + organization, or folder ID. + * You **MUST NOT** attempt to execute any commands, checks, or searches to + discover the missing IDs. This includes, but is not limited to: + * Running configuration checks like `gcloud config list` or `gcloud + auth list`. + * Running discovery or list commands like `gcloud projects list` or + `gcloud organizations list`. + * Searching workspace files, environment variables, or logs. +2. **NEVER search the workspace for finding details**: + * All SCC findings and toxic combinations reside strictly in the cloud. + You **MUST NOT** attempt to search the workspace files (using `grep`, + `grep_search`, `find`, or any python scripts) under any circumstances. + * If the user specifies a unique finding name in their request, and the + `gcloud scc findings list` command filtered by that name returns an + empty result, you **MUST** immediately stop and report to the user that + the specified finding could not be found. You **MUST NOT** attempt to + list all findings in the organization/project or ask the user to choose + from other findings. +3. **Ambiguous or Missing Finding Name**: + * If the user asks for details of the active finding in a + project/organization but does not specify the unique finding name, you + should list the active findings. + * If multiple findings are provided in the user's prompt or context, or if + multiple findings are returned by the list command, you **MUST NOT** + unilaterally pick one to describe, nor attempt to retrieve details for + multiple findings. You **MUST** immediately halt execution and ask the + user to specify which finding name they want details for. + * If the list command returns **zero findings** (empty result), you + **MUST** immediately stop and report to the user that no active findings + were found in the specified project/organization. You **MUST NOT** + search the workspace or try to find it elsewhere. +4. **Do NOT verify or describe attack path resources**: + + * This skill is strictly for retrieving and extracting details *from the + SCC finding payload itself*. + * You **MUST NOT** attempt to run any commands to describe, verify, or + query the actual GCP resources (such as GCS buckets, service accounts, + VMs, or IAM policies) mentioned in the finding's attack path. + * Resource analysis must be delegated to other skills (like + `security-iam-analyzer`) or skipped entirely if not explicitly requested + by the user. + +5. **Immediate Halt on Execution Errors**: + + * If any `gcloud` command fails due to permission, authorization, + authentication, configuration, or connectivity issues (for example, + receiving `PERMISSION_DENIED`, `IAM_PERMISSION_DENIED`, credential + expiration, or API endpoint connection timeouts), you **MUST** halt + execution immediately. + * You **MUST NOT** attempt to troubleshoot, resolve, or search for + credentials/configs. Specifically, do not: + * Search the workspace or look for local configuration/credentials + files. + * Query gcloud configuration or authentication states (e.g., `gcloud + config ...` or `gcloud auth ...`). + * Enter any debugging or diagnostic loops (like running `grep`, + `find`, or custom scripts). + * Report the failure and the verbatim error message from the failed + command to the user immediately. + +## Execution Workflow + +### Step 1: Extract and Validate Finding Name + +The agent must expect a `finding_name` (e.g. +`organizations/{org_id}/sources/{source_id}/findings/{finding_id}`) to proceed. +If the `finding_name` is missing from the context, list the active findings +first (using the workflow below), and if multiple findings are returned, ask the +user to specify which one they want details for. + +### Step 2: Retrieve Finding Details + +Retrieve the finding details by listing findings under the organization or +source parent, filtered by the unique finding name. + +* **Command Pattern**: + + ```bash + gcloud scc findings list {parent} \ + --filter="name=\"{finding_name}\"" \ + --location=global \ + --format="json" + ``` + + * `{parent}`: The organization ID (e.g. `organizations/{org_id}`) or + source name (e.g. `organizations/{org_id}/sources/{source_id}`) + extracted from `{finding_name}`. + * `{finding_name}`: The full finding name resource path. + +* **Safety Warning**: NEVER run `gcloud scc findings describe {finding_name}`. + +### Step 3: Validate Finding Scope + +Inspect the retrieved finding JSON payload: + +1. **Finding Class**: Confirm the `findingClass` is `TOXIC_COMBINATION`. If not + `TOXIC_COMBINATION` and the finding name does not contain `/issues/`, inform + the user that automated triage is currently only supported for Toxic + Combinations. +2. **Parent**: Confirm the parent resource starts with `organizations/`. If the + parent starts with `projects/` or `folders/`, inform the user that automated + triage is only supported for organization-level findings. + +### Step 4: Extract Attack Path details + +For `TOXIC_COMBINATION` findings, the attack path is described in the +`attackExposure` object inside the finding details. + +1. Verify the `attackExposure` field is present and has a `score > 0`. +2. Examine the attack path nodes and edges in the finding payload or referenced + `attackExposureResult` to identify exposed resources and attack + trajectories. + +## Reference Schema + +See [finding_schema.md](references/finding_schema.md) for the JSON structure of +a Security Command Center finding. diff --git a/skills/cloud/security-scc-query/references/finding_schema.md b/skills/cloud/security-scc-query/references/finding_schema.md new file mode 100644 index 0000000000..f4ecb99032 --- /dev/null +++ b/skills/cloud/security-scc-query/references/finding_schema.md @@ -0,0 +1,36 @@ +# SCC Finding Schema Reference + +This reference describes the common fields returned in the JSON payload of a +Security Command Center finding. + +```json +{ + "name": "organizations/{org_id}/sources/{source_id}/findings/{finding_id}", + "parent": "organizations/{org_id}", + "resourceName": "//compute.googleapis.com/projects/{project_id}/zones/{zone}/instances/{instance_name}", + "findingClass": "TOXIC_COMBINATION", + "category": "TOXIC_COMBINATION_PUBLIC_VM_WITH_EXCESSIVE_PERMISSIONS", + "state": "ACTIVE", + "severity": "CRITICAL", + "eventTime": "2026-06-16T17:41:31Z", + "createTime": "2026-06-16T17:41:31Z", + "attackExposure": { + "score": 0.85, + "attackExposureResult": "organizations/{org_id}/simulations/{sim_id}/attackExposureResults/{result_id}" + }, + "findingDetails": { + "description": "Publicly accessible instance with exploitable software vulnerability and the ability to assume service accounts" + } +} +``` + +## Field Explanations + +* `name`: The unique identifier for the finding. +* `parent`: The organization, folder, or project under which this finding is + grouped. +* `findingClass`: The high-level classification of the finding. Automated + triaging requires this to be `TOXIC_COMBINATION`. +* `state`: The current status of the finding. Typically `ACTIVE` or `MUTED`. +* `attackExposure`: Holds information about the computed exposure risk and + simulation result identifiers.