8000 GitHub - angga-22/awswaste: Read-only CLI that finds AWS waste — idle and orphaned resources ranked by $/month, across one account or a whole org. · GitHub
[go: up one dir, main page]

Skip to content
angga-22Public

About

Read-only CLI that finds AWS waste — idle and orphaned resources ranked by $/month, across one account or a whole org.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

awswaste

Go Reference Go Report Card License: MIT

Find your AWS waste in seconds. A read-only CLI that reports idle and orphaned resources with dollar estimates — the Trusted Advisor cost checks you shouldn't need a Support plan for.

$ awswaste scan --profile prod
Account 123456789012 · regions: us-east-1, eu-west-1
┌──────────────────┬───────────────────┬───────────┬─────────┬──────┬────────────────────────────────────────┐
│ CHECK            │ RESOURCE          │ REGION    │ $/MO    │ CONF │ DETAIL                                 │
├──────────────────┼───────────────────┼───────────┼─────────┼──────┼────────────────────────────────────────┤
│ ebs-unattached   │ vol-0a1b2c3d4e5f  │ us-east-1 │ $400.00 │ High │ 5000 GB gp3, available since 2025-11-02│
│ nat-idle         │ nat-07f1a…        │ us-east-1 │  $32.85 │ Med  │ 0 bytes moved over 30d (threshold 1MB) │
│ eip-unassociated │ eipalloc-99887766 │ eu-west-1 │   $3.65 │ High │ Elastic IP 52.10.10.10 not associated  │
└──────────────────┴───────────────────┴───────────┴─────────┴──────┴────────────────────────────────────────┘
Estimated monthly waste: $436.50  (3 findings)
prices: estimates, updated 2026-06  ·  fix commands in --format json (never executed)

awswaste scan demo

Quickstart

# Go install (works today)
go install github.com/angga-22/awswaste/cmd/awswaste@latest

# Homebrew (from the first tagged release)
brew install --cask angga-22/tap/awswaste

awswaste scan --profile prod

awswaste uses the standard AWS credential chain — the same profiles/SSO sessions your aws CLI already uses. No passwords, no keys baked into the tool.

Common flags:

Flag Purpose
--profile <name> AWS shared-config profile (default: env/default chain)
--region <list> Comma-separated regions to scan (default: all enabled regions)
--format table|json|markdown Output format (json and markdown include the fix commands)
--days <n> Age/idle window in days (default 90)
--idle-bytes <n> Idle threshold for NAT traffic over the window (default 1 MiB)
--min-savings <n> Hide findings below this monthly $ amount
--only / --skip Run or skip specific checks, e.g. --only ebs-unattached,eip-unassociated
--prices <file.yaml> Override the embedded price table
--exit-code Exit 3 when unsuppressed findings exist — gate a CI job or cron alert on waste
--config <file.yaml> Config file (default: ./.awswaste.yaml if present); flags always win
--write-baseline Accept all current findings into .awswaste-baseline.yaml; future scans gate on new waste
--show-suppressed List suppressed findings instead of the one-line summary
--org --role-name <role> Scan every account in your AWS Organization (docs)
--accounts <ids> --role-name <role> Scan an explicit list of accounts
--role-arn <arn> Scan one account through an assumed role

Scan your whole org

awswaste scan --org --role-name awswasteReadOnly

One command: accounts are discovered via AWS Organizations, a read-only role is assumed in each, findings come back grouped per account (worst first) with a fleet-wide total. Unreachable accounts are skipped with a note, never fatal. Role deployment (one StackSet / Terraform module) and the hub/spoke policies are in docs/multi-account.md.

Gate CI on new waste

An account with 40 known findings is red forever — nobody can gate on that. awswaste separates the debt you've accepted from the waste someone just added:

awswaste scan --write-baseline   # accept today's findings (.awswaste-baseline.yaml, commit it)
awswaste scan --exit-code        # exit 0 — until someone adds NEW waste (then 3)

Human-authored suppressions (with reasons, and optional expiry) live in .awswaste.yaml, which can also hold default flags:

regions: [us-east-1, eu-west-1]
min-savings: 1
suppress:
  - check: ebs-unattached
    resource: vol-0abc123
    reason: "DR volume — keep until Q3 migration"
    expires: 2026-09-30        # finding reappears after this date
  - check: nat-idle
    account: "111122223333"    # optional narrowing; empty fields match anything
    region: us-east-1

Suppressed findings never disappear silently — every report carries one honest line (12 finding(s) suppressed (baseline) — $36.08/mo), and --show-suppressed lists them. Exit codes are locked: 0 clean or all suppressed, 1 execution error, 3 unsuppressed findings with --exit-code. A ready-to-copy GitHub Actions workflow is in docs/ci.md.

