<<<<<<< HEAD

Automated AWS logging compliance and remediation system that monitors CloudTrail events and ensures logging is enabled across various AWS resources.

This project provides an event-driven architecture that:

• Monitors AWS CloudTrail for resource creation/modification events
• Automatically checks if logging is enabled for the resource
• Uses cross-account IAM roles for secure multi-account access
• Supports multiple AWS resource types (EC2, EKS, ELB, S3, VPC)

enlyte-observability/
├── cms-v2-lambdas/              # Lambda function code
│   ├── code/                    # Python source code
│   ├── layers/                  # Lambda layer dependencies
│   └── Makefile                 # Build automation
├── cms-v2-terraform/            # Terraform infrastructure
│   └── stacks/
│       ├── base/                # Shared infrastructure (S3, KMS)
│       └── observability/       # Observability stack
│           └── logging/         # Logging Lambda and EventBridge
├── cms-v2-terraform-modules/    # Reusable Terraform modules
│   ├── eventbridge-rules/       # EventBridge rule module
│   ├── kms/                     # KMS key module
│   ├── lambda/                  # Lambda function module
│   └── s3/                      # S3 bucket module
└── docs/                        # Resource-specific documentation
    ├── ec2/                     # EC2 logging documentation
    ├── eks/                     # EKS logging documentation
    ├── elb/                     # ELB logging documentation
    ├── s3/                      # S3 logging documentation
    └── vpc/                     # VPC logging documentation

• Python 3.12.3 (via pyenv)
• Terraform >= 1.0
• AWS CLI configured with appropriate credentials
• Make utility =======

Automated AWS observability solution that captures CloudTrail events via EventBridge and enables logging for AWS services (ELB, EC2, RDS, VPC, S3) using serverless Lambda functions.

CloudTrail Events → EventBridge Rules → Lambda Functions → Enable Service Logging
                                              ↓
                                        Lambda Layers
                                        (Dependencies)
                                              ↓
                                    CloudWatch Logs (30-day retention)

• Event-Driven Automation: Automatically enables logging when AWS resources are created
• Multi-Service Support: ELB (ALB/NLB), EC2, RDS, VPC, S3 logging enablement
• Modular Design: Reusable Terraform modules for Lambda, EventBridge, KMS, and S3
• Security First: KMS encryption for all sensitive data, IAM least privilege
• Local Development: Run and test Lambda functions locally with sample events
• CI/CD Ready: S3-based deployment with automatic change detection via ETag

enlyte-observability/
├── cms-v2-lambdas/              # Lambda function source code
│   ├── code/
│   │   ├── src/
│   │   │   ├── common/          # Shared utilities (events, security, utils)
│   │   │   ├── ec2_logs_enabler/
│   │   │   ├── elb_logs_enabler/
│   │   │   ├── process_events_enabler/
│   │   │   ├── rds_logs_enabler/
│   │   │   ├── s3_logs_enabler/
│   │   │   └── vpc_logs_enabler/
│   │   ├── tests/               # Sample CloudTrail events
│   │   ├── main_*.py            # Lambda entry points
│   │   └── launch.json          # VS Code debug configuration
│   ├── layers/                  # Lambda layer dependencies
│   │   └── requirements.txt
│   ├── dist/                    # Built Lambda packages (auto-generated)
│   └── Makefile                 # Build automation
│
├── cms-v2-terraform-modules/    # Reusable Terraform modules
│   ├── eventbridge-rules/       # EventBridge rules and targets
│   ├── kms/                     # KMS key management
│   ├── lambda/                  # Lambda functions and layers
│   ├── s3/                      # S3 bucket configuration
│   └── terraform-aws-s3-bucket/ # S3 bucket wrapper
│
├── cms-v2-terraform/            # Terraform infrastructure stacks
│   └── stacks/
│       ├── base/                # Base infrastructure
│       └── observability/
│           ├── logging/         # Logging stack (EventBridge + Lambda)
│           └── metrics/         # Metrics stack (future)
│
└── docs/                        # Service-specific documentation
    ├── ec2/
    ├── elb/
    ├── rds/
    ├── s3/
    └── vpc/

