Metadata-Version: 2.4
Name: aws-war-lens
Version: 0.1.1
Summary: AWS Well-Architected Review — automated assessment and PDF report generator
Requires-Python: >=3.13
Requires-Dist: anthropic>=0.102.0
Requires-Dist: boto3>=1.34.96
Requires-Dist: jinja2>=3.1.6
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: weasyprint>=66.0
Description-Content-Type: text/markdown

# AWS WAR Lens

Automated AWS Well-Architected Review assessments. Scans your AWS account across all six pillars, produces risk-rated findings, and generates a PDF report — with optional LLM-powered narrative and prioritization.

## Features

- **175 programmatic checks** across all 6 Well-Architected pillars
- **Risk-rated findings** — CRITICAL / HIGH / MEDIUM / LOW / PASS
- **PDF report** with executive summary, top priorities, and cross-finding correlations
- **Multi-region scanning** — `--region all` scans every opted-in region in parallel
- **No infrastructure required** — runs locally or in Docker against any AWS account

## Pillars

| Pillar | Checks |
|---|---|
| Security | 61 |
| Reliability | 44 |
| Operational Excellence | 34 |
| Performance Efficiency | 14 |
| Sustainability | 11 |
| Cost Optimization | 11 |

## Installation

```bash
pip install aws-war-lens
```

> **Note:** WeasyPrint (used for PDF generation) requires native system libraries on Linux/macOS. See [WeasyPrint installation docs](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html) if you hit dependency errors.

## Usage

```bash
# Scan a single region (security pillar by default)
aws-war-lens --region eu-west-1

# Scan multiple pillars
aws-war-lens --region eu-west-1 --pillars security reliability cost_optimization

# Scan all opted-in regions
aws-war-lens --region all

# Skip LLM analysis (no ANTHROPIC_API_KEY needed)
aws-war-lens --region eu-west-1 --no-llm

# Use a named AWS profile
aws-war-lens --region eu-west-1 --profile myprofile

# Use explicit credentials
aws-war-lens --region eu-west-1 --access-key AKIA... --secret-key xxxx
```

The PDF report is saved to `output/` by default. Use `--output <dir>` to change it.

## Authentication

Credentials are resolved in this order:

1. `--access-key` / `--secret-key` / `--session-token` flags
2. `--profile` named profile from `~/.aws/credentials`
3. `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` environment variables
4. Default AWS CLI profile
5. IAM instance profile / ECS task role / Lambda execution role

## LLM Analysis

Set `ANTHROPIC_API_KEY` in your environment (or a `.env` file) to enable LLM-powered narrative, executive summary, and cross-finding correlation in the report. Without it, the report renders with raw findings only.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
aws-war-lens --region eu-west-1
```

## Docker

```bash
docker run --rm \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e AWS_ACCESS_KEY_ID=... \
  -e AWS_SECRET_ACCESS_KEY=... \
  -e AWS_SESSION_TOKEN=... \
  -v "$(pwd)/output:/app/output" \
  aws-war-lens --region eu-west-1
```

## Available Pillars

| Value | Description |
|---|---|
| `security` | IAM, S3, GuardDuty, CloudTrail, KMS, VPC, ACM, and more |
| `reliability` | Auto Scaling, RDS multi-AZ, backups, Route 53, quotas |
| `performance` | Instance families, Graviton, DynamoDB, CloudFront, ElastiCache |
| `cost_optimization` | Idle resources, rightsizing, reserved capacity, orphaned snapshots |
| `operational_excellence` | CloudWatch alarms, SSM, tagging, CI/CD, ECS configuration |
| `sustainability` | Graviton adoption, Fargate, auto-scaling, S3 intelligent tiering |

## IAM Permissions

The scanner IAM role needs read-only access across the services it checks. A broad starting point is `ReadOnlyAccess` (AWS managed policy). Checks that lack permission are reported as coverage gaps in the PDF — they do not fail silently.