What it checks

Check What it flags Confidence
ebs-unattached EBS volumes in the available state (attached to nothing) High
ebs-gp2-gp3 In-use gp2 volumes — gp3 is ~20% cheaper, migrates online, deletes nothing High
eip-unassociated Elastic IPs with no association (idle EIPs bill hourly) High
ebs-snapshot-orphaned Self-owned snapshots older than --days and not referenced by any AMI High
ec2-stopped-ebs Instances stopped > --days whose EBS volumes keep billing Med-high
nat-idle Available NAT gateways moving < --idle-bytes over the window Med
elb-idle ALB/NLB load balancers with ≈0 traffic over the window Med
logs-no-retention Log groups that never expire and already store data (savings is a ceiling) High
ami-unused Self-owned AMIs older than --days referenced by no instance, launch template, or ASG Med
rds-idle DB instances with 0 connections over the window (stopped ones auto-restart after 7 days!) Med
ec2-old-generation Running prev-gen instances with a same-size, strictly-cheaper x86 successor (t2→t3, m4→m5, …) High

Skip a resource with the tag awswaste:ignore=true.

Deferred (scoped out on purpose, not forgotten): EC2 right-sizing (needs memory metrics for trustworthy calls), S3 lifecycle gaps (needs object-age analysis), Aurora Serverless idle detection, classic ELBs and ALB target-health inspection, and continuous monitoring. The full v2 plan is in docs/design/v2.md.

Read-only & safe

awswaste only calls Describe* / List* / Get* APIs — nothing it does can mutate a resource. The fix hints are printed (in --format json), never executed. Build trust before you build automation.

The full least-privilege policy is in docs/iam-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "awswasteReadOnly",
    "Effect": "Allow",
    "Action": [
      "sts:GetCallerIdentity",
      "ec2:DescribeRegions", "ec2:DescribeVolumes", "ec2:DescribeAddresses",
      "ec2:DescribeSnapshots", "ec2:DescribeImages", "ec2:DescribeInstances",
      "ec2:DescribeNatGateways",
      "ec2:DescribeLaunchTemplates", "ec2:DescribeLaunchTemplateVersions",
      "autoscaling:DescribeLaunchConfigurations",
      "elasticloadbalancing:DescribeLoadBalancers", "elasticloadbalancing:DescribeTags",
      "cloudwatch:GetMetricData",
      "logs:DescribeLogGroups",
      "rds:DescribeDBInstances"
    ],
    "Resource": "*"
  }]
}

Every action awswaste calls is in that list — nothing more. Resource: "*" is unavoidable for Describe APIs, but every action is read-only. If your credentials only cover some regions (e.g. an SCP or session policy restricts them), awswaste collapses the rest to one note: N region(s) skipped line rather than failing.

Alternatives

Tool Niche Why awswaste
AWS Trusted Advisor Cost checks behind a Support plan No paywall, runs locally
AWS Compute Optimizer Right-sizing only Covers orphaned/idle waste too
komiser Dashboard you host Zero-setup CLI
Infracost Pre-deploy Terraform estimates Scans what's actually running
cloud-custodian Policy engine Single command, ranked $ savings + fixes

The wedge: a zero-setup local CLI that ranks waste by dollars and hands you the fix command.

Roadmap

  • Scale: multi-account / AWS Organizations — shipped: --org.
  • Guardrail: config file, suppression baseline, CI gate — shipped: .awswaste.yaml + --write-baseline. GitHub Action repo still to come.
  • Checks: RDS idle, CloudWatch Logs retention, unused AMIs, old-generation EC2 — shipped.
  • Accuracy: price table generated from the AWS Pricing API — tools/genprices + monthly refresh workflow shipped (needs a pricing:GetProducts role to run; embedded table remains hand-estimated until the first generated snapshot lands).

Disclaimer

Savings are estimates, not invoices. awswaste ships a small embedded unit-price table (region-approximate, on-demand USD) and labels every report accordingly. Verify against the AWS Pricing page for your region before acting.

One known upper bound: AWS bills EBS snapshots on incremental stored bytes, which the API doesn't expose — ebs-snapshot-orphaned estimates from the full volume size, so its $/MO is a ceiling, not a midpoint.

awswaste is an independent open-source project and is not affiliated with, endorsed by, or sponsored by Amazon Web Services, Inc. "AWS" and all related marks are trademarks of Amazon.com, Inc. or its affiliates.

License

MIT

About

Read-only CLI that finds AWS waste — idle and orphaned resources ranked by $/month, across one account or a whole org.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0