# Official sources

Use this reference only when you need source grounding for AWS service behavior or the detailed source list.

## AWS documentation

Use these as starting points, not as proof of the user's live AWS state:
- https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/welcome.html
- https://docs.aws.amazon.com/wellarchitected/latest/framework/security.html
- https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html
- https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub-v2.html

## Grounding rule

Official documentation explains AWS service behavior. It does not prove the user's current account, Region, quota, resource configuration, IAM boundary, pricing, entitlement, or operational state. Prefer read-only AWS MCP or CLI evidence, repository evidence, or sanitized user-provided evidence for current-state claims.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:
- The Well-Architected Security Pillar focuses on protecting data, systems, and assets while delivering business value through risk assessments and mitigation strategies.
- Security review domains include identity and access management, detective controls, infrastructure protection, data protection, and incident response.

Sampled live evidence:
- Read-only API availability sampling reported `WellArchitected+GetWorkload` as `isAvailableIn` in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.
- Read-only product/API sampling also reported Security Hub and `SecurityHub+GetFindings` available in the sampled regions, but that does not prove detector coverage or finding remediation.

Review implications:
- Require IAM evidence, logging/detection coverage, network and workload protection, encryption/data-boundary controls, vulnerability posture, incident-response readiness, and exception tracking.
- Do not claim Well-Architected security readiness from questionnaire answers without live/repo evidence.

# Safety Checklist

Use before recommending any IAM policy change, network modification, KMS key action, or production-impacting security control.

## Non-negotiables

- Never ask users to paste access keys, session tokens, account IDs (unless sanitized), private keys, or customer data.
- Do not invent IAM policies, ARNs, resource names, quotas, account IDs, or live configuration state.
- Require explicit user approval before changes to IAM policies, SCPs, GuardDuty suppression rules, Security Hub controls, KMS key policies, or VPC security groups.
- Use official AWS documentation for service behavior — not training memory for specific API behavior that may have changed.
- Keep all recommendations least-privilege, reversible, and scoped to the stated workload boundary.
- Always distinguish between Detective controls (GuardDuty, Config) and Preventive controls (SCPs, Service Control Policies, org policies) — they are complementary, not interchangeable.

## Stress checks

- What can expose data to unauthorized principals?
- What can allow privilege escalation (PassRole, sts:AssumeRole, iam:CreateAccessKey)?
- What can disable audit logging (CloudTrail, Config, GuardDuty)?
- What can bypass encryption requirements?
- What compliance evidence is missing for the stated audit framework?

# Well-Architected Security Review Guide

Use this reference for AWS Well-Architected Framework Security Pillar reviews. In this repository, `aws-waf-security-review` means Well-Architected Framework review, not AWS Web Application Firewall configuration.

## What people get wrong

The lazy story is:

> Security review is checking IAM, encryption, and public access.

Wrong. Security posture is an end-to-end control system: identity, detection, infrastructure protection, data protection, vulnerability management, and incident response must all have evidence.

Common bad assumptions:

- No Security Hub finding means secure.
- Encryption enabled means data protection is complete.
- IAM managed policies are least privilege.
- CloudTrail exists, so detective controls are covered.
- Network private means workload secure.
- Incident response is ready because a runbook exists.

## Security-specific failure modes

- Multi-account boundaries, SCPs, permission boundaries, and break-glass controls are undefined.
- Static credentials, long-lived access keys, or broad cross-account trust remain active.
- Logging/detection coverage is incomplete across accounts, Regions, services, or data planes.
- KMS key policies, bucket policies, secrets, and data residency controls are unreviewed.
- Public exposure hides behind CDN/API/LB layers or misconfigured security groups.
- Findings have no owner, SLA, exception record, or verification after remediation.

## Minimum safe workflow

1. Confirm workload scope, accounts, Regions, data classification, regulatory context, and threat model.
2. Review identity first: human access, workload roles, federation, privilege boundaries, and break-glass.
3. Check detective controls: CloudTrail, Config, GuardDuty, Security Hub, IAM Access Analyzer, log retention, and alert routing.
4. Review infrastructure and data protection: network exposure, KMS, secrets, storage policies, backups, and vulnerability posture.
5. Check incident readiness: runbooks, contacts, containment paths, forensics logging, and game-day evidence.
6. Prioritize findings by exploitability, blast radius, business impact, and remediation safety.
7. Keep recommendations non-mutating unless a separate guarded operator workflow is invoked.

## Verification targets

- Organization/account structure, SCPs, permission boundaries, identity center/federation, MFA, and break-glass controls
- IAM policies, trust policies, access analyzer findings, unused access, and credential age
- CloudTrail, Config, GuardDuty, Security Hub, VPC Flow Logs, log destinations, retention, and alert paths
- public exposure evidence across ALB/API Gateway/CloudFront/S3/security groups/routes
- KMS key policies, secret rotation, S3/data-store encryption, backups, and data classification
- incident response runbooks, contacts, tabletop/game-day evidence, and exception register

## When to push back

Push back if the user asks to:

- claim security readiness from questionnaire answers alone
- ignore unsupported accounts, Regions, or log gaps
- widen IAM or network access as a shortcut
- hide critical findings behind generic “best practice” language
- treat encryption as proof of authorization or data minimization
- confuse this Well-Architected Framework review with AWS Web Application Firewall rules

# Workflow and Output Contract

Use this reference when performing the full WAF Security Pillar review or formatting the final assessment.

## Review domains

Work through these six security design principles in order:

1. **Strong identity foundation** — IAM credential types (root, IAM users, roles, federated), least-privilege policies, Permission Boundaries, SCPs, IAM Access Analyzer findings
2. **Traceability** — CloudTrail (all regions, log file validation, S3 MFA delete), AWS Config recording, Security Hub standards enabled, GuardDuty active
3. **Security at all layers** — VPC security groups (no 0.0.0.0/0 management ports), WAF rules, Shield Advanced, Network Firewall, EC2/container security
4. **Automation of security best practices** — IaC policy checks (cfn_nag, Checkov, tfsec), Binary Authorization/ECR scanning, Config Rules for detective controls
5. **Data protection** — KMS CMKs vs AWS-managed keys for regulated data, S3 encryption and Block Public Access, Secrets Manager, Macie PII discovery
6. **Incident response readiness** — IR playbooks, GuardDuty automated response, Security Hub Insights, Systems Manager Incident Manager runbooks

## Safe workflow

1. **Frame scope**: account IDs (sanitized), Organization structure, Regions in use, compliance drivers (PCI/HIPAA/SOC2)
2. **Gather evidence**: Security Hub score and standards, GuardDuty findings, CloudTrail status, IAM Access Analyzer findings
3. **Prioritize findings**: by exploitability × blast radius × data sensitivity
4. **Draft recommendations**: each with severity, rollback path, and validation command
5. **Confirm before acting**: require explicit approval for any IAM, network, KMS, or compliance-impacting change

## Response shape

1. Scope and multi-account structure
2. Security Hub / GuardDuty / CloudTrail / Config coverage
3. IAM and identity posture
4. Network and infrastructure protection
5. Data protection and encryption
6. Incident response readiness
7. Prioritized findings (Critical → High → Medium)
8. Open risks and blockers