Skip to content

AWS Permission Requirements for Runbooks CLI

AWS IAM permissions, policies, and Service Control Policy (SCP) considerations for each CloudOps-Runbooks command group.

Overview

CloudOps-Runbooks commands require specific AWS IAM permissions to function. This guide documents the minimum permissions for read-only operations, cost analysis, security assessments, and resource operations across single and multi-account AWS environments.

Scope

This guide covers: - Single-account operations: Inventory collection, security assessments, cost analysis - Multi-account operations: Organizations discovery, delegated admin operations (GuardDuty) - Billing account requirements: Cost Explorer, FinOps dashboards - Management account requirements: Organizations, control tower validation - SCP considerations: Service Control Policies that may block specific permissions

Key Principles

Principle Description
Least Privilege Each command group gets only the minimum permissions required
Multi-Account Design Separate profiles for different account roles (read-only, billing, management, operations)
SCP Awareness Service Control Policies may deny permissions despite IAM policy grants
Dry-Run Safety Most operations support --dry-run flag to preview changes without executing

Quick Reference: Permission Matrix

Command Group AWS Service APIs Minimum IAM Policy Multi-Account Profile SCP Risk
inventory collect EC2, S3, Lambda, IAM, CloudFormation, VPC, Auto Scaling, ElastiCache ReadOnlyAccess Standard account Low
inventory resource-explorer Resource Explorer 2 (resource:GetResources), EC2, S3, RDS, Lambda, Organizations ReadOnlyAccess + custom resource-explorer policy Standard account Low
inventory vpc EC2 (VPC APIs), CloudTrail, VPC Flow Logs ReadOnlyAccess Standard account Low
finops dashboard Cost Explorer (ce:GetCostAndUsage) CostExplorerReadOnly Billing account Low
finops optimize Cost Explorer, EC2, RDS, Lambda, Compute Optimizer ReadOnlyAccess + CostExplorerReadOnly Billing + Standard account Low
security assess IAM, CloudTrail, Config, CloudFormation, S3, Systems Manager SecurityAudit Standard account Low
security baseline IAM, CloudTrail, Config, VPC, Systems Manager, Secrets Manager SecurityAudit + custom write policy (for remediation) Standard account Medium
security deploy-guardduty GuardDuty, Organizations, IAM (create service-linked role) GuardDutyFullAccess + Organizations delegated admin Management account High ⚠️
cert inventory ACM, IAM, AWS Secrets Manager CertificateManagerReadOnly Standard account Low
cfat assess EC2, VPC, Organizations, Config, CloudTrail ReadOnlyAccess + Organizations Standard or management Low
validation benchmark Cost Explorer, SecurityHub, GuardDuty, Config ReadOnlyAccess + CostExplorerReadOnly Billing account High ⚠️
operate ec2 start|stop EC2 (ec2:StartInstances, ec2:StopInstances) Custom EC2 policy (write) Standard account Medium
operate s3 create-bucket S3 (s3:CreateBucket, s3:PutEncryption, s3:PutBucketVersioning) Custom S3 policy (write) Standard account Medium
operate vpc create-vpc EC2 (ec2:CreateVpc, ec2:CreateSubnet, etc.) Custom VPC policy (write) Standard account Medium
remediation remediate-findings SecurityHub, SSM, EC2, S3, IAM, Systems Manager Custom remediation policy + SecurityHubFullAccess Management account High ⚠️

Detailed Permission Requirements by Command Group

1. Inventory Collection (Read-Only Discovery)

Use Case: Discover AWS resources across 50+ services

Commands: inventory collect, inventory resource-explorer, inventory vpc

Required IAM Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:Describe*",
        "rds:Describe*",
        "s3:Get*",
        "s3:List*",
        "lambda:List*",
        "lambda:Get*",
        "iam:Get*",
        "iam:List*",
        "autoscaling:Describe*",
        "elasticache:Describe*",
        "cloudformation:List*",
        "cloudformation:Describe*",
        "organizations:Describe*",
        "organizations:List*",
        "cloudtrail:LookupEvents",
        "logs:Describe*",
        "logs:List*"
      ],
      "Resource": "*"
    }
  ]
}

AWS Managed Policy Alternative: ReadOnlyAccess (less granular but covers all required APIs)

Multi-Account Configuration

# Single account (most common)
export AWS_PROFILE=your-readonly-profile

