Fearless Factory Accelerator

Production-ready AI/ML platform with AWS Bedrock integration, weather intelligence, and modern web UI

A FedRAMP-compliant, multi-environment application platform featuring serverless Lambda functions, AI/ML capabilities via AWS Bedrock, and real-time weather intelligence with a modern React UI.

🎯 Getting Started

The Fearless Factory Accelerator provides two complementary approaches for infrastructure deployment:

Option 1: Manifest-Driven Generation (Recommended for New Projects) 🚀

Best for: New applications, rapid deployment, consistent standards

Define your application in a YAML manifest, then automatically generate production-ready Terraform infrastructure:

# 1. Choose or create a manifest
cp orchestration/examples/multi-tier-complex.yaml my-app.yaml

# 2. Generate Terraform infrastructure
cd generator
python3 generate_terraform.py ../my-app.yaml ../output/my-app/ --environment dev

# 3. Deploy to AWS
cd ../output/my-app/
terraform init
terraform plan
terraform apply

Benefits:

• ⚡ Fast: Infrastructure in minutes, not hours
• 📋 Consistent: Standardized naming, tagging, security
• 🎯 Simple: Describe what you want, not how to build it
• ✅ Validated: Schema validation catches errors early

Learn More:

• 📖 Manifest-Driven Guide - Complete documentation
• 📝 Example Manifests - Working examples
• 🔄 Comparison Doc - Traditional vs. Manifest approaches

Option 2: Direct Terraform (For Existing Infrastructure) 🔧

Best for: Existing infrastructure, custom requirements, advanced users

Manually configure and deploy Terraform for full control over every resource:

# Bootstrap state backend (one-time)
cd terraform/bootstrap
terraform init && terraform apply

# Deploy environment
cd ../environments/dev
terraform init && terraform plan && terraform apply

When to Use:

• You need fine-grained control over specific resources
• You're working with existing Terraform infrastructure
• You have custom requirements not covered by manifests
• You're an advanced Terraform user

Continue to Prerequisites section below for detailed setup.

---

👋 For New Team Members

Understanding the Project Evolution

This project has evolved through several phases:

1. Phase 1 (Original): Manual Terraform infrastructure

   • Located in terraform/ directory
   • Direct resource configuration
   • Full control, more complexity

2. Phase 2 (Current): Manifest-driven generation

   • Define apps in YAML (orchestration/)
   • Generate Terraform automatically (generator/)
   • Faster, more consistent, less error-prone

3. Phase 3 (Future): Full orchestration API

   • Self-service deployment portal
   • Approval workflows
   • Centralized tracking

Your First Day Checklist

Essential Reading (Priority Order):

• Start Here: orchestration/README.md - Understand manifest-driven approach
• Examples: orchestration/examples/ - See working manifests
• Generator: generator/README.md - Learn the generation tool
• Comparison: FACTORY_IAC_GENERATION_COMPARISON.md - Why we evolved

Getting Your Environment Set Up:

# 1. Install prerequisites
./scripts/install-tools.sh

# 2. Configure AWS
aws configure

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your settings
source .env

# 4. Try generating infrastructure from a manifest
cd generator
python3 generate_terraform.py \
  ../orchestration/examples/multi-tier-complex.yaml \
  ../output/test/ \
  --environment dev

Key Documentation Map

Document	Purpose	When to Read
orchestration/README.md	Manifest-driven deployment guide	Read First - Day 1
generator/README.md	Python generator tool usage	Day 1
orchestration/examples/	Working manifest examples	Day 1
app/README.md	FastAPI backend (Python)	When working on API code
ui/weather/README.md	React UI (TypeScript)	When working on frontend
terraform/README.md	Direct Terraform usage	Advanced scenarios only
docs/DEPLOYMENT.md	CI/CD pipeline details	When modifying builds

Common Questions

Q: Which approach should I use for a new project?
A: Use the manifest-driven approach (Option 1). It's faster, more consistent, and includes best practices by default.

Q: Can I customize the generated Terraform?
A: Yes! The generator creates standard Terraform files you can modify. For extensive customization, you can also extend the generator templates.

Q: What if I need something not in the manifest schema?
A: You have three options:

1. Generate infrastructure, then manually add custom resources
2. Request schema enhancements (if the need is common)
3. Use direct Terraform (Option 2) for full control

Q: Where do I find examples?
A: Check orchestration/examples/ for working manifests:

• multi-tier-complex.yaml - Full-featured enterprise app
• app-orchestrator-demo-manifest.yaml - Simple demo

---

🏗️ Architecture Overview

Deployment Architecture

The project supports two deployment paths from manifest to infrastructure:

┌─────────────────────────────────────────────────┐
│  Developer Creates Manifest (YAML)              │
│  - Application requirements                      │
│  - Infrastructure specifications                 │
│  - Environment configurations                    │
└────────────────────┬────────────────────────────┘
                     │
         ┌───────────┴───────────┐
         │                       │
         ▼                       ▼
