🚀 CloudOps/FinOps Runbooks - Enterprise AWS Automation
Enterprise-Grade Production-Ready AWS automation toolkit for DevOps and SRE teams managing Multi-Account Hybrid-Cloud environments at Scale 🏢⚡
Quick Value: Discover, analyze, and optimize AWS resources across multi-account AWS environments with production-validated automation patterns.
Runbooks FinOps & AWS MCP Servers
The hybrid approach (Runbooks CloudOps/FinOps & AWS MCPs) leverages the strengths of both solutions: AWS MCPs for real-time accuracy data access and Runbooks FinOps for business intelligence and visualization, ensuring optimal cost optimization results for your enterprise environment.
🏆 5-Minute Success Path
Installation (30 seconds)
uv tool install runbooks # recommended (isolated, on PATH)
# or: pipx install runbooks
# or: pip install runbooks
runbooks --version
Choose Your Path
Pick a quickstart matching your role:
- 💼 Finance Leaders: CFO Quickstart — Monthly cost visibility + savings opportunities
- 🏗️ Technical Leaders: CTO Quickstart — Cloud Foundations assessment + compliance
- ☁️ CloudOps Engineers: CloudOps Quickstart — Multi-account resource discovery
- 🔄 DevOps Engineers: DevOps Quickstart — Validation + safe operations
- 🚨 SREs: SRE Quickstart — Security baseline + automated remediation
Each quickstart gets you to first working command in <5 minutes.
🎯 Why Runbooks?
| Feature | Benefit | Status |
|---|---|---|
| 🤖 AI-Agents Orchestration | AI-Agents FAANG SDLC coordination | ✅ Production Ready |
| ⚡ Blazing Performance | Sub-second CLI responses | ✅ 0.11s execution |
| 💰 Cost Analysis | Multi-account cost monitoring | ✅ Real-time analysis |
| 🔒 Enterprise Security | Zero-trust, compliance ready | ✅ SOC2, PCI-DSS, HIPAA |
| 🏗️ Multi-Account Ready | Universal AWS integration | ✅ 200+ accounts supported |
| 📊 Rich Reporting | Executive + technical dashboards | ✅ 15+ output formats |
📦 Core Modules
| Module | Purpose | Example |
|---|---|---|
| finops | Cost analysis + optimization | runbooks finops dashboard --all-profile |
| inventory | Multi-account discovery (88 resource types) | runbooks inventory collect --all-profile |
| org | AWS Organizations governance | runbooks org accounts --all-profile |
| security | Compliance baseline (15+ checks) | runbooks security assess --profile $AWS_PROFILE |
| cfat | Cloud Foundations assessment | runbooks cfat assess --all-profile |
| vpc | Network analysis | runbooks vpc analyze --profile $AWS_PROFILE |
| operate | Safe resource operations (dry-run default) | runbooks operate ec2 --help |
| remediation | Security finding remediation | runbooks remediation --help |
| cert | Certificate lifecycle | runbooks cert --help |
| validation | Data accuracy gates (≥99.5%) | runbooks validation status --profile $AWS_PROFILE |
Every module README under src/runbooks/<module>/ is a short pointer to its hub in docs/modules/ and its generated CLI reference in docs/reference/cli/.
Configuration
🎯 Choose Your Setup Path
| Use Case | AWS Accounts | Profile Setup | Best For |
|---|---|---|---|
| 🚀 Single-Account | 1 AWS account | 1 profile | Development, testing, small deployments |
| 🏢 Multi-Account | AWS Organizations | 3 profiles | Enterprise, production, Landing Zones |
💡 Quick Decision:
- Have 1 AWS account? → Use Path 1 (Single-Account Setup - 2 minutes)
- Have AWS Organizations with multiple accounts? → Use Path 2 (Multi-Account Setup - 5 minutes)
Path 1: Single-Account Setup (Quickstart - 2 minutes)
For developers, testing, or single AWS account operations:
# Set your AWS profile (ONE profile only)
export AWS_PROFILE="my-account-profile"
# Verify access
aws sts get-caller-identity --profile $AWS_PROFILE
# Expected output:
# {
# "UserId": "AIDAI...",
# "Account": "123456789012",
# "Arn": "arn:aws:iam::123456789012:user/yourname"
# }
Usage Example - Single Account:
# Discover EC2, RDS and S3 in your account
runbooks inventory collect --profile $AWS_PROFILE --resources ec2,rds,s3
# Analyze EC2 costs (single account)
runbooks finops analyze-ec2 --profile $AWS_PROFILE --output data/cost-analysis.json
Path 2: Multi-Account Setup (Enterprise - 5 minutes)
For organizations with AWS Organizations and multiple accounts:
# Set the 3 Landing Zone hub profiles once; `--all-profile` reads them
export AWS_MANAGEMENT_PROFILE="your-management-readonly-profile" # Organizations API
export AWS_BILLING_PROFILE="your-billing-readonly-profile" # Cost Explorer API
export AWS_OPERATIONS_PROFILE="your-operations-readonly-profile" # Config Aggregator / Resource Explorer
The API a command calls decides which hub profile --all-profile resolves to
(Organizations → management, Cost Explorer → billing, org-wide discovery → operations).
Details: docs/reference/profile-semantics.md.
Usage Example - Multi-Account:
# Org-wide cost dashboard (Cost Explorer via $AWS_BILLING_PROFILE)
runbooks finops dashboard --all-profile --mode executive --top-n 10
# Org-wide EC2 decommission scoring from an inventory export
runbooks finops ec2-decommission-analysis --all-profile --input data/resources.xlsx
# Discover resources across all organization accounts (Config Aggregator via $AWS_OPERATIONS_PROFILE)
runbooks inventory collect --all-profile --all-regions
# List accounts (Organizations via $AWS_MANAGEMENT_PROFILE)
runbooks inventory list-org-accounts --all-profile --format json --output accounts.json
⚡ Essential Commands Reference
Every command and flag below exists today; confirm with runbooks <group> <command> --help.
🔍 Discovery & Inventory
# Multi-service resource discovery
runbooks inventory collect --profile $AWS_PROFILE --resources ec2,s3,rds --csv
# Org-wide discovery through the Config Aggregator
runbooks inventory config-aggregator --all-profile --resource-types AWS::Lambda::Function
# Organization structure as a Mermaid diagram
runbooks inventory draw-org --all-profile --format mermaid
💰 Cost Management
# Multi-account cost dashboard
runbooks finops dashboard --all-profile --timeframe monthly
# Orphaned resources in one account
runbooks finops detect-orphans --profile $AWS_PROFILE --resource-type ebs
# Savings Plans + RI recommendations
runbooks finops optimize-savings-plans --all-profile --lookback-days 30
🔒 Security & Compliance
# Security baseline assessment
runbooks security assess --profile $AWS_PROFILE --framework soc2 --language EN
# Well-Architected assessment across all pillars
runbooks cfat assess --all-profile --all-pillars
# Findings for one host (Security Hub + GuardDuty + Inspector)
runbooks security host-findings --profile $AWS_PROFILE --resource-id i-1234567890abcdef0
⚙️ Resource Operations
# Safe EC2 operations (dry-run by default)
runbooks operate ec2 stop --profile $AWS_PROFILE --instance-ids i-1234567890abcdef0 --dry-run
# S3 bucket with encryption, versioning and public-access block
runbooks operate s3 create-bucket --profile $AWS_PROFILE --bucket-name my-bucket --encryption --versioning --public-access-block
# CloudFormation deployment
runbooks operate cloudformation deploy --profile $AWS_PROFILE --stack-name app --template-file app.yaml --dry-run
🏗️ Architecture Highlights
Modern Stack
- 🐍 Python 3.11+: Modern async capabilities
- ⚡ UV + Ruff: 10x faster dependency resolution & linting
- 🎨 Rich CLI: Beautiful terminal interfaces
- 📊 Pydantic V2: Type-safe data models
- 🔗 boto3: Native AWS SDK integration
- 🤖 MCP Servers: Real-time AWS API access (MCP Specification)
Enterprise Features
- 🔐 Multi-Profile AWS: Seamless account switching
- 🌐 Multi-Language Reports: EN/JP/KR/VN support
- 📈 DORA Metrics: DevOps performance tracking
- 🚨 Safety Controls: Dry-run defaults, approval workflows
- 📊 Executive Dashboards: Business-ready reporting
📚 Documentation
Quick Links
- 🏠 Homepage - Official project website
- 📖 Documentation - Complete guides
- 🐛 Issues - Bug reports & features
- 💬 Discussions - Community support
Enterprise Module Documentation
| Module | Documentation Hub | CLI Reference | Code |
|---|---|---|---|
| 💰 FinOps | Module Hub | cli/finops | src/runbooks/finops/ |
| 📊 Inventory | Module Hub | cli/inventory | src/runbooks/inventory/ |
| 🔒 Security | Module Hub | cli/security | src/runbooks/security/ |
| 🏛️ CFAT | Module Hub | cli/cfat | src/runbooks/cfat/ |
| 🔗 VPC | Module Hub | cli/vpc | src/runbooks/vpc/ |
| ⚙️ Operate | Module Hub | cli/operate | src/runbooks/operate/ |
🔧 Configuration
AWS Profiles Setup
# Landing Zone hub profiles (read by --all-profile)
export AWS_MANAGEMENT_PROFILE="your-management-readonly-profile"
export AWS_BILLING_PROFILE="your-billing-readonly-profile"
export AWS_OPERATIONS_PROFILE="your-operations-readonly-profile"
# Two flags only
runbooks finops dashboard --all-profile # org-wide (hub profiles above)
runbooks inventory collect --profile $AWS_PROFILE # one workload account
The older per-purpose profile flags (billing / management / ops) still parse with a deprecation warning and are removed in the next major version; new scripts use the two flags above.
Advanced Configuration
# Custom configuration directory
export RUNBOOKS_CONFIG_DIR="/path/to/config"
# Performance tuning
export RUNBOOKS_PARALLEL_WORKERS=10
export RUNBOOKS_TIMEOUT=300
🛡️ Security & Compliance
| Framework | Status | Coverage |
|---|---|---|
| AWS Well-Architected | ✅ Full | 5 pillars |
| SOC2 | ✅ Compliant | Type II ready |
| PCI-DSS | ✅ Validated | Level 1 |
| HIPAA | ✅ Ready | Healthcare compliant |
| ISO 27001 | ✅ Aligned | Security management |
🔧 Troubleshooting
Configuration Issues
Problem: "I set up 3 profiles but I only have 1 AWS account"
Solution: Single-account users only need 1 profile:
# ✅ CORRECT (Single Account):
export AWS_PROFILE="my-account-profile"
runbooks inventory collect --profile $AWS_PROFILE
# ❌ INCORRECT (don't do this for single account):
export AWS_OPERATIONS_PROFILE="my-account-profile"
export AWS_MANAGEMENT_PROFILE="my-account-profile"
export AWS_BILLING_PROFILE="my-account-profile"
When to use which setup:
- 1 Profile (AWS_PROFILE): You have a single AWS account for development/testing
- 3 Profiles (MANAGEMENT + BILLING + OPERATIONS): You have AWS Organizations with multiple member accounts
See Configuration section above for detailed setup instructions.
Problem: "Command fails with 'profile not found'"
Solution: Verify your AWS credentials are configured:
# Check if profile exists
aws configure list-profiles
# Verify profile access
aws sts get-caller-identity --profile YOUR_PROFILE_NAME
# Expected output should show Account ID and User ARN
If profile doesn't exist, configure it:
aws configure --profile YOUR_PROFILE_NAME
🆘 Support Options
Community Support (Free)
- 🐛 GitHub Issues - Bug reports & feature requests
- 💬 GitHub Discussions - Community Q&A
Enterprise Support
- 🏢 Professional Services - Custom deployment assistance
- 🎓 Training Programs - Team enablement workshops
- 🛠️ Custom Development - Tailored collector modules
- 📧 Email: https://www.linkedin.com/in/nnthanh/
📄 License
Apache License 2.0 - See LICENSE file for details.
📋 Release Notes
See CHANGELOG.md for the current release and migration notes.
🏗️ Built with ❤️ by the xOps team at OceanSoft
Transform your AWS operations from reactive to proactive with enterprise-grade automation 🚀
Metadata
Release files for runbooks 1.5.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| runbooks-1.5.11.tar.gz | 5.1 MB | Without provenance | Details for runbooks-1.5.11.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| runbooks-1.5.11-py3-none-any.whl | Python 3 | none | any | Details for runbooks-1.5.11-py3-none-any.whl |
Total release size: 9.5 MB
Release files / runbooks-1.5.11.tar.gz
| Download URL | runbooks-1.5.11.tar.gz |
|---|---|
| Size | 5.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
06bd18e24e473fcc26388ae5d848f859b07c4b546b9fbead24675beacb2ef34d
|
|
BLAKE2b-256 checksum How to use checksums |
85c899ac28e5e9fd5832ca787136ef0d5de8ca8ccbb64df58e50cb406a10124c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / runbooks-1.5.11-py3-none-any.whl
| Download URL | runbooks-1.5.11-py3-none-any.whl |
|---|---|
| Size | 4.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4227e33d7776449788271ab9cc813c8d3e8e2c2c5522f441ef4aed739ccff2b3
|
|
BLAKE2b-256 checksum How to use checksums |
180fc3df2588de9fad2ee934b5ae36b75e91eb419f0d279fc843c66145cd949c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for runbooks 1.5.11
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.