IAM Role Least-Privilege Review Prompt

Security engineers and cloud architects use this prompt to perform a structured, human-readable audit of a single IAM policy document against least-privilege principles. The core job-to-be-done is generating a detailed privilege analysis that identifies over-permissioned actions, unused permissions, wildcard resource risks, and missing condition keys, along with specific remediation recommendations. This prompt is designed to be integrated into a pre-deployment security review gate or a periodic access audit cycle, producing an artifact that can be attached to a security finding ticket and tracked to closure.

The ideal input is a complete IAM policy JSON document, such as an AWS IAM role policy, an Azure RBAC role definition, or a GCP IAM binding. The prompt expects the raw policy text and an optional [CONTEXT] block specifying the role's intended function, the services it interacts with, and the trust boundary. The output is a structured analysis, not a simple pass/fail verdict. It should enumerate specific actions that exceed the stated requirements, flag any use of "Resource": "*" without a compensating condition, and call out missing condition keys like aws:SourceIp or aws:RequestedRegion that could restrict blast radius. This level of detail makes the prompt useful for engineers who need to justify a remediation to an application team or an auditor.

This prompt is not a replacement for automated IAM analysis tools. Do not use it as a substitute for AWS IAM Access Analyzer, Azure Policy, or GCP Policy Intelligence, which provide continuous, policy-wide analysis across all roles in an account. Instead, use this prompt when you need a targeted, human-readable audit trail for a single high-risk role, or when you need to generate the narrative justification for a remediation that an automated tool has already flagged. It is also inappropriate for analyzing the effective permissions of a principal across multiple attached policies, as the prompt operates on a single policy document and cannot resolve the union of permissions from multiple policy attachments or group memberships. For that, use a policy simulator. Finally, never use the prompt's output as the sole authorization for a production change; all remediation recommendations must be reviewed by a human with context on the application's actual runtime behavior.

The following prompt template is designed to be copied directly into your AI orchestration layer, model API call, or evaluation harness. It accepts an IAM policy document and a set of business context variables, then produces a structured least-privilege analysis. Every square-bracket placeholder must be replaced with a concrete value before the prompt is sent to the model. Leaving a placeholder unresolved will cause the model to hallucinate or skip critical analysis steps.

textCopy
You are an IAM security reviewer performing a least-privilege audit on a cloud IAM role.

## INPUT
Role Name: [ROLE_NAME]
Attached Policies (JSON): [POLICY_DOCUMENTS]
Inline Policies (JSON): [INLINE_POLICIES]
Trust Policy (JSON): [TRUST_POLICY]
Last Used Data (JSON, optional): [LAST_USED_REPORT]

## CONTEXT
Workload Description: [WORKLOAD_DESCRIPTION]
Required Actions: [REQUIRED_ACTIONS]
Required Resources: [REQUIRED_RESOURCES]
Environment: [ENVIRONMENT]
Compliance Framework: [COMPLIANCE_FRAMEWORK]

## CONSTRAINTS
- Flag any permission not present in [REQUIRED_ACTIONS] as over-privileged.
- Flag any resource pattern containing "*" unless explicitly justified in [REQUIRED_RESOURCES].
- Flag any trust policy principal that is not an explicit account ID or known service.
- Flag any missing condition keys that would restrict source IP, VPC endpoint, or MFA.
- If [LAST_USED_REPORT] is provided, flag any permission unused for more than [UNUSED_THRESHOLD_DAYS] days.
- Do not recommend removing permissions that are required by AWS-managed service roles unless they are clearly unused.

## OUTPUT_SCHEMA
Return a JSON object with this exact structure:
{
  "summary": {
    "total_permissions": <number>,
    "over_privileged_count": <number>,
    "unused_count": <number>,
    "risk_level": "low" | "medium" | "high" | "critical"
  },
  "findings": [
    {
      "id": "F-<number>",
      "severity": "low" | "medium" | "high" | "critical",
      "category": "over-privileged" | "unused" | "wildcard-resource" | "missing-condition" | "trust-risk",
      "policy_name": "<string>",
      "statement_sid": "<string or null>",
      "permission": "<string>",
      "resource": "<string>",
      "finding": "<explanation>",
      "recommendation": "<specific fix>"
    }
  ],
  "remediation_plan": {
    "immediate_actions": ["<string>"],
    "short_term_actions": ["<string>"],
    "requires_architectural_change": <boolean>
  }
}