┌──────────────────┐    ┌──────────────────┐
│ Manual Generator │    │ Orchestration    │
│ (Fast, Local)    │    │ API (Governed)   │
│ See generator/   │    │ See orchestration/│
└────────┬─────────┘    └────────┬─────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
         ┌─────────────────────┐
         │ Generated Terraform │
         │ (in output/ dir)    │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │ AWS Infrastructure  │
         │ - VPC, Lambda, etc. │
         └─────────────────────┘

Application Architecture

Once deployed, the application runs with this architecture:

┌─────────────────────────────────────────────────┐
│  React UI (CloudFront + S3)                     │
│  - Weather dashboard with AI chat               │
│  - Real-time forecasts and alerts               │
└────────────────────┬────────────────────────────┘
                     │ HTTPS
                     ▼
┌─────────────────────────────────────────────────┐
│  API Gateway + WAF                              │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│  Lambda (Python 3.11 - FastAPI)                 │
│  - /ai/* endpoints (Bedrock AI/ML)              │
│  - /weather/* endpoints (NWS + AI)              │
│  - /health (monitoring)                         │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
            AWS Bedrock (Claude Models)
            National Weather Service API

Infrastructure Components

• Frontend: React/TypeScript UI with Tailwind CSS v4, hosted on CloudFront + S3
• Backend: Python FastAPI on Lambda for AI and weather services
• VPC: Multi-AZ VPC with public and private subnets
• Security: KMS encryption, AWS Secrets Manager, CloudTrail, GuardDuty, AWS Config, Security Hub
• Compute: AWS Lambda for serverless functions
• API: API Gateway for RESTful APIs with WAF protection
• AI/ML: AWS Bedrock for generative AI capabilities (Claude models)
• Weather: National Weather Service API integration with caching
• CDN: CloudFront for global UI distribution
• Storage: S3 buckets with versioning and lifecycle policies
• Monitoring: CloudWatch Logs, Metrics, and Alarms
• Networking: NAT Gateways, VPC Endpoints, Network ACLs

Environments

• dev: Development environment (single-AZ, minimal resources)
• test: Testing environment (multi-AZ, moderate resources)
• prod: Production environment (multi-AZ, HA, scaled resources)

🤖 Fearless Factory Bedrock API

A production-ready FastAPI application providing REST API access to AWS Bedrock AI/ML capabilities.

Features

• AI Chat: Conversational AI with Claude 3.5 Sonnet, Claude 3 Haiku, Claude 3 Sonnet
• Text Embeddings: Semantic search with Amazon Titan
• Model Discovery: List and query available Bedrock models
• OpenAPI Integration: Automatic spec generation for Stoplight.ai
• Secure by Design: Input validation, structured error handling
• Observability: JSON logging, CloudWatch metrics
• FedRAMP Aligned: Compliance controls built-in

API Endpoints

AI Services (/ai):

GET  /ai/models        - List available Bedrock models
POST /ai/chat          - Conversational AI (Claude models)
POST /ai/embeddings    - Text embeddings (Titan)

Weather Services (/weather):

GET  /weather/forecast?zip_code=10001  - 7-day weather forecast
GET  /weather/alerts?zip_code=10001    - Active weather alerts
POST /weather/chat                     - AI weather conversation
POST /weather/advice                   - Personalized weather advice

System:

GET  /health           - Health check
GET  /openapi.json     - OpenAPI specification
GET  /docs             - Interactive API docs (Swagger UI)
GET  /redoc            - Alternative API docs (ReDoc)

Quick Start

Local Development:

cd app
pip install -r requirements.txt
python main.py
# Access http://localhost:8000/docs

Deploy to AWS:

# Automatic: Push changes to app/ directory
cd app
# Make changes...
git add app/
git commit -m "feat: Update FastAPI"
git push origin feature/cline_generation_az  # Or your branch

# The unified pipeline will automatically:
# - Detect app/ changes
# - Build Docker image
# - Deploy to Lambda

Testing the Deployed FastAPI API

Get API Endpoint (No Terraform Required):

# Get API Gateway ID from AWS
API_ID=$(aws apigateway get-rest-apis \
  --query 'items[?name==`dev-mes-accelerator-demo-api`].id' \
  --output text)

# Construct endpoint URL
API_ENDPOINT="https://${API_ID}.execute-api.us-east-1.amazonaws.com/dev"
echo "API Endpoint: $API_ENDPOINT"

# Or use the direct endpoint if you know it:
API_ENDPOINT="https://555jtireoa.execute-api.us-east-1.amazonaws.com/dev"

Test FastAPI Bedrock Endpoints:

# Health check
curl "$API_ENDPOINT/health" | jq .

# List available AI models (Claude, Titan)
curl "$API_ENDPOINT/ai/models" | jq .

# Interactive Swagger UI documentation
open "$API_ENDPOINT/docs"

# Chat with Claude 3.5 Sonnet
curl -X POST "$API_ENDPOINT/ai/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain serverless architecture benefits",
    "model_id": "anthropic.claude-3-5-sonnet-20241022-v2:0"
  }' | jq .

# Generate text embeddings
curl -X POST "$API_ENDPOINT/ai/embeddings" \
  -H "Content-Type: application/json" \
  -d '{"text": "Machine learning and AI"}' | jq .

# Get OpenAPI specification
curl "$API_ENDPOINT/openapi.json" | jq . > openapi.json

Documentation

• 📖 Quick Start Guide: docs/QUICK_START.md
• 📖 Deployment Guide: docs/DEPLOYMENT.md
• 📖 Stoplight Integration: docs/STOPLIGHT_INTEGRATION.md
• 📖 App Documentation: app/README.md

📋 Prerequisites

Required Tools

Run the installation script to install all required tools:

./scripts/install-tools.sh

This installs:

• Terraform (>= 1.5.0)
• AWS CLI v2
• Docker
• Python 3.11+
• pre-commit
• jq
• terraform-docs
• tfsec
• checkov
• tflint

AWS Configuration

1. AWS Credentials: Configure AWS CLI with appropriate credentials

   aws configure

2. Required Permissions: Your AWS user/role needs permissions to create:

   • VPC, Subnets, Route Tables, NAT Gateways
   • S3 Buckets
   • Lambda Functions
   • API Gateway REST APIs
   • KMS Keys
   • Secrets Manager Secrets, SSM Parameters
   • IAM Roles and Policies
   • CloudTrail, GuardDuty, AWS Config, Security Hub
   • CloudWatch Log Groups

Environment Variables Configuration

IMPORTANT: Set up environment variables before running Terraform to avoid unexpected state changes.

1. Create Local Environment File: Copy the example file and configure your values

   cp .env.example .env

2. Configure Required Variables: Edit .env and set the required Terraform variables. Variables prefixed with TF_VAR_ are automatically picked up by Terraform.

   Critical for CI/CD Module - Add the GitHub token secret ARN if you need webhook integration:

   # Add to your .env file
   export TF_VAR_github_token_secret_arn="arn:aws:secretsmanager:us-east-1:YOUR_ACCOUNT_ID:secret:dev/mes-demo/github-token-XXXXX"  # pragma: allowlist secret

   Note: Without this variable, Terraform will plan to destroy the aws_codebuild_source_credential resource and remove GitHub webhook authentication from your CodeBuild projects.

3. Load Environment Variables: Before running any Terraform commands, source the environment file:

   source ./.env

   This loads all environment variables into your current shell session. You'll need to run this command in each new terminal session.

4. Verify Variables Are Set: Confirm your Terraform variables are loaded:

   # Check if GitHub token ARN is set
   echo $TF_VAR_github_token_secret_arn

Why This Matters: Terraform uses conditional resource creation based on these variables. Missing variables can cause Terraform to plan unexpected resource deletions, particularly for CI/CD resources like GitHub webhooks and source credentials.

🚀 Quick Start

Automated Setup (Recommended)

The easiest way to set up the Terraform infrastructure is using the automated setup script:

# Make the script executable (if not already)
chmod +x setup-terraform.sh

# Run the automated setup
./setup-terraform.sh

The script will:

1. ✅ Check prerequisites (Terraform, AWS CLI, AWS credentials)
2. ✅ Display your AWS account and region
3. ✅ Create or verify the Terraform backend (S3 + DynamoDB)
4. ✅ Initialize the dev environment
5. ✅ Provide next steps for deployment

What it handles for you:

• Detects if backend already exists (won't recreate)
• Provides clear colored output with progress indicators
• Handles errors gracefully with helpful messages
• Gives you the option to skip existing infrastructure

After the script completes, you can proceed with deploying your infrastructure:

cd terraform/environments/dev
terraform plan
terraform apply

---

Manual Setup (Alternative)

If you prefer to run the setup steps manually, follow these instructions:

1. Bootstrap Terraform State Backend

IMPORTANT: Run this ONCE before any environment deployment:

cd terraform/bootstrap
terraform init
terraform plan
terraform apply

# Save outputs for reference
terraform output -json > bootstrap-outputs.json

2. Configure Environment Variables

IMPORTANT: Load your environment variables before deploying:

# From the project root, load environment variables
source ./.env

# Verify critical variables are set
echo $TF_VAR_github_token_secret_arn

3. Deploy Dev Environment

cd terraform/environments/dev

# Initialize Terraform
terraform init

# Review the plan
terraform plan

# Apply the infrastructure
terraform apply

# Save outputs
terraform output -json > outputs.json

Note: If you see unexpected resource deletions in the plan (especially aws_codebuild_source_credential), verify your environment variables are properly loaded with source ./.env.

4. Test Your Deployment

After successful deployment, test your API endpoints:

# Get the API Gateway endpoint URL
API_ENDPOINT=$(terraform output -raw api_gateway_endpoint)

# Test the health check endpoint (public - no authentication required)
curl $API_ENDPOINT/health

# Expected response:
# {"success":true,"status":"healthy","environment":"dev","service":"lambda-api-handler","version":"1.0.0"}

Testing the /hello Endpoint (API Key Required):

The /hello endpoint is protected with API key authentication for security. Retrieve and use the API key:

# Option 1: Get API key from Secrets Manager (recommended)
API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id dev/api-gateway/hello-api-key \
  --query SecretString --output text | jq -r '.api_key_value')

# Option 2: Get API key from Terraform output
API_KEY=$(terraform output -raw api_key_value)

# Test the hello endpoint with API key
curl -H "x-api-key: $API_KEY" "$API_ENDPOINT/hello"

# Expected response:
# {"success":true,"message":"Hello, World!","environment":"dev"}

# Test with custom name parameter
curl -H "x-api-key: $API_KEY" "$API_ENDPOINT/hello?name=John"

# Expected response:
# {"success":true,"message":"Hello, John!","environment":"dev"}

# Test without API key (should fail with 403 Forbidden)
curl "$API_ENDPOINT/hello"

# Expected response:
# {"message":"Forbidden"}

View Complete API Key Details:

# View all API key metadata from Secrets Manager
aws secretsmanager get-secret-value \
  --secret-id dev/api-gateway/hello-api-key \
  --query SecretString --output text | jq '.'

# Output includes:
# {
#   "api_key_id": "...",
#   "api_key_value": "...",
#   "api_key_name": "dev-mes-accelerator-demo-hello-api-key",  # pragma: allowlist secret
#   "endpoint": "/hello",
#   "description": "API key for accessing the /hello endpoint",
#   "created_date": "..."
# }

View Lambda Logs:

# Get the Lambda function name
FUNCTION_NAME=$(terraform output -raw lambda_function_name)

# View recent logs
aws logs tail /aws/lambda/$FUNCTION_NAME --follow

Retrieve Secrets (stored in Secrets Manager):

# Get application API keys (for external services)
aws secretsmanager get-secret-value \
  --secret-id dev/app/api-keys \
  --query SecretString --output text | jq '.'

# Get API Gateway API key (for /hello endpoint)
aws secretsmanager get-secret-value \
  --secret-id dev/api-gateway/hello-api-key \
  --query SecretString --output text | jq '.'

📁 Repository Structure

fearless-factory-accelerator/
├── generator/              # 🆕 Manifest → Terraform Generator
│   ├── generate_terraform.py    # CLI entry point
│   ├── terraform_generator.py   # Core generation logic
│   ├── manifest_parser.py       # YAML manifest parser
│   ├── sizing_calculator.py     # Resource sizing algorithms
│   ├── requirements.txt         # Python dependencies
│   ├── templates/              # Jinja2 templates
│   │   ├── main.tf.j2          # Main Terraform file
│   │   ├── variables.tf.j2     # Variable definitions
│   │   ├── outputs.tf.j2       # Output values
│   │   └── backend.tf.j2       # S3 backend config
│   └── README.md               # Generator documentation
│
├── orchestration/          # 🆕 Orchestration Layer
│   ├── README.md          # Complete orchestration guide
│   ├── FACTORY_IAC_GENERATION_COMPARISON.md  # Approach comparison
│   ├── schemas/           # Manifest schemas
│   │   ├── manifest-schema-v1.0.yaml  # JSON Schema (YAML format)
│   │   ├── convert-to-json.sh         # Schema conversion script
│   │   └── README.md                  # Schema documentation
│   ├── examples/          # Example manifests
│   │   ├── multi-tier-complex.yaml    # Enterprise example
│   │   └── app-orchestrator-demo-manifest.yaml  # Simple demo
│   └── CLEANUP_DESIGN.md  # Cleanup procedures
│
├── app/                    # Python FastAPI Backend
│   ├── api/
│   │   ├── models/        # Pydantic request/response models
│   │   ├── routes/        # API route handlers
│   │   │   ├── bedrock.py      # AI/ML endpoints
│   │   │   ├── weather.py      # Weather endpoints
│   │   │   └── health.py       # Health check
│   │   └── services/      # Business logic
│   │       ├── bedrock_service.py
│   │       ├── weather_service.py
│   │       └── geocoding_service.py
│   ├── core/              # Configuration and logging
│   ├── main.py            # FastAPI application
│   ├── requirements.txt   # Python dependencies
│   └── README.md          # Backend documentation
│
├── ui/                     # Frontend Applications
│   └── weather/           # Weather UI (React/TypeScript)
│       ├── components/    # React components
│       ├── lib/           # API client and utilities
│       ├── styles/        # Tailwind CSS
│       ├── package.json   # Node.js dependencies
│       └── README.md      # UI documentation
│
├── terraform/              # Infrastructure as Code (Direct Deployment)
│   ├── bootstrap/         # State backend setup
│   ├── modules/          # Reusable modules
│   │   ├── vpc/          # VPC and networking
│   │   ├── security/     # KMS, Secrets, security services
│   │   ├── orchestration/  # 🆕 Orchestration infrastructure
│   │   ├── cicd/         # CodeBuild, CodeDeploy
│   │   ├── cloudfront/   # CloudFront + S3 for UI
│   │   └── waf/          # Web Application Firewall
│   ├── environments/     # Environment configs
│   │   ├── dev/          # Development
│   │   ├── test/         # Testing
│   │   └── prod/         # Production
│   └── README.md         # Infrastructure documentation
│
├── output/                # Generated Terraform (from generator/)
│   └── */                # Per-project generated code
│
├── .github/workflows/     # GitHub Actions CI/CD
├── docs/                  # Documentation
├── prompts/              # AI prompt files for code generation
├── buildspec.yml          # AWS CodeBuild configuration
└── README.md              # This file (start here!)

