iam-helper-for-privileged-access-management

Files (7)

• SKILL.md
• entitlement_template.yaml · assets/
• approver.md · references/
• attribution.md · references/
• requester.md · references/
• list_entitlements_hierarchy.sh · scripts/
• search_eligible_entitlements.sh · scripts/

SKILL.md (first lines)

# Privileged Access Manager (PAM)

This skill provides step-by-step guidance for planning, validating, and
executing Privileged Access Manager (PAM) entitlement CRUD operations, approval
workflow configurations, access elevations, and grant approval/denial workflows.

## Usage Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you
MUST read and follow the instructions in
[Usage Attribution](references/attribution.md).

## Table of Contents

*   [Core Concepts](#core-concepts)
*   [Approval Workflows & Max Request Duration](#approval-workflows)
*   [Safety & Confirmation Strategy](#safety-confirmation)
*   [Plan-Validate-Execute Pattern](#plan-validate-execute)
*   [Mode 1: Interactive Access Elevation](#mode-1)
*   [Mode 2: Standalone Entitlement CRUD](#mode-2)
*   [Mode 3: Approver Workflow](#mode-3)
*   [Supporting Links & Resources](#supporting-links)

## Core Concepts {#core-concepts}

Privileged Access Manager (PAM) replaces permanent or ambient IAM role
assignments with on-demand, time-bound, and audited access elevations. Rather than
appending permanent IAM policy bindings, PAM uses:

*   **Entitlements:** Configurations defining access scopes, eligible
    requesters, and approvers.
*   **Grants:** Short-lived requests created against entitlements to activate
    the entitlement's IAM roles.

### Privileged Access (`privilegedAccess`)

The `privilegedAccess` block in an entitlement defines the precise access scope that will be granted. An access scope comprises three essential components:
*   **Resource:** The target Google Cloud resource (Project, Folder, or Organization) where access is granted.
*   **Role Setup:** The IAM role (`roleBindings.role`) to be assigned.
*   **Condition:** (Optional) An IAM condition expression (`roleBindings.conditionExpression`) restricting when or where the role applies.

### Core Workflow

1.  Administrators create Entitlements.
2.  Requesters can then request Grants against these entitlements.
3.  If the entitlement is configured with approvals, then an approver must
    approve the requested grant.
4.  Once all necessary approval steps are completed, the grant is activated for
    the requested time.
5.  The grant automatically ends after the requested duration has elapsed, and
    the elevated access is removed.

## Approval Workflows & Max Request Duration {#approval-workflows}

### Approval Workflows (`approvalWorkflow`)

When sensitive environments require human approval before temporary access is
activated, configure the `approvalWorkflow` block in the entitlement YAML
manifest (`entitlement.yaml`).

```yaml
approvalWorkflow:
  manualApprovals:
    # Optional: requires approver to supply a justification string
    requireApproverJustification: true
    steps:
    - approvalsNeeded: 1
      approverEmailRecipients:
      - approver@example.com
      approvers:
      - principals:
        - user:db-lead@my-company.com  # or group:sre-leads@my-company.com
```

*   **When to include:** Include `approvalWorkflow` whenever the user prompt
    specifies that manual approval or an approver (user or group) is required.
*   **Outcome:** When a user requests a grant against an entitlement
    with `approvalWorkflow`, the grant transitions to `APPROVAL_AWAITED`.
    Requesters must await an Approver's decision (`Mode 3`).

### Max Request Duration (`maxRequestDuration`)

`maxRequestDuration` defines the maximum single access elevation timeframe a requester
may ask for when placing a grant request.

*   **Flexible Configuration:** Configure `maxRequestDuration` according to the
    user's specific request (e.g. `8 hours` / `28800s`, `1 hour` / `3600s`, `24
    hours` / `86400s`).
*   **Default Value:** If the user does NOT specify a maximum request duration,
    default to `4 hours` (`14400s`).
*   **YAML Syntax:** Always format `maxRequestDuration` as a string in seconds
    in the entitlement YAML (e.g., `"14400s"`, `"28800s"`).

## Safety & Confirmation Strategy {#safety-confirmation}

Adhere strictly to these workflow guards:

*   **Modifying / Destructive Executions (Create, Update, Delete, Approve, Deny, Revoke):** Always
    present a plain-text summary of the planned adjustments and prompt the user
    for explicit confirmation (Yes/No).
*   **Read-Only Inspections (List, Describe, Search):** Run autonomously without
    requesting confirmation.
*   **Batching Bash Commands (Reduce User Confirmations):** The host environment
    requires user approval for every individual shell tool call. To minimize
    confirmation popups, combine sequential read-only and lookup commands into a
    single compound bash script within one tool call (e.g., combining project,
    folder, and organization hierarchy audits into a single multiline
    execution).
*   **Anti-Loop Strategy:** If a command fails with a clear, actionable error,
    you may attempt to self-debug and retry. If the error is ambiguous, halt
    immediately, present the stderr output, and await user direction.

## Plan-Validate-Execute Pattern {#plan-validate-execute}

For all modifying actions (Mode 1 Step 3, Mode 2 Create, Update, Delete, Mode 3 Approve, Deny):

1.  **Plan:** Construct the proposed parameters or read the sample entitlement
    structure. (For entitlement creation, load and use the template:
    [assets/entitlement_template.yaml](assets/entitlement_template.yaml)).

From google/skills, Apache-2.0.

More from google/skills