Setup guide

Grants the read-only security posture calls the skill depends on: cloudtrail:DescribeTrails, ec2:DescribeSecurityGroups, iam:GenerateCredentialReport/GetCredentialReport, kms:GetKeyRotationStatus, config:Describe*, guardduty:List*, access-analyzer:ListAnalyzers.

↳ SecurityAudit deliberately excludes s3:GetObject, kms:Decrypt and ssm:GetParameter on secret values. Never add them for an audit; the skill records unreadable data as 'not verifiable' rather than reading it.

Supplies the broad List/Describe/Get coverage SecurityAudit omits, used for inventory, RDS, Auto Scaling, DynamoDB, AWS Backup, CloudFormation drift and CloudWatch alarm checks.

↳ If you must trim, keep only the service prefixes the skill actually calls: ec2, rds, autoscaling, dynamodb, backup, cloudformation, cloudwatch, logs, s3, elasticloadbalancing, ssm, organizations.

Baselines the resource inventory and computes tag coverage for Owner, Environment, Application and CostCenter in Step 2, which decides whether the audit is scoped per-workload or per-account.

↳ tag:GetResources is already read-only and cannot be narrowed by resource; add tag:GetTagKeys only if you also want key enumeration.

Produces the monthly spend breakdown by SERVICE dimension that every Cost Optimization finding is quantified against.

↳ Cost Explorer actions do not support resource-level restriction. The narrower control is to grant ce:GetCostAndUsage alone and omit ce:GetCostForecast and ce:GetReservationPurchaseRecommendation.

Returns AWS's own estimatedMonthlySavingsAmount for Compute Savings Plans, which the skill reports instead of hand-computing commitment savings.

↳ Omit if the engagement explicitly excludes commitment purchasing advice; the rest of the cost sweep still works.

Confirms in Step 7 that at least one Cost Anomaly Detection monitor exists, which is an Operational Excellence control.

Detects whether Compute Optimizer is Active before the skill relies on its recommendations, so it can fall back to raw CloudWatch metrics if enrollment is Inactive.

Provides the right-sizing evidence base for the Performance Efficiency pillar; the skill also calls GetEBSVolumeRecommendations, GetLambdaFunctionRecommendations, GetAutoScalingGroupRecommendations and GetRDSDatabaseRecommendations.

↳ Grant only the recommendation verbs for resource types in scope, e.g. drop GetLambdaFunctionRecommendations for a pure EC2 workload.

Measures quota headroom for ec2, lambda and vpc in the Reliability pillar; above 70% utilization becomes a finding.

↳ Pair with cloudwatch:GetMetricData on the AWS/Usage namespace if you want actual utilization rather than the quota ceiling alone.

Probes the support tier and, on Business/Enterprise Support, pulls the full Trusted Advisor check set used to cross-check cost and fault-tolerance findings.

↳ Add support:DescribeTrustedAdvisorCheckResult only if you want per-check results; the probe alone is enough to detect the tier. The AWS Support API is unavailable below Business Support regardless of IAM.

Confirms effective permissions before the skill escalates an IAM finding to Critical, since SCPs, permissions boundaries and resource policies can override a permissive-looking policy.

↳ Read-only simulation; it never evaluates against real resources or performs the action.

Determines in Step 1 whether the scope is a standalone account or an Organization payer plus members; absence throws AWSOrganizationsNotInUseException, which the skill treats as 'standalone'.

↳ Add organizations:ListAccounts only when the audit genuinely spans member accounts; otherwise this single describe is sufficient.

Lets the skill verify list prices against the AWS Price List API instead of quoting the stale figures baked into its cost model.

↳ Public pricing data; no account data is exposed. Safe to grant on Resource: *.

Optional Step 9 mutation that mirrors findings into the AWS Well-Architected Tool; also needs wellarchitected:ListLensReviewImprovements to read back improvement items.

↳ OMIT THIS BY DEFAULT. The audit is read-only; grant it only after explicit written approval, and prefer a separate elevated profile so the sweep itself cannot write.

Cause: Either the ce:* actions are missing from the supplemental inline policy, or — far more often — 'IAM user and role access to Billing information' is still deactivated in Billing Account settings, which blocks Cost Explorer for every non-root principal regardless of IAM.

