AWS Well-Architected Review

This workflow performs a structured AWS Well-Architected Framework (WAF) review against your workload's IaC files and deployed infrastructure. It identifies risks across all 6 WAF pillars and creates GitHub issues to track remediation.

Prerequisites

• AWS CLI configured and authenticated
• IaC files present in the repository (Terraform, CloudFormation, CDK, or SAM)
• GitHub MCP server configured and authenticated

Workflow Steps

Step 1: Load Well-Architected Framework Reference

Fetch current AWS WAF best practices:

• https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html
• Pillar-specific lenses relevant to the workload type (Serverless, SaaS, etc.)

Step 2: Discover IaC & Architecture

Scan the repository for IaC files:

• Terraform: **/*.tf
• CloudFormation/SAM: **/*.yaml, **/*.json (CFn templates)
• CDK: lib/**/*.ts, bin/**/*.ts, cdk.json

Identify key AWS services in use (compute, data, networking, security, observability) and generate a Mermaid architecture diagram.

Step 3: Pillar-by-Pillar Review

Pillar 1: Operational Excellence

• All infrastructure defined as IaC (no manual console changes)
• Consistent tagging strategy applied across all resources
• CloudWatch alarms defined for key metrics
• Automated deployment pipeline present (no manual deployments)
• CloudTrail enabled for audit logging
• Runbooks or operational documentation present

Pillar 2: Security

• IAM roles use least-privilege policies (no * actions without justification)
• No hardcoded credentials in IaC or code
• Secrets managed via Secrets Manager or SSM Parameter Store
• S3 buckets have public access blocked and server-side encryption enabled
• Sensitive resources placed in private subnets
• Security groups restrict inbound to minimum required ports/CIDRs
• KMS encryption enabled for sensitive data stores (RDS, EBS, S3, SQS, DynamoDB)
• SSL/TLS enforced on all endpoints (enforceSSL: true)
• GuardDuty enabled (aws guardduty list-detectors)
• AWS WAF configured on public-facing APIs and CloudFront distributions
• MFA delete enabled on critical S3 buckets

Pillar 3: Reliability

• Multi-AZ deployments for production databases (RDS Multi-AZ, DynamoDB Global Tables)
• Auto Scaling configured with appropriate policies for EC2/ECS
• S3 versioning and lifecycle policies configured
• RDS automated backups enabled with appropriate retention period
• DynamoDB Point-in-Time Recovery (PITR) enabled
• Dead Letter Queues (DLQ) configured for Lambda, SQS, SNS
• Route 53 health checks configured for DNS failover
• Lambda reserved concurrency set to prevent noisy-neighbor throttling

Pillar 4: Performance Efficiency

• Right-sized instance types (Lambda memory, EC2 type, RDS class)
• Graviton/ARM instances used where available (Lambda arm64, EC2 Graviton)
• Caching implemented (ElastiCache, DAX, CloudFront, API Gateway caching)
• CloudFront used for global static content delivery
• Aurora Serverless or DynamoDB On-Demand for variable load patterns
• Lambda Provisioned Concurrency for latency-critical synchronous paths

Pillar 5: Cost Optimization

• EC2 Reserved Instances or Savings Plans for steady-state workloads
• S3 lifecycle policies moving data to cheaper storage tiers
• Lambda arm64 architecture adopted (20% cost reduction)
• VPC Endpoints for S3/DynamoDB to avoid NAT Gateway charges
• gp2 EBS volumes migrated to gp3 (same performance, 20% cheaper)
• Development/test environments have auto-shutdown schedules
• AWS Budgets and Cost Anomaly Detection configured
• Unattached EBS volumes and idle EC2 instances identified

Pillar 6: Sustainability

• Graviton/ARM instances selected where available
• Serverless/managed services preferred over always-on EC2
• S3 lifecycle policies reduce unnecessary long-term data storage
• Auto Scaling configured to avoid over-provisioning
• Region selection considers AWS renewable energy commitments

Step 4: Risk Classification

For each finding, classify:

• High Risk: Security vulnerability, single point of failure, no backup/recovery
• Medium Risk: Suboptimal reliability, cost inefficiency, performance concern
• Low Risk: Best practice deviation, minor optimization opportunity

Step 5: User Confirmation

…