Metadata-Version: 2.4
Name: runbooks
Version: 1.5.11
Summary: CloudOps Automation Toolkit with Enhanced Cloud Foundations Assessment for DevOps and SRE teams.
Author-email: Maintainers <nnthanh101@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://cloudops.oceansoft.io
Project-URL: Repository, https://github.com/1xOps/runbooks
Project-URL: Documentation, https://cloudops.oceansoft.io/runbooks/
Project-URL: Issues, https://github.com/1xOps/runbooks/issues
Project-URL: Changelog, https://github.com/1xOps/runbooks/blob/main/CHANGELOG.md
Keywords: runbooks,automation,DevOps,SRE,CloudOps,AWS,cloud-foundations,FinOps,enterprise,cost-optimization,security-compliance,multi-account,business-intelligence
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: System :: Networking
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.35.40
Requires-Dist: botocore>=1.35.40
Requires-Dist: diagrams>=0.24.4
Requires-Dist: click>=8.2.1
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: markdown>=3.7.0
Requires-Dist: simplejson>=3.20.1
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: graphviz>=0.20.1
Requires-Dist: rich>=14.1.0
Requires-Dist: reportlab>=3.6.1
Requires-Dist: requests>=2.32.0
Requires-Dist: packaging>=21.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: jmespath>=1.0.1
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: urllib3>=2.6.3
Requires-Dist: openapi-spec-validator>=0.7.2
Requires-Dist: mcp>=1.12.3
Requires-Dist: pandas>=2.3.1
Requires-Dist: psutil>=7.0.0
Requires-Dist: xlsxwriter>=3.2.9
Requires-Dist: tabulate>=0.9.0
Requires-Dist: typer>=0.21.1
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: tenacity>=8.0.0
Requires-Dist: python-hcl2>=4.3
Requires-Dist: plotly>=7.0.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: scipy>=1.16.2
Requires-Dist: matplotlib>=3.10.5
Requires-Dist: seaborn>=0.13.2
Provides-Extra: focus
Requires-Dist: duckdb>=1.5.3; extra == "focus"
Dynamic: license-file

# 🚀 CloudOps/FinOps Runbooks - Enterprise AWS Automation

[![PyPI](https://img.shields.io/pypi/v/runbooks)](https://pypi.org/project/runbooks/)
[![Python](https://img.shields.io/pypi/pyversions/runbooks)](https://pypi.org/project/runbooks/)
[![License](https://img.shields.io/pypi/l/runbooks)](https://opensource.org/licenses/Apache-2.0)
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen)](https://cloudops.oceansoft.io/runbooks/)
[![Downloads](https://img.shields.io/pypi/dm/runbooks)](https://pypi.org/project/runbooks/)

> **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)
```bash
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](docs/business/cfo-quickstart.md) — Monthly cost visibility + savings opportunities
- **🏗️ Technical Leaders**: [CTO Quickstart](docs/business/cto-quickstart.md) — Cloud Foundations assessment + compliance
- **☁️ CloudOps Engineers**: [CloudOps Quickstart](docs/business/cloudops-quickstart.md) — Multi-account resource discovery
- **🔄 DevOps Engineers**: [DevOps Quickstart](docs/business/devops-quickstart.md) — Validation + safe operations
- **🚨 SREs**: [SRE Quickstart](docs/business/sre-quickstart.md) — 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>/`](src/runbooks/) is a short pointer to its hub in [`docs/modules/`](docs/modules/README.md) and its generated CLI reference in [`docs/reference/cli/`](docs/reference/cli/index.md).

### 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:**

```bash
# 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**:
```bash
# 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:**

```bash
# 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`](docs/reference/profile-semantics.md).

**Usage Example - Multi-Account**:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](https://modelcontextprotocol.io/))

### 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](https://cloudops.oceansoft.io)** - Official project website
- **📖 [Documentation](https://cloudops.oceansoft.io/runbooks/)** - Complete guides
- **🐛 [Issues](https://github.com/1xOps/CloudOps-Runbooks/issues)** - Bug reports & features
- **💬 [Discussions](https://github.com/1xOps/CloudOps-Runbooks/discussions)** - Community support

### Enterprise Module Documentation

| Module | Documentation Hub | CLI Reference | Code |
|--------|-------------------|---------------|------|
| 💰 **FinOps** | [Module Hub](docs/modules/finops/README.md) | [cli/finops](docs/reference/cli/finops.md) | [src/runbooks/finops/](src/runbooks/finops/) |
| 📊 **Inventory** | [Module Hub](docs/modules/inventory/README.md) | [cli/inventory](docs/reference/cli/inventory.md) | [src/runbooks/inventory/](src/runbooks/inventory/) |
| 🔒 **Security** | [Module Hub](docs/modules/security/README.md) | [cli/security](docs/reference/cli/security.md) | [src/runbooks/security/](src/runbooks/security/) |
| 🏛️ **CFAT** | [Module Hub](docs/modules/cfat/README.md) | [cli/cfat](docs/reference/cli/cfat.md) | [src/runbooks/cfat/](src/runbooks/cfat/) |
| 🔗 **VPC** | [Module Hub](docs/modules/vpc/README.md) | [cli/vpc](docs/reference/cli/vpc.md) | [src/runbooks/vpc/](src/runbooks/vpc/) |
| ⚙️ **Operate** | [Module Hub](docs/modules/operate/README.md) | [cli/operate](docs/reference/cli/operate.md) | [src/runbooks/operate/](src/runbooks/operate/) |

## 🔧 Configuration

### AWS Profiles Setup
```bash
# 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
```bash
# 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**:

```bash
# ✅ 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](#configuration) section above for detailed setup instructions.

#### Problem: "Command fails with 'profile not found'"

**Solution**: Verify your AWS credentials are configured:

```bash
# 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:
```bash
aws configure --profile YOUR_PROFILE_NAME
```

## 🆘 Support Options

### Community Support (Free)
- 🐛 **[GitHub Issues](https://github.com/nnthanh101/runbooks/issues)** - Bug reports & feature requests
- 💬 **[GitHub Discussions](https://github.com/nnthanh101/runbooks/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/](mailto:nnthanh101@gmail.com)

## 📄 License

Apache License 2.0 - See [LICENSE](LICENSE) file for details.

---

## 📋 Release Notes

See [CHANGELOG.md](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* 🚀