# For Organizations discovery
export AWS_PROFILE=your-readonly-profile
runbooks inventory list-org-accounts --profile $AWS_PROFILE

SCP Considerations

Risk Details Mitigation
Low Read operations rarely blocked by SCPs Verify IAM user/role has explicit Allow before assuming SCP is the issue

2. FinOps Cost Analysis (Cost Explorer Read-Only)

Use Case: Cost analysis, spend trends, optimization recommendations

Commands: finops dashboard, finops optimize, finops scenario

Required IAM Policies

Primary Policy (Billing Account): 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "ce:GetCostForecast",
        "ce:GetReservationPurchaseRecommendation",
        "ce:GetSavingsPlansPurchaseRecommendation",
        "ce:ListCostAllocationTags",
        "cur:DescribeReportDefinitions",
        "cur:PutReportDefinition"
      ],
      "Resource": "*"
    }
  ]
}

Secondary Policy (Resource Account): 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:Describe*",
        "rds:Describe*",
        "lambda:List*",
        "elasticache:Describe*",
        "computeoptimizer:Get*",
        "computeoptimizer:Describe*"
      ],
      "Resource": "*"
    }
  ]
}

AWS Managed Policy Alternative: - Billing account: CostExplorerReadOnly - Resource account: ReadOnlyAccess

Multi-Account Configuration

# Cost analysis (requires billing account profile)
export AWS_BILLING_PROFILE=your-billing-readonly
runbooks finops dashboard --profile $AWS_BILLING_PROFILE

# Optimization recommendations (needs both profiles)
export AWS_PROFILE=your-resource-account-profile
export AWS_BILLING_PROFILE=your-billing-readonly
runbooks finops optimize --profile $AWS_PROFILE --billing-profile $AWS_BILLING_PROFILE

SCP Considerations

Risk Details Mitigation
Low Cost Explorer rarely blocked by SCPs Billing account may have different SCP rules; verify with Finance team
Medium CUR (Cost & Usage Report) may require explicit allow Request SCP exception if cur:PutReportDefinition is needed

Common Issues

ERROR: User is not authorized to perform: ce:GetCostAndUsage
Account: 123456789012
Reason: Cost Explorer is not available in member accounts

✓ Solution: Use AWS_BILLING_PROFILE (master/management account with billing access)
✓ Verify: AWS Organizations > Billing > Cost Management > Cost Explorer (enabled)

3. Security Assessment (SecurityAudit + Custom Write)

Use Case: Security baseline validation, compliance assessment, vulnerability scanning

Commands: security assess, security baseline, security remediate-findings

Read-Only Policy (Assessment Only)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:Get*",
        "iam:List*",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",
        "cloudtrail:LookupEvents",
        "config:Describe*",
        "config:Get*",
        "config:List*",
        "s3:GetBucketPolicy",
        "s3:GetBucketVersioning",
        "s3:GetBucketAcl",
        "s3:ListBucket",
        "ec2:Describe*",
        "rds:Describe*",
        "kms:Describe*",
        "secretsmanager:Describe*",
        "secretsmanager:List*"
      ],
      "Resource": "*"
    }
  ]
}

AWS Managed Policy Alternative: SecurityAudit

Write Policy (Remediation)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:UpdateAccountPasswordPolicy",
        "iam:UpdateAssumeRolePolicy",
        "s3:PutBucketVersioning",
        "s3:PutBucketPublicAccessBlock",
        "s3:PutEncryptionConfiguration",
        "ec2:ModifyInstanceAttribute",
        "cloudtrail:UpdateTrail",
        "config:PutConfigRule"
      ],
      "Resource": "*"
    }
  ]
}

Multi-Account Configuration

# Assessment only (read-only)
export AWS_PROFILE=your-security-audit-profile
runbooks security assess --profile $AWS_PROFILE

# Baseline with auto-remediation (requires write policy)
runbooks security baseline --profile $AWS_PROFILE --auto-remediate

SCP Considerations

Risk Details Mitigation
Low iam:Get* and cloudtrail:* rarely blocked Verify read permissions first
Medium Remediation write actions may be blocked Request SCP exception for specific actions before deployment
High Multi-account remediation requires delegated admin Use --dry-run to preview changes first

4. GuardDuty Deployment (Management Account)

Use Case: Deploy GuardDuty organization-wide with delegated admin

Commands: security deploy-guardduty

Required IAM Policies