## EXAMPLES
<example>
Input: Role with s3:* on * resource, workload only needs GetObject on one bucket.
Output finding: F-1, critical, over-privileged, s3:*, *, "Role grants full S3 access to all buckets. Workload only requires s3:GetObject on arn:aws:s3:::app-bucket/*. Replace with scoped permission."
</example>

## INSTRUCTIONS
1. Parse all policy documents and flatten every Action and Resource.
2. Compare each permission against [REQUIRED_ACTIONS] and [REQUIRED_RESOURCES].
3. Cross-reference with [LAST_USED_REPORT] if provided.
4. Check every trust policy principal for overly broad trust.
5. Check for missing condition keys: aws:SourceIp, aws:SourceVpc, aws:MultiFactorAuthPresent.
6. Output only the JSON object. No markdown, no commentary.

Adaptation notes: Replace [POLICY_DOCUMENTS] with the full JSON of each attached policy, not just policy names. The model needs the complete Action, Resource, Effect, and Condition blocks to perform accurate analysis. If you don't have a last-used report, remove the [LAST_USED_REPORT] placeholder and the associated constraint bullet, or set [UNUSED_THRESHOLD_DAYS] to a value that makes sense for your environment (typically 90 days). The [COMPLIANCE_FRAMEWORK] field should contain a short identifier like SOC2, HIPAA, PCI-DSS, or NIST-800-53 to help the model prioritize condition key recommendations.

Validation before use: Before sending this prompt to production, run it against a known over-privileged test role and confirm the output JSON parses correctly, the finding count matches your manual count, and the risk_level field aligns with your internal severity rubric. If the model returns findings outside the JSON block, add a stronger output constraint or use a structured output API feature. For high-risk production roles, always route findings through a human reviewer before applying remediation, especially when the recommendation involves removing permissions from a role that serves live traffic.

This prompt is designed to be integrated into a CI/CD pipeline or a periodic security audit workflow, not as a one-off chat interaction. The implementation harness must treat the prompt as a deterministic analysis step that produces structured, machine-readable output suitable for downstream ticketing systems and compliance dashboards. The primary integration points are: a policy retrieval step that gathers the IAM policy document and CloudTrail event history, the prompt execution step that generates the privilege analysis, a validation step that enforces the output schema, and a routing step that sends high-severity findings for human review while auto-approving low-risk observations.

Start by building a policy retrieval adapter that accepts an IAM role ARN and returns a structured context object containing the inline and attached policies, trust relationships, permission boundaries, and a summary of recent API calls from CloudTrail (last 90 days). This adapter must resolve managed policy attachments to their full document bodies and normalize the Action, Resource, and Condition blocks into a consistent format before passing them into the prompt's [IAM_POLICY_DOCUMENT] and [CLOUDTRAIL_ACTIVITY] placeholders. For the [RISK_THRESHOLD] parameter, map your organization's severity levels (e.g., HIGH, MEDIUM, LOW) to the prompt's expected values and set a default of MEDIUM for automated runs. The [COMPLIANCE_FRAMEWORK] placeholder should be populated from a configuration file that maps your accounts to the relevant standards (e.g., SOC2, PCI-DSS, HIPAA) so the prompt can tailor its checks for wildcard resources and missing condition keys specific to each framework.

After the model returns a response, run a schema validator against the expected JSON output structure before any downstream action is taken. The validator must confirm that the findings array contains objects with the required fields (severity, finding_type, description, affected_permissions, recommendation, compliance_flag), that severity values are in the allowed enum, and that the summary object includes total_findings, critical_count, high_count, medium_count, and low_count. If validation fails, implement a retry loop with a maximum of 2 additional attempts, appending the validation error message to the prompt as feedback: The previous output failed schema validation with the following errors: [VALIDATION_ERRORS]. Please correct the JSON output. After 3 total failures, log the raw response and escalate to the security engineering team for manual review rather than silently dropping the analysis.

For findings classified as CRITICAL or HIGH, the harness must open a ticket in your issue tracker (Jira, ServiceNow, etc.) with the finding details, affected role ARN, and a link to the full analysis. For MEDIUM findings, add them to a security backlog for sprint planning. For LOW findings, log them to a compliance evidence store without blocking the pipeline. Implement a human approval gate that prevents automatic remediation of any finding involving iam:PassRole, sts:AssumeRole, or cross-account trust modifications—these must always require explicit security team sign-off. The harness should also maintain an audit log of every prompt execution, including the input policy hash, model version, output hash, validation status, and reviewer identity, so that compliance auditors can trace each least-privilege review from trigger to resolution.