aws-cost-optimizer

A Python CLI that audits AWS spend across many accounts and produces actionable cost-optimization reports — Cost Explorer trends, unused-resource detection, and rightsizing recommendations, exported to Excel and CSV.

Audit pipeline

flowchart LR
    subgraph Accounts["AWS accounts (config-driven)"]
        A1["acme-prod\n111111111111"]
        A2["acme-staging\n222222222222"]
        A3["acme-dev\n333333333333"]
    end

    A1 & A2 & A3 -->|STS assume-role| C{{"Collectors"}}

    subgraph C["Collectors"]
        CE["cost_explorer\ncost + MoM trends"]
        UR["unused_resources\nEBS / EC2 / EIP / RDS / ELB / ENI / S3"]
        RS["rightsizing\nCompute Optimizer + CloudWatch"]
    end

    CE & UR & RS --> AGG["multi_account\naggregate AuditResult"]
    AGG --> AN["analysis\nestimated savings totals"]
    AN --> OUT["report\nExcel workbook + CSV"]

Loading

✨ Features

• Cost Explorer insights — unblended cost grouped by service / region / usage type, plus month-over-month trends that surface the biggest movers first.
• Unused-resource detection — finds and prices waste across eight categories: unattached EBS volumes, idle/stopped EC2, unassociated Elastic IPs, old EBS snapshots, idle RDS, unused load balancers, detached ENIs, and empty/old S3 buckets.
• Rightsizing — pulls first-party AWS Compute Optimizer recommendations for EC2 and a CloudWatch CPU heuristic for RDS, each with estimated monthly savings.
• Multi-account — config-driven STS assume-role across a whole fleet of accounts, aggregated into one report. A failure in one account is logged and skipped, never sinking the run.
• Polished reporting — a styled, multi-sheet Excel workbook (headline savings + per-category sheets) and a flat CSV export for BI tools.
• Composable CLI — audit, unused, rightsize, and report subcommands with --profile, --accounts-file, and --regions options.
• Read-only by design — every collector only calls Describe*/Get* APIs; the tool never mutates your infrastructure.

🗂️ Repository Structure

aws-cost-optimizer/
├── src/aws_cost_optimizer/
│   ├── __init__.py
│   ├── models.py            # shared dataclasses (CostLineItem, WasteFinding, ...)
│   ├── cost_explorer.py     # Cost Explorer (ce) cost + MoM trends
│   ├── unused_resources.py  # waste detectors (EBS/EC2/EIP/RDS/ELB/ENI/S3)
│   ├── rightsizing.py       # Compute Optimizer + CloudWatch rightsizing
│   ├── multi_account.py     # STS assume-role + aggregation
│   ├── report.py            # Excel (openpyxl) + CSV writers
│   └── cli.py               # click CLI (audit / unused / rightsize / report)
├── tests/
│   ├── test_models_and_report.py   # model + report unit tests
│   └── test_unused_resources.py    # moto-mocked detector tests
├── sample/
│   ├── generate_sample.py   # builds a synthetic demo report
│   ├── demo-findings.csv    # synthetic CSV output
│   ├── demo-report.xlsx     # synthetic Excel output
│   └── README.md            # describes the sample output
├── config.example.yaml      # accounts + role names (placeholders)
├── pyproject.toml
├── requirements.txt
├── .github/workflows/ci.yml # ruff + black --check + pytest
├── LICENSE
└── README.md

🚀 Installation & Usage

Install

git clone https://github.com/Muhammad-Imad/aws-cost-optimizer.git
cd aws-cost-optimizer

python -m venv .venv && source .venv/bin/activate
pip install -e .            # or: pip install -e ".[dev]" for tests + linters

Configure (multi-account)

Copy the example config and fill in your real account IDs and the name of a read-only audit role you've deployed into each account:

cp config.example.yaml config.yaml
$EDITOR config.yaml

Run

# Full audit of a single account using a named profile, writing both reports
aws-cost-optimizer report --profile acme-mgmt \
    --regions us-east-1,eu-west-1 \
    --output report.xlsx --csv-output findings.csv

# Full audit across every account in the config (assume-role + aggregate)
aws-cost-optimizer audit --profile acme-mgmt \
    --accounts-file config.yaml \
    --output fleet-report.xlsx

# Just hunt for unused / idle resources in one account
aws-cost-optimizer unused --profile acme-dev --regions us-east-1

# Just pull rightsizing recommendations
aws-cost-optimizer rightsize --profile acme-prod --output rightsizing.xlsx

Every command prints a one-line headline of the estimated monthly savings and the number of findings. Add -v/--verbose for debug logging.

Required IAM permissions

The role/profile the tool runs as only needs read access:

ce:GetCostAndUsage
ec2:Describe*
rds:DescribeDBInstances
cloudwatch:GetMetricStatistics
elasticloadbalancing:Describe*
s3:ListAllMyBuckets, s3:ListBucket
compute-optimizer:GetEC2InstanceRecommendations
sts:AssumeRole          # only the base profile, for multi-account runs

📊 Sample Output

A fully synthetic demo report lives in sample/ — generated by python sample/generate_sample.py with placeholder account IDs and fake resource IDs (no real data).

The Excel workbook contains a Summary sheet (headline monthly/annual savings + a savings-by-category breakdown) and per-category sheets for Cost by Service, MoM Trends, Unused Resources, and Rightsizing. The CSV is a flat, long-format export of every finding. In the demo dataset the headline is roughly $947/month of estimated savings across three accounts. See sample/README.md for the full schema.

🧭 Engineering Case Study

This tool grew out of a FinOps effort to bring cloud spend under control across a 50+ account AWS Organization. The cost surface had drifted: dozens of accounts owned by different teams, no consistent tagging, and spend that grew faster than usage.

Approach

• Visibility first. Centralized Cost Explorer pulls and month-over-month trend analysis exposed which services and accounts were driving growth, rather than arguing over a single monthly bill.
• Unused-resource cleanup. Automated sweeps for unattached EBS volumes, stale snapshots, unassociated Elastic IPs, idle RDS, and load balancers with no targets turned "we should clean that up someday" into a ranked, priced backlog the platform team could burn down.
• Rightsizing. Compute Optimizer recommendations plus CloudWatch utilization data identified chronically overprovisioned EC2 and RDS fleets; one-step downsizes were rolled out with change control.
• Cost governance. The Excel/CSV reports became a recurring artifact in a monthly cost review — owners, savings, and status tracked over time, with budgets and tagging standards enforced going forward.

Outcome

Recurring waste cleanup and rightsizing drove a sustained ~20–30% reduction in monthly compute and storage spend, with the largest single wins coming from EC2/RDS rightsizing and orphaned-storage cleanup. Just as importantly, the recurring report turned cost from a quarterly surprise into a governed, owned metric.

All figures here are representative ranges from generalized FinOps work; no specific employer, client, or confidential data is referenced.

📄 License

MIT © Muhammad Imad