/iam-helper-for-policy-management

name: iam-helper-for-policy-management
description: >-
  Streamlines the creation, modification, and management of IAM allow policies
  (v1) and deny policies (v2). Manages access control across Resource Manager
  resources (Organization, Folder, Project) and individual resources. Use when
  creating, updating, listing, or deleting IAM allow policies or deny policies.
  Don't use for access denial troubleshooting (use
  iam-helper-for-troubleshooting), temporary privileged access (use
  iam-helper-for-privileged-access-management), configuring VPC Service
  Controls, or managing network firewall rules.
metadata:
  category: Security

IAM Helper for Policy Management

Orchestrates the lifecycle and management of IAM allow and deny policies across IAM v1 (allow policies) and IAM v2 (deny policies).

--------------------------------------------------------------------------------

Core Concepts & Paradigms

IAM operates across two policy paradigms:

1. **IAM v1 (Allow Policies)**: Grants roles to principals (users, service accounts, groups, domains) on specific resources. Supports Resource Manager resources (organizations, folders, projects) as well as individual resources across supported Google Cloud services. 2. **IAM v2 (Deny Policies)**: Sets explicit organization-, folder-, or project-level guardrails that prevent specified principals from using designated permissions, regardless of any allow policies granted. Evaluated before allow policies.

--------------------------------------------------------------------------------

Workflow & Decision Tree

When receiving a policy management request, determine whether the operation is **Read-Only** or **Mutating**, and whether it targets **IAM v1 (Allow Policies)** or **IAM v2 (Deny Policies)**:

1. Read-Only Operations (Autonomous Execution)

Read-only actions include the following:

• **IAM v1 Allow Policies**: `get-iam-policy` on project/folder/organization,

or `gcloud iam list-testable-permissions //cloudresourcemanager.googleapis.com/projects/PROJECT_ID`.

• **IAM v2 Deny Policies**: `gcloud iam policies list` or `gcloud iam policies

get` with `--attachment-point` and `--kind=denypolicies`.

For read-only actions, execute the command autonomously to inspect state, and present the query results clearly to the user.

2. Mutating Operations (Plan & Confirm Protocol)

Mutating operations include the following:

• **IAM v1 Allow Policies**: `add-iam-policy-binding`,

`remove-iam-policy-binding`, or `set-iam-policy` across project, folder, organization, or resource levels (see [references/v1-allow-policies.md](references/v1-allow-policies.md)).

• **IAM v2 Deny Policies**: `create`, `update`, or `delete` deny policies on

attachment points (`cloudresourcemanager.googleapis.com/projects/PROJECT_ID`, `cloudresourcemanager.googleapis.com/folders/FOLDER_ID`, or `cloudresourcemanager.googleapis.com/organizations/ORG_ID`) using YAML/JSON policy files (see [references/v2-deny-policies.md](references/v2-deny-policies.md)).

For mutating operations, follow the **Plan & Confirm Protocol** below. **DO NOT** execute mutating commands autonomously without prior user approval.

--------------------------------------------------------------------------------

Execution & Safety Protocol

• **Plan and Confirm (No Autonomous Mutation)**: Mutating allow and deny

policy changes modify live security perimeters and access controls. You MUST NOT execute mutating `gcloud` commands directly via tool calls without explicit prior confirmation from the user. When asked to apply a mutating change, do the following: 1. **Formulate the Command**: Generate the exact, fully constructed `gcloud` command (including all parameters such as `--member`, `--role`, `--attachment-point`, `--kind=denypolicies`, and `--policy-file`). 2. **Warn of Impact & Propagation**: Issue a general warning that the change could impact access in a live environment and takes time to propagate across Google Cloud global infrastructure. 3. **Request User Confirmation**: Prompt the user for approval before applying the changes to the live environment.

• **Post-Execution Verification**: After the user approves and the mutating

policy change is executed, run the corresponding verification command (see [references/v1-allow-policies.md](references/v1-allow-policies.md) and [references/v2-deny-policies.md](references/v2-deny-policies.md) for exact verification steps) to verify that the active state matches expectations before reporting completion.

• **Security Guardrail (Public & Blanket Access Refusal)**: Never grant

`allUsers` or `allAuthenticatedUsers` basic roles (`roles/owner`, `roles/editor`, `roles/viewer`, `roles/admin`, `roles/writer`, and `roles/reader`) or broad permissions. Explicitly refuse blanket public access requests, explain the severe security risks of public project ownership/access, and propose scoped, least-privileged role bindings for specific authenticated identities instead.

--------------------------------------------------------------------------------

Supporting Links

• [IAM Overview](https://cloud.google.com/iam/docs/overview)
• [IAM Deny Policies](https://cloud.google.com/iam/docs/deny-overview)