Component Documentation

Component	Documentation	Purpose
Orchestration	orchestration/README.md	📖 Start here - Manifest-driven deployment
Generator	generator/README.md	🔧 Terraform generation tool
Backend	app/README.md	🐍 FastAPI application, endpoints, development
Frontend	ui/weather/README.md	⚛️ React application, components
Infrastructure	terraform/README.md	🏗️ Direct Terraform deployment
Deployment	docs/DEPLOYMENT.md	🚀 CI/CD pipeline, environments
Prompts	prompts/README.md	🤖 AI-assisted code generation

🤖 AI Prompt Files

This project includes AI-optimized prompt files for automated infrastructure generation. These files are designed for AI assistants like Cline to generate infrastructure code, CI/CD pipelines, and related components for new client projects.

Location: prompts/

For detailed information about the prompt files, their purpose, and usage instructions, see the Prompts Directory README.

Quick Overview

The prompts directory contains comprehensive specifications for:

• Foundation Standards (factory-common-prompt.md) - Naming conventions, tagging strategy, security requirements, and compliance standards
• Infrastructure Specifications (factory-terraform-prompt.md) - AWS infrastructure definitions including VPC, security, Lambda, API Gateway, and monitoring
• CI/CD Pipeline (factory-cicd-prompt.md) - GitHub Actions workflow specifications with security scanning, testing, and deployment automation
• REST API (factory-apigateway-prompt.md) - Lambda + API Gateway specifications with Cognito authentication (optional component)
• Templates & Guides - Master template for creating new prompts and comprehensive dependency matrix