• Terraform >= 1.0
• AWS CLI configured with appropriate credentials
• Python 3.12+
• Make (for building Lambda packages)
• CloudTrail enabled in target AWS region

origin/main

cd cms-v2-lambdas

<<<<<<< HEAD
# Install dependencies locally
make python-packages

# Build Lambda layer
make layers

# Package Lambda function
make process_events

# Upload to S3 (optional)
make copy-s3

=======

make layers # Build Python dependencies layer make process_events # Build main event processor make ec2 # Build EC2 logs enabler make elb # Build ELB logs enabler

make clean make layers process_events

Built packages will be in `cms-v2-lambdas/dist/`:
- `dependencies_layer.zip`
- `process_events_lambda.zip`
- `ec2_lambda.zip`
- `elb_lambda.zip`

>>>>>>> origin/main
### 2. Deploy Infrastructure

```bash
cd cms-v2-terraform/stacks/observability/logging

# Initialize Terraform
terraform init

<<<<<<< HEAD
# Plan deployment
terraform plan -var-file=environments/dev_us-east-1.tfvars

# Apply infrastructure
terraform apply -var-file=environments/dev_us-east-1.tfvars

1. CloudTrail captures AWS API calls for resource creation/modification
2. EventBridge rule filters relevant events and triggers Lambda
3. Lambda function:
   • Parses the event to identify resource type
   • Assumes cross-account IAM role (logging-remediation)
   • Checks if logging is enabled for the resource
   • Returns result (success if logging disabled, error if enabled)

The Lambda function uses STS AssumeRole to access resources in other AWS accounts:

Lambda (Account A) 
  ↓ AssumeRole
Remediation Role (Account B)
  ↓ Use temporary credentials
AWS Resources (Account B)

Event-driven Python 3.12 Lambda that processes CloudTrail events and checks logging status.

Key Features:

• Abstract base classes for extensibility
• Cross-account role assumption
• Support for Linux and Windows EC2 instances
• Comprehensive error handling and logging

See cms-v2-lambdas/README.md for detailed documentation.

Infrastructure as Code for deploying the observability system.

Components:

• EventBridge rules for CloudTrail event filtering
• Lambda function and layer deployment
• IAM roles for Lambda execution and cross-account access
• S3 bucket for Lambda artifacts
• KMS keys for encryption

Reusable Terraform modules for common AWS resources:

• eventbridge-rules/ - EventBridge rule creation
• kms/ - KMS key management
• lambda/ - Lambda function and layer deployment
• s3/ - S3 bucket with security best practices

Resource-specific documentation for each supported AWS service.

The Lambda requires these environment variables:

• REMEDIATION_ROLE_NAME - IAM role name for cross-account access (default: logging-remediation)
• AWS_REGION - AWS region where Lambda is deployed

Required permissions:

• Basic Lambda execution (logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents)
• STS AssumeRole for the remediation role

Required permissions (assumed by Lambda):

• S3: s3:GetBucketLogging, s3:PutBucketLogging
• EKS: eks:DescribeCluster, eks:UpdateClusterConfig
• EC2: ec2:DescribeInstances, ec2:DescribeFlowLogs, ec2:CreateFlowLogs
• ELB: elasticloadbalancing:DescribeLoadBalancers, elasticloadbalancing:DescribeLoadBalancerAttributes
• VPC: ec2:DescribeFlowLogs, ec2:DescribeVpcs
• SSM: ssm:SendCommand, ssm:GetCommandInvocation (for EC2 CloudWatch Agent checks)

Use VS Code debugger to test Lambda locally:

1. Open cms-v2-lambdas/code/main_process_events.py
2. Set breakpoints as needed
3. Press F5 to start debugging
4. Test events are in cms-v2-lambdas/code/tests/

1. Create handler class in cms-v2-lambdas/code/src/common/ (e.g., rds.py)
2. Implement BaseResources interface:
   • is_event() - Check if event matches resource
   • parse_event() - Extract resource information
   • get_arn() - Construct resource ARN
   • check_logs_enabled() - Verify logging status
3. Register handler in cms-v2-lambdas/code/src/common/events.py
4. Create test event in cms-v2-lambdas/code/tests/
5. Add documentation in docs/ directory

cd cms-v2-terraform/stacks/observability/logging
terraform apply -var-file=environments/dev_us-east-1.tfvars

cd cms-v2-terraform/stacks/observability/logging
terraform apply -var-file=environments/prod_us-east-1.tfvars

The Lambda function uses CloudWatch Logs for observability:

# View Lambda logs
aws logs tail /aws/lambda/process-events --follow

# View specific error messages
aws logs filter-pattern /aws/lambda/process-events --pattern "ERROR"

1. AccessDenied when assuming role

   • Check IAM trust policy on remediation role
   • Verify Lambda execution role has sts:AssumeRole permission

2. Module import errors

   • Run make python-packages in cms-v2-lambdas/
   • Verify Python 3.12.3 is active

3. Logging check failures

   • Verify remediation role has appropriate permissions
   • Check resource-specific documentation in docs/

• All S3 buckets use server-side encryption (SSE-KMS)
• Lambda functions use environment variables for configuration
• Cross-account access uses IAM roles with least privilege
• All data in transit uses TLS
• CloudWatch Logs for audit trail

When contributing to this project:

1. Follow the existing code structure and naming conventions
2. Add comprehensive error handling
3. Update relevant documentation
4. Test locally before deploying
5. Use descriptive commit messages

[Add your license information here]

terraform plan

terraform apply

### 3. Upload Lambda Packages

After infrastructure is deployed, upload the Lambda packages:

```bash
# Get bucket name from Terraform
BUCKET_NAME=$(terraform output -raw s3_bucket_name)

