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

📄 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 and s3 only)
aws-doctor report waste ec2 s3

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) 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

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, orphaned snapshots, idle RDS instances, and more. Supports selective service filtering (ec2, s3, elb, cloudwatch, rds).
• 📊 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.
• 🔐 MFA Ready: Native support for profiles requiring Multi-Factor Authentication.

💡 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.

🤝 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.