Key Benefits

✅ Rapid Deployment: 1-2 hours for serverless infrastructure setup ✅ Consistency: Standardized naming, tagging, and security across all client projects ✅ Compliance: Built-in FedRAMP Moderate and HIPAA controls ✅ Quality: Best practices, comprehensive testing, and security scanning ✅ AI-Optimized: Designed for efficient AI processing ✅ Production-Ready: Complete specifications with examples and troubleshooting guides

These files enable rapid, consistent serverless infrastructure deployment across multiple client projects while maintaining enterprise-grade security, compliance, and quality standards.

---

🔄 Multi-Environment Setup

This project uses a symlink strategy to maintain DRY principles:

• Common Code: main.tf, variables.tf, outputs.tf in dev/ directory
• Environment-Specific: backend.tf, provider.tf, terraform.tfvars in each environment
• Symlinks: test/ and prod/ symlink to common files in dev/

Deploying to Test/Prod

# Test Environment
cd terraform/environments/test
terraform init
terraform plan
terraform apply

# Prod Environment
cd terraform/environments/prod
terraform init
terraform plan
terraform apply

🔐 Security & Compliance

FedRAMP Compliance

This infrastructure implements FedRAMP Moderate security controls:

• Encryption: All data encrypted at rest (KMS) and in transit (TLS 1.2+)
• Logging: CloudTrail, VPC Flow Logs, application logs
• Monitoring: CloudWatch metrics, GuardDuty threat detection
• Access Control: IAM with least privilege, Zero Trust model
• Compliance: AWS Config rules, Security Hub standards