# Upload packages
cd ../../../../../cms-v2-lambdas
make BUCKET=observability-logging-artifacts-dev copy-s3

# Or manually:
aws s3 cp dist/process_events_lambda.zip s3://$BUCKET_NAME/
aws s3 cp dist/dependencies_layer.zip s3://$BUCKET_NAME/

cd cms-v2-terraform/stacks/observability/logging

# Force Lambda to pick up new code
terraform apply -replace="module.process_events_lambda_logging.module.lambda[0].aws_lambda_function.this[0]"

cd cms-v2-lambdas/code

# Run with test event
python main_process_events.py

# Set log level
export LOGLEVEL=DEBUG
python main_process_events.py

Use the included launch.json configuration:

1. Open cms-v2-lambdas/code/main_process_events.py
2. Set breakpoints
3. Press F5 or select "Debug Lambda Test Runner with Path"
4. Edit tests/nlb_event.json to test different scenarios

Sample CloudTrail events are in cms-v2-lambdas/code/tests/:

• alb_event.json - ALB creation event
• nlb_event.json - NLB deletion event
• ec2_event.json - EC2 event (placeholder)

Modify main_process_events.py to test different events:

file_path = "tests/alb_event.json"  # Change this line

Purpose: Central event router that identifies AWS service events and enables appropriate logging.

Architecture:

EventsHandler → LoadBalancerEvents → Parse & Identify Service
                                            ↓
                                    Enable Service Logging

Supported Events:

• ELB: CreateLoadBalancer, DeleteLoadBalancer
• EC2: (future implementation)
• RDS: (future implementation)
• S3: (future implementation)
• VPC: (future implementation)

Event Processing Flow:

1. Event Reception: Lambda receives CloudTrail event from EventBridge
2. Event Identification: Determines service type (ELB, EC2, etc.)
3. Event Parsing: Extracts relevant information (ARN, region, account)
4. Action Execution: Enables logging for the identified service
5. Response: Returns success/failure status

Example Response:

{
  "statusCode": 200,
  "body": {
    "message": "Event processed successfully",
    "data": {
      "eventSource": "elasticloadbalancing.amazonaws.com",
      "eventName": "CreateLoadBalancer",
      "account": "131578276461",
      "region": "us-east-1",
      "arn": "arn:aws:elasticloadbalancing:us-east-1:131578276461:loadbalancer/app/test-lb/abc123"
    }
  }
}