Fix: Sign in as the root user, go to Billing and Cost Management > Account settings > IAM user and role access to Billing information > Edit > Activate IAM Access > Update, then re-run. Confirm the inline policy also lists ce:GetCostAndUsage.

Cause: Account-level S3 Block Public Access has never been configured. This is NOT a credential problem — it is the SEC-01 Critical finding the skill is looking for.

Fix: Do not 'fix' it during the audit. Record it as a Critical Security finding and hand back the aws_s3_account_public_access_block Terraform remediation. Only confirm the permission is real by checking that s3:GetAccountPublicAccessBlock is allowed (SecurityAudit grants it).

Cause: The target is a standalone account, not an Organization member or payer.

Fix: Expected and benign. Treat the scope as a single account and skip all member-account enumeration; note it in the report's scope section.

Cause: The account is on Basic or Developer Support. The AWS Support API and the full Trusted Advisor check set require Business or Enterprise Support.

Fix: Do not add IAM permissions — this is a subscription gate, not an authorization one. Record the support tier in the report and derive the equivalent checks manually from the direct service APIs the skill already calls.

Cause: The Region came from 'ec2 describe-regions --all-regions' but is an opt-in Region that is disabled for this account.

Fix: Either enable the Region under account menu > Account > AWS Regions, or drop --all-regions so only enabled Regions are enumerated. Record any Region you skipped so the report's Region list is honest.

Cause: Compute Optimizer enrollment was never completed, or was completed only for a different account in the Organization.

Fix: Run 'aws compute-optimizer get-enrollment-status' to confirm, then opt in from the Compute Optimizer console. If enrollment is Active but lists are empty, wait ~12 hours and meanwhile fall back to cloudwatch get-metric-statistics on AWS/EC2 CPUUtilization.

Cause: AWS_SESSION_TOKEN came from an assume-role or IAM Identity Center session that has passed its duration (often 1 hour by default). A full multi-Region sweep can outlive it.

Fix: Re-run 'aws sso login --profile wa-audit' or re-issue 'aws sts assume-role --duration-seconds 43200' (the role's MaxSessionDuration must be raised in IAM > Roles > WellArchitectedAudit > Summary > Edit to allow more than 1 hour).

Cause: Bad or rotated access keys, an AKIA key paired with a stale AWS_SESSION_TOKEN, or local system clock skew of more than 5 minutes (SigV4 rejects skewed signatures).

Fix: Unset AWS_SESSION_TOKEN when using a long-lived AKIA key, re-sync the system clock (w32tm /resync on Windows, chronyc makestep on Linux), and confirm the key is Active under IAM > Users > Security credentials.

Cause: SecurityAudit and ViewOnlyAccess were not both attached, or a Service Control Policy / permissions boundary on the account denies the action above the identity policy.

Fix: Verify both managed policies are attached, then run 'aws iam simulate-principal-policy --policy-source-arn <role-arn> --action-names ec2:DescribeInstances' to see whether an SCP or boundary is the actual denier, and record the check as verifiable:false if it cannot be resolved.

Cause: The all-Region sweep issues many describe/list calls in a short window and trips per-account API rate limits.

Fix: Ensure AWS_MAX_ATTEMPTS=10 and AWS_RETRY_MODE=adaptive are exported (the reference script sets both), and serialize the per-Region loop instead of fanning out. Never pass --no-paginate to compensate; that silently under-reports on large accounts.

Cause: AWS_PROFILE points at a profile name that has no matching section in ~/.aws/config, or the section was written as [wa-audit] instead of [profile wa-audit] in the config file.

Fix: In ~/.aws/config the header must be '[profile wa-audit]'; only ~/.aws/credentials uses the bare '[wa-audit]' form. Confirm with 'aws configure list-profiles'.

Cause: iam:GetCredentialReport is granted but the report was never generated, or generation is still in progress and the call raced it.

Fix: Run 'aws iam generate-credential-report' first, poll until State is COMPLETE, then re-run get-credential-report. On a genuine AccessDenied, record the identity checks as verifiable:false rather than as a pass.