Security Features

• ✅ KMS encryption for all storage and logs
• ✅ AWS Secrets Manager for sensitive data
• ✅ API key authentication for API endpoints (CKV_AWS_59 compliant)
• ✅ Usage plans with rate limiting and quotas
• ✅ Network isolation with private subnets
• ✅ Security groups with minimal ingress rules
• ✅ CloudTrail with log file validation
• ✅ GuardDuty for threat detection
• ✅ AWS Config for compliance monitoring
• ✅ Security Hub with CIS and FedRAMP standards
• ✅ Automated security scanning in CI/CD

📝 Security Implementation TODO

This section tracks remaining security enhancements identified by Checkov security scanning. The infrastructure currently achieves 68.75% reduction in security findings (from 16 to 5), with the following items remaining for production environments.

Current Security Status

• ✅ Passed Checks: 233
• ⚠️ Remaining Issues: 5 (Phase 3 - Production Readiness)
• ⏭️ Justified Skips: 5 (documented design decisions)

---

Phase 3: Production Readiness (Recommended for Prod Deployment)

The following security enhancements are recommended for production environments. All are lower priority for development but important for compliance and production-grade security.

1. Lambda Environment Variable Encryption with CMK

Issue: CKV_AWS_173 - Lambda environment variables not encrypted with Customer Managed Key Current State: Environment variables exist but use AWS-managed encryption Priority: Medium Effort: Low (30 minutes) Compliance Impact: Required for FedRAMP High, HIPAA strict compliance