The Lambda layer includes shared dependencies:

• requests - HTTP library
• urllib3 - HTTP client
• pytz - Timezone handling

Layer structure in Lambda:

/opt/python/
└── lib/
    └── python3.12/
        └── site-packages/
            ├── requests/
            ├── urllib3/
            └── pytz/

Creates EventBridge rules and targets with automatic Lambda permissions.

Features:

• Multiple rules and targets per deployment
• Automatic IAM policy attachment
• CloudWatch integration
• Custom event patterns

Documentation: cms-v2-terraform-modules/eventbridge-rules/README.md

Wrapper around terraform-aws-modules/lambda/aws with S3 change detection.

Features:

• Automatic S3 package updates via ETag
• Lambda functions and layers
• KMS encryption support
• CloudWatch Logs integration

Documentation: cms-v2-terraform-modules/lambda/README.md

Manages KMS keys for encryption with service principal access.

Documentation: cms-v2-terraform-modules/kms/README.md

S3 bucket configuration with versioning and encryption.

Documentation: cms-v2-terraform-modules/s3/README.md

• Lambda Environment Variables: KMS encrypted
• CloudWatch Logs: KMS encrypted with 30-day retention
• S3 Artifacts: KMS encrypted with versioning enabled

Lambda execution roles follow least privilege:

• CloudWatch Logs write access
• KMS decrypt for environment variables
• Service-specific permissions (e.g., ELB DescribeLoadBalancers)

• Lambdas run in AWS-managed VPC (no internet access required)
• EventBridge uses IAM for authorization
• S3 buckets have server-side encryption enforced

Lambda execution logs:

• Log Group: /aws/lambda/process-events-function
• Retention: 30 days
• Encryption: KMS encrypted

Log levels (controlled via LOGLEVEL env var):

• DEBUG - Detailed execution flow
• INFO - Standard operational messages
• WARNING - Non-critical issues
• ERROR - Failures and exceptions

Monitor in CloudWatch:

• Invocations - Rule matches
• FailedInvocations - Lambda failures
• TriggeredRules - Successful executions

• Duration - Execution time
• Errors - Function errors
• Throttles - Concurrency limits hit
• ConcurrentExecutions - Parallel invocations

• Use ARM64 architecture (20% cheaper than x86)
• Adjust CloudWatch Log retention based on compliance needs
• Enable S3 lifecycle policies for old Lambda versions
• Right-size Lambda memory based on profiling
• Use reserved concurrency to prevent runaway costs

Symptoms: Events occur but Lambda doesn't execute

Solutions:

1. Verify CloudTrail is enabled
2. Check EventBridge rule patterns
3. Verify Lambda permissions
4. Review EventBridge metrics for FailedInvocations

Symptoms: New code uploaded but Lambda runs old version

Solutions:

1. Verify ignore_source_code_hash = true in Lambda module
2. Check S3 versioning enabled
3. Confirm ETag changed after upload
4. Force update with terraform apply -replace

Symptoms: Lambda returns "Event type not supported"

Solutions:

1. Add debug logging: export LOGLEVEL=DEBUG
2. Check event format matches CloudTrail structure
3. Verify event source and detail-type in EventBridge pattern
4. Test locally with actual CloudTrail event JSON

• Lambda Module: cms-v2-terraform-modules/lambda/README.md
• EventBridge Module: cms-v2-terraform-modules/eventbridge-rules/README.md
• KMS Module: cms-v2-terraform-modules/kms/README.md
• Logging Stack: cms-v2-terraform/stacks/observability/logging/README.md
• Service Docs: docs/

• Complete EC2 logging enablement
• Complete RDS logging enablement
• Complete S3 logging enablement
• Complete VPC Flow Logs enablement
• Add metrics collection stack
• Implement automated testing (pytest)
• Add CI/CD pipeline (GitHub Actions)

origin/main