Management Account Policy: 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "guardduty:Create*",
        "guardduty:Update*",
        "guardduty:List*",
        "guardduty:Describe*",
        "organizations:DescribeOrganization",
        "organizations:ListDelegatedAdministrators",
        "organizations:RegisterDelegatedAdministrator",
        "organizations:DeregisterDelegatedAdministrator",
        "iam:CreateServiceLinkedRole"
      ],
      "Resource": "*"
    }
  ]
}

AWS Managed Policy Alternative: GuardDutyFullAccess (on management account only)

Multi-Account Configuration

# Deploy organization-wide GuardDuty (management account only)
export AWS_MANAGEMENT_PROFILE=your-management-readonly
runbooks security deploy-guardduty --profile $AWS_MANAGEMENT_PROFILE

SCP Considerations

Risk Details Mitigation
HIGH ⚠️ GuardDuty actions are frequently denied by SCPs Action: Request explicit SCP exception before deployment
HIGH ⚠️ Member accounts need guardduty:CreateDetector allow Include in SCP exception request to Security team
Medium Service-linked role creation (iam:CreateServiceLinkedRole) may be blocked Verify IAM permissions in addition to SCP

SCP Exception Template

If you encounter GuardDuty SCP blocks, provide this template to your Security team:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowGuardDutyOrgDeployment",
      "Effect": "Allow",
      "Action": [
        "guardduty:Create*",
        "guardduty:Update*",
        "guardduty:List*",
        "guardduty:Describe*",
        "organizations:RegisterDelegatedAdministrator",
        "iam:CreateServiceLinkedRole"
      ],
      "Resource": "*"
    }
  ]
}

Troubleshooting

ERROR: guardduty:CreateDetector - explicit deny in service control policy
Account: 499201730520
Region: ap-southeast-1

❌ This means: SCP denies GuardDuty in member accounts
✓ Action: Contact Security/Cloud team with template above
✓ Workaround (temporary): Use `--skip-guardduty` flag if available

5. Certificate Management (Read-Only)

Use Case: Discover and track ACM, IAM, and Azure Key Vault certificates

Commands: cert inventory, security cert-inventory

Required IAM Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "acm:Describe*",
        "acm:List*",
        "acm-pca:Describe*",
        "acm-pca:List*",
        "iam:Get*",
        "iam:List*",
        "secretsmanager:Describe*",
        "secretsmanager:List*",
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "*"
    }
  ]
}

AWS Managed Policy Alternative: CertificateManagerReadOnly

Multi-Account Configuration

# Certificate inventory across all accounts
export AWS_PROFILE=your-readonly-profile
runbooks cert inventory --profile $AWS_PROFILE

# Multi-account certificate report
runbooks inventory collect --resources certificate --output json --profile $AWS_PROFILE

SCP Considerations

Risk Details Mitigation
Low Certificate read operations rarely blocked Verify Access Analyzer results for cross-account ACM access

6. Cloud Foundations Assessment Tool (CFAT)

Use Case: Assess AWS Cloud Foundations across 40+ checks

Commands: cfat assess

Required IAM Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:Describe*",
        "rds:Describe*",
        "s3:Get*",
        "s3:List*",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",
        "cloudtrail:LookupEvents",
        "config:Describe*",
        "config:Get*",
        "organizations:Describe*",
        "organizations:List*",
        "servicequotas:GetServiceQuota",
        "servicequotas:ListServiceQuotas",
        "cloudwatch:DescribeAlarms",
        "logs:Describe*"
      ],
      "Resource": "*"
    }
  ]
}

AWS Managed Policy Alternative: ReadOnlyAccess

Multi-Account Configuration

# Single account assessment
export AWS_PROFILE=your-readonly-profile
runbooks cfat assess --profile $AWS_PROFILE

# Multi-account assessment (via Organizations)
export AWS_PROFILE=your-readonly-profile
runbooks cfat assess --profile $AWS_PROFILE --include-member-accounts

SCP Considerations

Risk Details Mitigation
Low Read-only operations rarely blocked Verify Organizations and Config permissions in particular

7. Resource Operations (Write-Access Required)

Use Case: Perform operational tasks (start/stop instances, create buckets, etc.)

Commands: operate ec2 start, operate ec2 stop, operate s3 create-bucket, operate vpc create-vpc