Implementation:

# File: terraform/modules/lambda/main.tf
resource "aws_lambda_function" "api_handler" {
  # ... existing config ...

  kms_key_arn = var.kms_key_arn  # Add this line

  environment {
    variables = {
      # Existing variables...
    }
  }
}

Benefits:

• Full control over encryption keys
• Enhanced audit trail for key usage
• Ability to rotate keys independently
• Better compliance posture

Testing:

# Verify encryption after deployment
aws lambda get-function --function-name <function-name> \
  | jq '.Configuration.KMSKeyArn'

---

2. DynamoDB Customer Managed Key (CMK) Encryption

Issue: CKV_AWS_119 - DynamoDB state lock table uses AWS-managed key Current State: Table encrypted with AWS-managed key Priority: Low for Dev, High for Prod Effort: Low (15 minutes) Compliance Impact: Required for FedRAMP Moderate+, recommended for HIPAA

Implementation:

# File: terraform/bootstrap/main.tf
resource "aws_dynamodb_table" "terraform_state_lock" {
  # ... existing config ...

  server_side_encryption {
    enabled     = true
    kms_key_arn = aws_kms_key.terraform_state.arn
  }
}

Benefits:

• Centralized key management
• Enhanced security posture for state management
• Better audit and compliance reporting

Note: This change requires recreating the DynamoDB table. Plan carefully for production.

---

3. CodeBuild CMK Encryption

Issue: CKV_AWS_147 - CodeBuild projects not encrypted with CMK Current State: Using AWS-managed encryption Priority: Low for Dev, Medium for Prod Effort: Low (20 minutes) Compliance Impact: Recommended for FedRAMP, required for highly sensitive builds

Implementation:

# File: terraform/modules/cicd/main.tf
resource "aws_codebuild_project" "main" {
  # ... existing config ...

  encryption_key = var.kms_key_arn  # Add this line

  # ... rest of config ...
}

Benefits:

• Encrypted build artifacts with customer-managed keys
• Better control over CI/CD pipeline security
• Enhanced compliance posture

Testing:

# Verify encryption after deployment
aws codebuild batch-get-projects \
  --names <project-name> \
  | jq '.projects[0].encryptionKey'

---

4. CloudTrail SNS Notifications

Issue: CKV_AWS_252 - CloudTrail not configured with SNS topic for alerts Current State: CloudTrail logging to S3 and CloudWatch only Priority: Low for Dev, Medium for Prod Effort: Medium (45 minutes) Compliance Impact: Recommended for real-time security monitoring

Implementation:

# File: terraform/modules/security/main.tf

# Create SNS topic for CloudTrail alerts
resource "aws_sns_topic" "cloudtrail_alerts" {
  name              = "${var.environment}-${var.project_name}-cloudtrail-alerts"
  kms_master_key_id = aws_kms_key.main.arn

  tags = merge(var.tags, {
    Name = "${var.environment}-${var.project_name}-cloudtrail-alerts"
  })
}

# Email subscription (optional)
resource "aws_sns_topic_subscription" "cloudtrail_email" {
  count     = var.security_alert_email != "" ? 1 : 0
  topic_arn = aws_sns_topic.cloudtrail_alerts.arn
  protocol  = "email"
  endpoint  = var.security_alert_email
}

# Update CloudTrail
resource "aws_cloudtrail" "main" {
  # ... existing config ...

  sns_topic_name = aws_sns_topic.cloudtrail_alerts.name  # Add this line
}

Benefits:

• Real-time notifications for CloudTrail events
• Integration with security monitoring systems
• Faster incident response

Use Cases:

• Alert on unauthorized API calls
• Notify on IAM policy changes
• Monitor security group modifications

---

5. Lambda Code Signing (Advanced)

Issue: CKV_AWS_272 - Lambda function not configured for code signing validation Current State: No code signing validation Priority: Low (Advanced security feature) Effort: High (2-3 hours for initial setup) Compliance Impact: Optional, enhances supply chain security

Implementation Overview:

Step 1: Create signing profile

# Create signing profile in AWS Signer
aws signer put-signing-profile \
  --profile-name lambda-signing-profile \
  --platform-id AWSLambda-SHA384-ECDSA

Step 2: Create code signing configuration

# File: terraform/modules/lambda/main.tf
resource "aws_lambda_code_signing_config" "main" {
  allowed_publishers {
    signing_profile_version_arns = [
      var.signing_profile_arn
    ]
  }

  policies {
    untrusted_artifact_on_deployment = "Warn"  # or "Enforce"
  }

  description = "Code signing config for ${var.environment} Lambda functions"
}

