# AWS Users Key Watchdog

A Lambda-based solution that enforces AWS IAM access key rotation policies by automatically deactivating old keys, sending notifications, and providing users with comprehensive guidance on how to rotate their keys.

## Project Overview

This project consists of:

1. A Lambda function that monitors AWS IAM user access keys, automatically deactivates keys older than 90 days, and sends notifications to users
2. A comprehensive HTML guide for AWS access key rotation hosted on S3

## Project Structure

```
.
├── guide/                          # Self-contained HTML guide for AWS access key rotation
├── lambda/                         # Lambda function code
│   └── aws_users_key_watchdog/     # Main Lambda package
│       ├── src/                    # Source code
│       │   ├── templates/          # HTML templates and images
│       │   │   ├── aws_key_rotation_guide.html  # Template HTML guide
│       │   │   ├── email_*.html/txt            # Email templates
│       │   │   └── images/                     # Guide images
│       │   ├── app.py              # Main application code
│       │   └── handler.py          # Lambda handler
│       └── tests/                  # Test files
└── scripts/                        # Utility scripts for guide creation and S3 upload
```

## Guide Files

The project includes two versions of the AWS Access Key Rotation Guide:

1. **Template Guide** (`lambda/aws_users_key_watchdog/src/templates/aws_key_rotation_guide.html`):
   - HTML template with image references
   - Used as the source for generating the S3-hosted guide
   - Images are stored in `lambda/aws_users_key_watchdog/src/templates/images/`

2. **Self-Contained Guide** (`guide/`):
   - Contains the standalone HTML guide with embedded images
   - Fully portable and can be shared without external dependencies
   - Can be opened in any web browser
   - Includes step-by-step instructions with screenshots

## Lambda Function

The Lambda function monitors AWS IAM user access keys and takes action based on their age. It includes:

- Monitoring for key age
- Automatic deactivation of keys older than the configured threshold (90 days by default)
- Deletion of unused keys that are older than the threshold
- Email notifications with rotation instructions
- Links to the comprehensive rotation guide hosted on S3
- Support for DataDog monitoring and lambdacommon error tracking

### Environment Variables

- `KEY_MAX_AGE_DAYS`: Maximum age for keys before expiration (default: 90)
- `SEND_NOTIFICATION_DAYS_BEFORE`: Days before expiration to send notification (default: 7)
- `DISABLE_EXPIRED_KEYS`: Whether to disable expired keys (default: true)

## Utility Scripts

The `scripts/` directory contains utility scripts for managing the guide:

- **create_self_contained_guide.py** - Creates a standalone HTML guide with embedded images
- **upload_guide_to_s3.py** - Uploads the guide to S3 for sharing with users

## S3 Hosting

The guide is hosted on S3 and accessible via the following URL:
```
https://orcd-public.theorchard.io/aws-key-rotation-guide/aws_key_rotation_guide.html
```

This URL is referenced in the email templates to provide users with access to the guide.

## Using the Guide

1. Users can access the guide via the link in the notification email
2. Alternatively, the self-contained HTML file can be shared directly with users
3. The guide can be opened in any web browser without requiring internet access (when using the self-contained version)
4. Users should follow the step-by-step instructions with screenshots to rotate their AWS access keys

## Email Templates

The email templates are located in `lambda/aws_users_key_watchdog/src/templates/` and include:

- `email_body.html` - HTML version of the notification email
- `email_body.txt` - Plain text version of the notification email
- `email_subject.txt` - Subject line for the notification email

The HTML email template includes a link to the S3-hosted guide.

## Development

### Prerequisites

- Docker and Docker Compose
- AWS CLI configured with appropriate permissions

### Local Development

```bash
# Run tests
docker-compose up lint-and-test

# Start local function
docker-compose up function
```

### Guide Development

1. Make changes to the template guide in `lambda/aws_users_key_watchdog/src/templates/aws_key_rotation_guide.html`
2. Run the script to create the self-contained guide:
   ```bash
   python scripts/create_self_contained_guide.py
   ```
3. Upload the guide to S3:
   ```bash
   python scripts/upload_guide_to_s3.py
   ```
4. Deploy the Lambda function

## Deployment

To deploy the solution:

1. Generate the self-contained guide: 
   ```bash
   python scripts/create_self_contained_guide.py
   ```
2. Upload the guide to S3: 
   ```bash
   python scripts/upload_guide_to_s3.py
   ```
3. Deploy the Lambda function using your preferred method (AWS CLI, CloudFormation, etc.)
4. Verify the email templates contain the correct S3 URL for the guide