EC2 Operations Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:StartInstances",
        "ec2:StopInstances",
        "ec2:RebootInstances",
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceStatus"
      ],
      "Resource": "arn:aws:ec2:*:*:instance/*",
      "Condition": {
        "StringEquals": {
          "ec2:ResourceTag/Environment": "production"
        }
      }
    }
  ]
}

S3 Operations Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:CreateBucket",
        "s3:PutBucketVersioning",
        "s3:PutEncryptionConfiguration",
        "s3:PutBucketPublicAccessBlock",
        "s3:PutBucketLogging"
      ],
      "Resource": "arn:aws:s3:::your-bucket-prefix-*"
    }
  ]
}

VPC Operations Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:CreateVpc",
        "ec2:CreateSubnet",
        "ec2:CreateRouteTable",
        "ec2:CreateRoute",
        "ec2:CreateInternetGateway",
        "ec2:AttachInternetGateway"
      ],
      "Resource": "*"
    }
  ]
}

Multi-Account Configuration

# Start instances (standard account)
export AWS_PROFILE=your-operations-profile
runbooks operate ec2 start --instance-ids i-1234567890abcdef0 --dry-run

# Create S3 bucket with encryption (standard account)
runbooks operate s3 create-bucket --bucket-name your-bucket-name --region ap-southeast-2 --dry-run

Safety Features

Feature Default Override
Dry-run Enabled (preview mode) --force to execute
Confirmation Required for destructive ops --force to skip
Logging All operations logged Audit trail in CloudTrail

SCP Considerations

Risk Details Mitigation
Medium ⚠️ SCPs often restrict StartInstances, StopInstances Use tags to limit scope (e.g., Environment=production)
Medium ⚠️ S3 bucket creation may be blocked Verify bucket naming restrictions and encryption requirements
High ⚠️ VPC creation frequently restricted in landing zones Use --dry-run first; coordinate with Cloud team

Multi-Account Profile Setup

Standard Multi-Account Architecture

# Master/Management Account (Billing + Organizations)
AWS_MANAGEMENT_PROFILE: Your-Org-Management-Admin
  Permissions: Organizations, GuardDuty delegated admin, Cost Explorer, Control Tower

# Billing Account (if separate)
AWS_BILLING_PROFILE: Your-Billing-ReadOnly-Access
  Permissions: Cost Explorer, Billing, CUR

# Standard Member Accounts (most resources)
AWS_PROFILE: Your-Readonly-Profile
  Permissions: ReadOnlyAccess, SecurityAudit

# Operations Account (if separate)
AWS_OPERATIONS_PROFILE: Your-Operations-Admin
  Permissions: Resource Explorer aggregator, cross-account discovery

Configure Environment Variables

# Recommended: Add to ~/.bashrc or ~/.zshrc
export AWS_MANAGEMENT_PROFILE=your-management-profile
export AWS_BILLING_PROFILE=your-billing-profile
export AWS_OPERATIONS_PROFILE=your-operations-profile
export AWS_PROFILE=your-standard-profile
export AWS_REGION=ap-southeast-2

# Verify configuration
aws sts get-caller-identity --profile $AWS_PROFILE
aws sts get-caller-identity --profile $AWS_MANAGEMENT_PROFILE
aws sts get-caller-identity --profile $AWS_BILLING_PROFILE

Known Permission Issues & Workarounds

Issue 1: GuardDuty Blocked by SCP

Symptom: 

ERROR: guardduty:ListDetectors - explicit deny in service control policy
Account: 499201730520
Region: ap-southeast-1
Impact: validation benchmark fails on GuardDuty checks

Root Cause: Service Control Policy denies GuardDuty actions in member accounts

Workaround (temporary): 

# Skip GuardDuty validation
runbooks validation benchmark --skip-guardduty --profile $AWS_PROFILE

Permanent Fix: Request SCP exception from Security team (see SCP Exception Template above)

Issue 2: Cost Explorer Not Available in Member Accounts

Symptom: 

ERROR: User is not authorized to perform: ce:GetCostAndUsage
Account: 987654321098
Reason: Cost Explorer is not available in this account

Root Cause: Cost Explorer API only available in master/management account

Solution: 

# Always use billing profile for cost operations
export AWS_BILLING_PROFILE=your-master-account-profile
runbooks finops dashboard --profile $AWS_BILLING_PROFILE

Issue 3: Organizations API in Member Accounts

Symptom: 

ERROR: You don't have permissions to access Organizations in this account

Root Cause: Organizations APIs only available in management account

Solution: 