resource "aws_lambda_function" "api_handler" {
  # ... existing config ...

  code_signing_config_arn = aws_lambda_code_signing_config.main.arn
}

Step 3: Sign deployment packages

# Sign the Lambda deployment package
aws signer start-signing-job \
  --source 's3={bucketName=my-bucket,key=lambda.zip,version=1}' \
  --destination 's3={bucketName=signed-bucket}' \
  --profile-name lambda-signing-profile

Benefits:

• Ensures only signed code is deployed
• Prevents unauthorized code modifications
• Enhanced supply chain security
• Audit trail for code deployments

Considerations:

• Requires CI/CD pipeline modifications
• Additional step in deployment process
• May impact deployment speed slightly

---

Implementation Priority Guide

For Development Environments

• ✅ Phase 1 & 2 Complete - Current implementation sufficient
• ⚠️ Phase 3 Optional - Implement only if needed for specific compliance requirements

For Production Environments

• ✅ Phase 1 & 2 Complete - Foundation established
• 🔴 Immediate: Lambda Environment CMK (CKV_AWS_173)
• 🔴 Immediate: DynamoDB CMK (CKV_AWS_119)
• 🟡 High Priority: CodeBuild CMK (CKV_AWS_147)
• 🟡 High Priority: CloudTrail SNS (CKV_AWS_252)
• 🟢 Optional: Lambda Code Signing (CKV_AWS_272)

---

Running Security Scans

Full Checkov scan:

checkov --config-file .checkov.yml --directory terraform/ --compact

Scan specific modules:

# Scan Lambda module only
checkov --directory terraform/modules/lambda/ --compact

# Scan with detailed output
checkov --directory terraform/ --output cli

Generate compliance reports:

# JSON report
checkov --directory terraform/ \
  --output json \
  --output-file-path security-report.json

# JUnit XML for CI/CD
checkov --directory terraform/ \
  --output junitxml \
  --output-file-path security-junit.xml

---

Estimated Implementation Time

Phase	Items	Total Effort	When to Implement
Phase 1 (Complete)	8 items	~2 hours	✅ Done
Phase 2 (Complete)	3 items	~3 hours	✅ Done
Phase 3 (Remaining)	5 items	~4-6 hours	Before production deployment

Total remaining effort for production: 4-6 hours

---

🛠️ Development Workflow

Pre-commit Hooks

Install pre-commit hooks:

pre-commit install

Run manually:

pre-commit run --all-files

CI/CD Pipeline

The project uses a unified, intelligent CI/CD pipeline that automatically detects changes and deploys accordingly.

Intelligent Change Detection

The pipeline automatically detects what changed and deploys only what's needed:

Changed Files	Pipeline Actions
terraform/** only	✅ Terraform validation → plan → apply
app/** only	✅ Code quality checks → Docker build → Lambda deployment
Both terraform/ + app/	✅ Terraform deployment then Lambda deployment
Documentation/tests only	✅ Validation checks only (no deployment)

Pull Request Validation

When you open a pull request, the pipeline runs:

• terraform fmt -check -recursive - Ensures code formatting
• terraform validate - Validates Terraform syntax and configuration

Note: Security scanning, Terraform plan preview, and other checks are intentionally excluded from PR validation per project requirements.

Automatic Deployment (Push to develop)

When code is merged to the develop branch, the unified pipeline:

1. Change Detection Phase

   • Analyzes git diff to detect Terraform changes (terraform/**)
   • Analyzes git diff to detect application changes (app/**)
   • Creates intelligent deployment plan

2. Infrastructure Deployment (if Terraform changes detected)

   • terraform fmt -check - Validates code formatting
   • terraform init - Initializes Terraform
   • terraform validate - Validates configuration
   • terraform plan - Creates execution plan
   • terraform apply - Deploys infrastructure changes

3. Application Deployment (if app changes detected)

   • Code quality checks (black, flake8)
   • Unit tests (pytest)
   • Docker build (Lambda deployment package)
   • Upload to S3
   • Update Lambda function
   • Tag with deployment metadata

4. Notifications

   • SNS notifications with deployment summary
   • Includes what was deployed (Terraform/Lambda/both)

Key Benefits:

• ⚡ Faster deployments - Only deploys what changed
• 🎯 Targeted updates - No unnecessary infrastructure changes
• 🔄 Correct order - Always deploys Terraform before Lambda
• 📊 Clear visibility - Know exactly what was deployed

Deployment to Test/Prod Environments

Test and prod deployments must be done manually:

# For test
cd terraform/environments/test
terraform init && terraform plan && terraform apply

# For prod
cd terraform/environments/prod
terraform init && terraform plan && terraform apply

Viewing Pipeline Logs

Monitor deployments in AWS CodeBuild:

# View build logs in real-time
aws logs tail /aws/codebuild/dev-mes-accelerator-demo --follow

# Check last build status
aws codebuild batch-get-builds \
  --ids $(aws codebuild list-builds-for-project \
    --project-name dev-mes-accelerator-demo-build-deploy \
    --query 'ids[0]' --output text)

Branching Strategy

• main: Production-ready code
• develop: Development branch
• feature/*: Feature branches
• hotfix/*: Hotfix branches

📊 Monitoring & Observability

CloudWatch Dashboards

Access CloudWatch dashboards for:

• Lambda metrics (invocations, errors, duration, throttles)
• API Gateway metrics (requests, latency, 4xx/5xx errors)
• VPC Flow Logs
• Application logs

Alarms

Configured CloudWatch alarms for:

• Lambda errors and throttles
• Lambda duration approaching timeout
• API Gateway 5xx errors
• VPC Flow Log analysis

🔧 Maintenance

Updating Terraform

cd terraform/environments/dev
terraform plan  # Review changes
terraform apply # Apply changes

Rotating Secrets

# Rotate API keys
aws secretsmanager update-secret \
  --secret-id dev/app/api-keys \
  --secret-string '{"service1_api_key":"new-key-1","service2_api_key":"new-key-2"}'  # pragma: allowlist secret

Scaling Lambda

Modify terraform.tfvars for each environment:

# Adjust Lambda memory and concurrency
lambda_memory_size                    = 1024  # Increase memory for better performance
lambda_reserved_concurrent_executions = 50    # Reserve more concurrent executions
lambda_timeout                        = 60    # Increase timeout if needed

# Adjust API Gateway throttling
api_gateway_throttle_burst_limit = 1000
api_gateway_throttle_rate_limit  = 500

📖 Additional Documentation

• Bootstrap Infrastructure
• VPC Module
• Security Module
• Lambda Module
• API Gateway Module
• CI/CD Module
• GitHub Webhook Setup Guide - Complete guide for configuring GitHub webhooks with AWS CodeBuild

🆘 Troubleshooting

Common Issues

Unexpected Terraform Resource Changes

If Terraform plans to destroy resources that haven't changed in code (especially CI/CD resources like aws_codebuild_source_credential):

# The issue: You see changes like "index [0] is out of range for count"
# This means a conditional resource expects a variable that isn't set

# Solution: Ensure environment variables are loaded
source ./.env

# Verify the specific variable causing the issue
echo $TF_VAR_github_token_secret_arn

# If empty, add it to your .env file:
# export TF_VAR_github_token_secret_arn="arn:aws:secretsmanager:..."  # pragma: allowlist secret

# Re-run the plan after loading variables
cd terraform/environments/dev
terraform plan

Root Cause: The CI/CD module uses conditional resource creation based on github_token_secret_arn. When this variable is empty, Terraform's count evaluates to 0, causing resources to be destroyed. When set, count is 1, and resources are created/maintained. # pragma: allowlist secret

Terraform State Lock Error

# Force unlock (use with caution)
terraform force-unlock <LOCK_ID>

Lambda Function Errors

# Check Lambda logs
FUNCTION_NAME=$(terraform output -raw lambda_function_name)
aws logs tail /aws/lambda/$FUNCTION_NAME --since 1h

# Test Lambda directly
aws lambda invoke \
  --function-name $FUNCTION_NAME \
  --payload '{}' \
  response.json

API Gateway 5xx Errors

• Check Lambda function logs for errors
• Verify Lambda has correct IAM permissions
• Check VPC configuration and NAT Gateway
• Review API Gateway logs in CloudWatch

API Gateway 403 Forbidden Errors

If you receive 403 Forbidden when calling the /hello endpoint:

# Verify you're using the API key header
curl -H "x-api-key: YOUR_KEY_HERE" "$API_ENDPOINT/hello"

# Retrieve the current API key
API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id dev/api-gateway/hello-api-key \
  --query SecretString --output text | jq -r '.api_key_value')

# Test again with the correct key
curl -H "x-api-key: $API_KEY" "$API_ENDPOINT/hello"

# Verify the API key is associated with the usage plan
aws apigateway get-usage-plan-keys \
  --usage-plan-id $(terraform output -raw usage_plan_id)

VPC Connectivity Issues

• Verify NAT Gateway is running
• Check route table configurations
• Review security group rules
• Check VPC endpoint configurations

🤝 Contributing

1. Create a feature branch from develop
2. Make your changes
3. Run pre-commit hooks
4. Submit a pull request
5. Wait for CI/CD validation
6. Address review feedback
7. Merge after approval

📝 License

This project is licensed under the terms in the LICENSE file.

👥 Team

Built with ❤️ by Fearless Solutions

Be Remarkable. Be Fearless. 💜

---

🚨 Important Notes

• Never commit secrets to version control
• Always review Terraform plans before applying
• Test in dev before deploying to prod
• Monitor costs in AWS Cost Explorer
• Rotate API keys regularly
• Review Security Hub findings weekly
• Monitor Lambda costs and adjust memory/concurrency as needed

📞 Support

For issues or questions:

• Open a GitHub issue
• Contact the Fearless Solutions team
• Review CloudWatch logs
• Check AWS Service Health Dashboard