aws-doctor

A terminal-based tool that acts as a comprehensive health check for your AWS accounts. Built with Golang, aws-doctor diagnoses cost anomalies, detects idle resources, and provides a proactive analysis of your cloud infrastructure.

[!TIP] View the full documentation, permissions guide, and usage examples at awsdoctor.compacompila.com

👀 Quick glance

⚖️ Comparative Cost Analytics

📈 6-Month Trend Analysis

🧟 Waste Detection

Supports selective scanning: aws-doctor waste ec2 s3 cloudwatch rds vpc lambda sagemaker elb ecr secrets-manager iam

• Interactive Terminal UI: Navigate seamlessly through detected waste categories using your keyboard arrows or tabs, complete with an aggregated Summary view.
• Graceful Degradation: Running in CI/CD? aws-doctor automatically detects if it's being piped or redirected and gracefully falls back to static tables.

📄 Professional Reporting

aws-doctor can now generate detailed, professional PDF reports ready for stakeholders. Reports include branded headers, styled tables, and comprehensive cost/waste analyses.

[!TIP] View PDF reporting examples and details at awsdoctor.compacompila.com/docs/reporting/

Generate a Cost Comparison Report

aws-doctor report cost

Generate a Waste Analysis Report

# Full waste report
aws-doctor report waste

# Selective checks (e.g., ec2, s3, and lambda only)
aws-doctor report waste ec2 s3 lambda sagemaker

Generate a Trend Report

# Full trend report (all services)
aws-doctor report trend

# Selective services (e.g., ec2 and rds only)
aws-doctor report trend ec2 rds

[!TIP] Subcommand Arguments: Just like the terminal commands, report waste accepts specific checks (e.g., ec2, s3, rds, lambda) and report trend accepts specific service names.

[!TIP] By default, reports are saved in your Documents folder. Use the --path flag to specify a custom directory or filename: aws-doctor report cost --path ./billing-analysis.pdf

🚀 Installation

Homebrew (macOS/Linux):

brew install elC0mpa/homebrew-tap/aws-doctor

One-Line Script (macOS/Linux):

curl -sSfL https://raw.githubusercontent.com/elC0mpa/aws-doctor/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/elC0mpa/aws-doctor/main/install.ps1 | iex

Using Go:

go install github.com/elC0mpa/aws-doctor@latest

✨ Key Features

• 📄 Professional PDF Reports: Generate branded, ready-to-share PDF documents for costs, trends, and waste analysis.
• 📉 Fair Cost Comparison: Compares identical time windows between months to spot real anomalies.
• 🧟 Zombie Discovery: Scans for idle EIPs, stopped instances, idle running EC2 instances, orphaned snapshots, idle RDS instances, idle NAT Gateways, idle Load Balancers, over-provisioned Lambda memory, idle SageMaker real-time inference endpoints, ECR repositories with untagged images, missing lifecycle policies, or no images at all, unused Secrets Manager secrets, and unused IAM users or Root accounts without MFA. Supports selective service filtering (ec2, s3, elb, cloudwatch, rds, vpc, lambda, sagemaker, ecr, secrets-manager, iam).
• 📊 6-Month Trends: High-fidelity ANSI visualization of your spending velocity.
• 📤 Multiple Output Formats: Export results in table, json, or csv for easy integration with other tools or reporting.
• 🔔 Update Notifications: Automatically checks for new versions in the background and notifies you after command output.
• 🚀 Efficient Caching: Uses a local cache service to minimize redundant network calls. Currently used for version check notifications (2-hour TTL) and slated for expansion to pricing data and other heavy flows.
• 🔐 MFA Ready: Native support for profiles requiring Multi-Factor Authentication.
• 🌍 Region-Aware Pricing: Queries the AWS Pricing API at startup to use rates for the configured region, falling back to us-east-1 defaults if the API is unavailable. Requires pricing:GetProducts in the caller's IAM policy; without it, estimates silently fall back to defaults.

💡 Motivation

As a Cloud Architect, I often need to check AWS costs and billing information. While the AWS Console provides raw data, it lacks the immediate context I need to answer the question: "Are we spending efficiently?"

I created *aws-doctor* to fill that gap. It doesn't just show you the bill; it acts as a diagnostic tool that helps you understand *where* the money is going and *what* can be cleaned up. It automates the routine checks I used to perform manually, serving as a free, open-source alternative to the paid recommendations found in AWS Trusted Advisor.

👥 Community

Contributors

A huge thank you to everyone who has contributed to aws-doctor! Your help makes this tool better for everyone.

Star History

🤝 Contributing

We love contributions! Whether it's a new detection rule or a bug fix, check our Community Dashboard to get started.

[!IMPORTANT] Always target your Pull Requests to the development branch. The main branch is reserved for production-ready releases. Check our Contributing Guidelines for more details.