# Use management account for org-wide operations
export AWS_MANAGEMENT_PROFILE=your-management-profile
runbooks inventory list-org-accounts --profile $AWS_MANAGEMENT_PROFILE
runbooks cfat assess --profile $AWS_MANAGEMENT_PROFILE --include-member-accounts

Issue 4: Cross-Account Resource Explorer Access

Symptom: 

ERROR: ResourceNotFoundException: Aggregator not found
Account: 123456789012

Root Cause: Resource Explorer aggregator not configured in operations account

Solution: 1. Verify Resource Explorer aggregator exists in operations account 2. Use standard profile if aggregator unavailable: 

export AWS_PROFILE=your-standard-profile
runbooks inventory resource-explorer --profile $AWS_PROFILE

Validation Checklist

Before deploying CloudOps-Runbooks, verify each permission requirement:

Read-Only Operations (inventory, security assess, cfat)

  • AWS profile configured with ReadOnlyAccess or equivalent
  • SecurityAudit policy attached for security commands
  • CostExplorerReadOnly policy attached for billing profile
  • Multi-account profiles defined for Organizations operations
  • Test: runbooks inventory collect --dry-run --profile $AWS_PROFILE succeeds

FinOps Operations

  • Billing profile has CostExplorerReadOnly policy
  • Cost Explorer enabled in AWS Billing console
  • Member account has ReadOnlyAccess for resource discovery
  • Test: runbooks finops dashboard --profile $AWS_BILLING_PROFILE shows cost data

Security Operations

  • Standard profile has SecurityAudit policy
  • Remediation policy attached for baseline with --auto-remediate
  • Management profile has GuardDutyFullAccess for deploy-guardduty
  • Test: runbooks security assess --profile $AWS_PROFILE completes
  • Test: runbooks security deploy-guardduty --profile $AWS_MANAGEMENT_PROFILE --dry-run shows plan

Resource Operations

  • Custom write policies for operate commands attached to appropriate profile
  • Resource tags match policies (e.g., Environment=production)
  • Approval process defined for destructive operations
  • Test: runbooks operate ec2 start --dry-run --profile $AWS_PROFILE shows what would execute

SCP Considerations Summary

Command Group SCP Risk Recommendation
inventory collect Low Standard permission set typically allows
finops dashboard Low Verify billing account SCP differs from member accounts
finops optimize Low Resource-level SCPs rarely block describe operations
security assess Low Audit policies usually permitted
security baseline Medium Remediation actions frequently restricted; get SCP exception
security deploy-guardduty High ⚠️ MANDATORY: Request SCP exception before deployment
cert inventory Low Cross-account ACM access may need exception
cfat assess Low Standard permission set typically allows
validation benchmark High ⚠️ GuardDuty may be blocked; use --skip-guardduty workaround
operate ec2|s3|vpc Medium Tag-based conditions help limit blast radius; coordinate with Cloud team

Additional Resources

Resource Link
AWS IAM Policies https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html
Service Control Policies https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html
Cost Explorer API https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-what-is.html
GuardDuty Permissions https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_organizations.html
CloudOps-Runbooks CLI ../cli/index.md
AWS Well-Architected Security Pillar https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/welcome.html

Action Items & TODOs

For Your AWS Team

  • Review command group matrix above and identify which commands your organization will use
  • Create IAM policies/roles for each profile (management, billing, standard, operations)
  • Test single-account read-only operations first (inventory collect, security assess)
  • Request SCP exceptions from Security team for GuardDuty if using security deployment features
  • Verify Cost Explorer is enabled in billing account before FinOps operations
  • Ensure IAM Identity Center (or IAM users) have correct permission sets attached
  • Document your multi-account profile setup in internal wiki or runbook
  • Create approval process for resource operations (operate ec2, operate s3, etc.)

For Security Team

  • Review SCP exception template for GuardDuty organization deployment
  • Define least-privilege policies for security assessment and remediation operations
  • Audit existing SCPs to identify blocks on read-only operations
  • Establish process for approving write-access policies (operate commands)

For FinOps Team

  • Enable Cost Explorer in billing account
  • Configure Cost & Usage Report (CUR) if advanced analysis needed
  • Set up cost anomaly detection in Cost Explorer
  • Define cost optimization thresholds for runbooks recommendations

Last Updated: 2026-04-01 CloudOps-Runbooks Version: 1.3.16+ AWS SDK: boto3 1.28+