runbooks 0.7.0__tar.gz → 0.7.6__tar.gz

runbooks-0.7.6/PKG-INFO

@@ -0,0 +1,608 @@
+Metadata-Version: 2.4
+Name: runbooks
+Version: 0.7.6
+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/CloudOps-Runbooks
+Project-URL: Documentation, https://cloudops.oceansoft.io/runbooks/
+Project-URL: Issues, https://github.com/1xOps/CloudOps-Runbooks/issues
+Project-URL: Changelog, https://github.com/1xOps/CloudOps-Runbooks/blob/main/CHANGELOG.md
+Keywords: runbooks,automation,DevOps,SRE,CloudOps,AWS,cloud-foundations,FinOps
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+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: Topic :: System :: Systems Administration
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: <3.14,>=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: jinja2>=3.1.4
+Requires-Dist: werkzeug>=3.1.0
+Requires-Dist: markdown>=3.7.0
+Requires-Dist: prettytable>=3.16.0
+Requires-Dist: simplejson>=3.20.1
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: graphviz>=0.20.1
+Requires-Dist: rich>=14.0.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: urllib3<1.27,>=1.26.18
+Requires-Dist: mcp>=1.12.3
+Dynamic: license-file
+
+# 🚀 CloudOps Runbooks - Enterprise AWS Automation Toolkit
+
+[![PyPI Version](https://img.shields.io/pypi/v/runbooks)](https://pypi.org/project/runbooks/)
+[![Python Support](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/)
+[![CI/CD](https://img.shields.io/github/actions/workflow/status/1xOps/CloudOps-Runbooks/ci.yml?branch=main)](https://github.com/1xOps/CloudOps-Runbooks/actions)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Type Checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)
+[![Tests: pytest](https://img.shields.io/badge/tests-pytest-green.svg)](https://pytest.org/)
+
+> **Enterprise-grade AWS automation toolkit for cloud operations (SRE and DevOps teams) at scale**
+
+CloudOps Runbooks provides comprehensive AWS resource discovery, inventory management, and automation capabilities with enterprise-grade architecture, type safety, and validation.
+
+
+## 🚀 Overview
+
+CloudOps Runbooks is a production-ready AWS automation framework that combines traditional scripting excellence with modern AI orchestration. Designed for enterprises managing complex multi-account AWS environments, it delivers comprehensive discovery, intelligent analysis, and automated remediation across 50+ AWS services.
+
+> Why CloudOps Runbooks?
+
+- **🎯 Proven in Production**: Deployed across enterprises managing 50+ AWS accounts
+- **🤖 AI-Ready Architecture**: Native integration with AI-Agents and MCP-servers
+- **⚡ Blazing Fast**: Parallel execution reducing discovery time by 60%
+- **🔒 Enterprise Security**: Zero-trust validation, compliance automation, and audit trails
+- **💰 Cost Intelligence**: Identifies 25-50% optimization opportunities automatically
+- **🏗️ AWS Landing Zone Native**: Purpose-built for Multi-Organizations Landing Zone
+
+## 🌟 Key Features
+
+### 🔍 **Comprehensive AWS Discovery**
+- **Multi-Account Inventory**: Seamless discover resources (EC2, RDS, Lambda, ECS, S3, IAM, and more) across entire AWS Organizations
+- **Cross-Region Support**: Parallel scanning of all available AWS regions  
+- **Resource Coverage**: 50+ AWS resource types across all major services
+- **Real-time Collection**: Concurrent collection with progress tracking
+
+### 🏗️ **Enterprise Architecture**
+- **Type Safety**: Full Pydantic V2 models with runtime validation
+- **Modular Design**: Service-specific collectors with common interfaces
+- **Extensibility**: Easy to add new collectors and resource types
+- **Error Handling**: Comprehensive error tracking and retry logic
+
+
+### Hybrid Intelligence Integration
+
+- **MCP Server Integration**: Real-time AWS API access without custom code
+- **AI Agent Orchestration**: AI-powered analysis and recommendations
+- **Evidence Pipeline**: Unified data normalization and correlation
+- **Intelligent Prioritization**: ML-based resource targeting
+
+### 💰 **Cost Integration**
+- **Cost Estimation**: Automatic cost calculations for billable resources
+- **Cost Analytics**: Cost breakdown by service, account, and region
+- **Budget Tracking**: Resource cost monitoring and alerting
+
+### 📊 **Multiple Output Formats**
+- **Structured Data**: JSON, CSV, Excel, Parquet
+- **Visual Reports**: HTML reports with charts and graphs
+- **Console Output**: Rich table formatting with colors
+- **API Integration**: REST API for programmatic access
+
+### 🔒 **Security & Compliance**
+- **IAM Integration**: Role-based access control
+- **Audit Logging**: Comprehensive operation logging
+- **Encryption**: Secure credential management
+- **Compliance Reports**: Security and compliance validation
+
+## 🚀 Quick Start Excellence: Progressive Examples
+
+### 📦 Installation
+
+```bash
+# Install using UV (recommended for speed and reliability)
+uv add runbooks
+
+# Or using pip
+pip install runbooks
+
+# Development installation
+git clone https://github.com/1xOps/CloudOps-Runbooks.git
+cd CloudOps-Runbooks
+uv sync --all-extras --dev
+```
+
+### 🎯 **Modern CLI Commands Overview**
+
+CloudOps Runbooks now provides enterprise-grade CLI commands for comprehensive AWS operations:
+
+```bash
+# 🎯 STANDARDIZED CLI (Human & AI-Agent Friendly) v0.7.3
+runbooks --help                    # Main CLI help
+runbooks inventory collect         # Read-only discovery & analysis
+runbooks operate ec2 start         # Resource lifecycle operations
+runbooks cfat assess               # Cloud Foundations Assessment
+runbooks security assess           # Security Baseline Testing  
+runbooks org list-ous              # Organizations Management
+runbooks finops dashboard          # Cost and Usage Analytics
+
+# 🤖 AI-Agent Optimized: Consistent options across all commands
+# --profile, --region, --dry-run, --output, --force (where applicable)
+```
+
+### 🔰 Level 1: Basic Single Account Discovery
+
+**Goal**: Discover EC2 instances in your current AWS account
+
+```bash
+# Set up your AWS credentials
+export AWS_PROFILE="your-aws-profile"
+aws sts get-caller-identity  # Verify access
+
+# Basic EC2 instance discovery
+cd CloudOps-Runbooks
+python src/runbooks/inventory/list_ec2_instances.py --profile $AWS_PROFILE --regions us-east-1 --timing
+
+# Example output:
+# Finding instances from 1 locations: 100%|██████████| 1/1 [00:02<00:00,  2.43 locations/s]
+# Found 12 instances across 1 account across 1 region
+# This script completed in 3.45 seconds
+```
+
+### 🏃 Level 2: Multi-Service Resource Discovery 
+
+**Goal**: Discover multiple AWS resource types efficiently
+
+```bash
+# EBS Volumes with orphan detection
+python src/runbooks/inventory/list_ec2_ebs_volumes.py --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+
+# Lambda Functions with cost analysis
+python src/runbooks/inventory/list_lambda_functions.py --profile $AWS_PROFILE --regions ap-southeast-2
+
+# RDS Instances across multiple regions
+python src/runbooks/inventory/list_rds_db_instances.py --profile $AWS_PROFILE --regions us-east-1,eu-west-1,ap-southeast-2
+
+# Security Groups analysis
+python src/runbooks/inventory/find_ec2_security_groups.py --profile $AWS_PROFILE --regions us-east-1 --defaults
+```
+
+### 🏢 Level 3: Enterprise Multi-Account Operations
+
+**Goal**: Organization-wide resource discovery and compliance
+
+```bash
+# Comprehensive inventory across AWS Organizations
+python src/runbooks/inventory/list_org_accounts.py --profile $AWS_PROFILE
+
+# Multi-account CloudFormation stack discovery
+python src/runbooks/inventory/list_cfn_stacks.py --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+
+# Organization-wide GuardDuty detector inventory
+python src/runbooks/inventory/list_guardduty_detectors.py --profile $AWS_PROFILE --regions ap-southeast-2
+
+# CloudTrail compliance validation
+python src/runbooks/inventory/check_cloudtrail_compliance.py --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+```
+
+### 🚀 Level 4: Autonomous Testing Framework
+
+**Goal**: Automated testing and validation of entire inventory suite
+
+```bash
+# Test individual script
+./src/runbooks/inventory/inventory.sh list_ec2_instances.py --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+
+# Test specific script category with detailed analysis
+./src/runbooks/inventory/inventory.sh list_ec2_ebs_volumes.py --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+
+# Full autonomous test suite (20+ core scripts)
+./src/runbooks/inventory/inventory.sh all --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+
+# Review test results and analysis
+ls test_logs_*/
+cat test_logs_*/test_execution.log
+```
+
+### 🔬 Level 5: Advanced Integration & Analysis
+
+**Goal**: Production-grade automation with comprehensive reporting
+
+```bash
+# 1. VPC Network Discovery with Subnet Analysis
+python src/runbooks/inventory/list_vpc_subnets.py --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+python src/runbooks/inventory/list_vpcs.py --profile $AWS_PROFILE --regions ap-southeast-2
+
+# 2. Load Balancer Infrastructure Mapping
+python src/runbooks/inventory/list_elbs_load_balancers.py --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+
+# 3. IAM Security Posture Assessment
+python src/runbooks/inventory/list_iam_roles.py --profile $AWS_PROFILE --timing
+python src/runbooks/inventory/list_iam_policies.py --profile $AWS_PROFILE --timing
+
+# 4. ECS Container Platform Discovery
+python src/runbooks/inventory/list_ecs_clusters_and_tasks.py --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+
+# 5. Network Interface and ENI Analysis
+python src/runbooks/inventory/list_enis_network_interfaces.py --profile $AWS_PROFILE --regions ap-southeast-2 --timing
+```
+
+### 🎯 Level 6: Specialized Operations
+
+**Goal**: Advanced scenarios for specific use cases
+
+```bash
+# 1. Landing Zone Readiness Assessment
+python src/runbooks/inventory/check_landingzone_readiness.py --profile $AWS_PROFILE
+
+# 2. CloudFormation Drift Detection
+python src/runbooks/inventory/find_cfn_drift_detection.py --profile $AWS_PROFILE --regions ap-southeast-2
+
+# 3. Organizations Structure Analysis
+python src/runbooks/inventory/list_org_accounts_users.py --profile $AWS_PROFILE --timing
+
+# 4. Config Compliance Monitoring
+python src/runbooks/inventory/list_config_recorders_delivery_channels.py --profile $AWS_PROFILE --regions ap-southeast-2
+
+# 5. Route53 DNS Infrastructure
+python src/runbooks/inventory/list_route53_hosted_zones.py --profile $AWS_PROFILE --timing
+```
+
+### 📊 Integration Examples
+
+**Modern Architecture Integration:**
+
+```python
+# collectors/ and core/ directories provide modern modular architecture
+from runbooks.inventory.collectors.aws_compute import ComputeCollector
+from runbooks.inventory.core.collector import InventoryCollector
+from runbooks.inventory.core.formatter import OutputFormatter
+
+# Enterprise-grade type-safe collection
+collector = InventoryCollector(profile='production')
+results = collector.collect_compute_resources(include_costs=True)
+formatter = OutputFormatter()
+report = formatter.generate_html_report(results)
+```
+
+## 🏢 **Level 7: Enterprise CLI Operations**
+
+### **AWS Resource Operations**
+
+**Goal**: Comprehensive AWS resource lifecycle management with enterprise safety features
+
+```bash
+# EC2 Instance Operations
+runbooks operate ec2 start --instance-ids i-1234567890abcdef0 --profile production
+runbooks operate ec2 stop --instance-ids i-1234567890abcdef0 i-0987654321fedcba0 --dry-run
+runbooks operate ec2 terminate --instance-ids i-1234567890abcdef0 --force
+
+# S3 Bucket Operations with Security Best Practices
+runbooks operate s3 create-bucket --bucket-name secure-prod-bucket \
+  --encryption --versioning --public-access-block --region us-west-2
+runbooks operate s3 delete-bucket-and-objects --bucket-name old-test-bucket --dry-run
+runbooks operate s3 set-public-access-block --account-id 123456789012 --profile management
+
+# CloudFormation StackSet Operations
+runbooks operate cloudformation move-stack-instances \
+  --source-stackset-name old-baseline --target-stackset-name new-baseline \
+  --account-ids 111111111111,222222222222 --regions us-east-1,us-west-2 --dry-run
+runbooks operate cloudformation lockdown-stackset-role \
+  --target-role-name AWSCloudFormationStackSetExecutionRole \
+  --management-account-id 123456789012
+
+# IAM Cross-Account Role Management
+runbooks operate iam update-roles-cross-accounts \
+  --role-name CrossAccountAccessRole \
+  --trusted-account-ids 111111111111,222222222222 \
+  --external-id MySecureExternalId --require-mfa
+
+# CloudWatch Log Management
+runbooks operate cloudwatch update-log-retention-policy \
+  --retention-days 30 --update-all-log-groups --profile production
+
+# DynamoDB Table Operations
+runbooks operate dynamodb create-table \
+  --table-name user-sessions --hash-key user_id --range-key session_id \
+  --billing-mode PAY_PER_REQUEST --tags Environment=production Team=backend
+runbooks operate dynamodb backup-table --table-name critical-data --backup-name weekly-backup
+runbooks operate dynamodb delete-table --table-name temp-table --confirm --dry-run
+
+# Cross-Service Resource Tagging
+runbooks operate tag apply-template --template production \
+  --resource-arns arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0
+```
+
+### **Cloud Foundations Assessment Tool (CFAT)**
+
+**Goal**: Comprehensive AWS account assessment against best practices
+
+```bash
+# Basic CFAT assessment with HTML report
+runbooks cfat assess --profile production
+
+# Multiple output formats with compliance framework
+runbooks cfat assess --profile prod \
+  --compliance-framework "AWS Well-Architected" \
+  --output all \
+  --serve-web --web-port 8080
+
+# Targeted assessment with specific categories
+runbooks cfat assess --profile dev \
+  --categories iam,s3,vpc \
+  --severity CRITICAL \
+  --parallel --max-workers 10
+
+# Export results to project management tools
+runbooks cfat assess --profile staging \
+  --export-jira --export-asana \
+  --output json
+```
+
+### **Security Baseline Assessment**
+
+**Goal**: Multi-language security compliance validation
+
+```bash
+# Comprehensive security assessment (English)
+runbooks security assess --profile production --language EN
+
+# Localized security reports for global teams
+runbooks security assess --profile prod-asia \
+  --language JP --format html --output /reports/security
+
+# Run specific security checks
+runbooks security check root_mfa --profile management
+runbooks security check iam_password_policy --profile prod
+
+# List available security checks
+runbooks security list-checks
+
+# Multiple checks with JSON output
+runbooks security assess --profile dev \
+  --checks root_mfa --checks bucket_public_access \
+  --format json
+```
+
+### **AWS Organizations Management**
+
+**Goal**: Enterprise OU structure setup and management
+
+```bash
+# List current organizational structure
+runbooks org list-ous --profile management --output table
+
+# Setup standard OU structure (dry-run first)
+runbooks org setup-ous --profile management \
+  --template standard --dry-run
+
+# Create production OU structure
+runbooks org setup-ous --profile management \
+  --template security
+
+# Custom OU structure from file
+runbooks org setup-ous --profile management \
+  --file custom-ou-structure.yaml
+
+# Export OU structure to different formats
+runbooks org list-ous --profile management --output json > ou-structure.json
+runbooks org list-ous --profile management --output yaml > ou-structure.yaml
+
+# Delete empty organizational unit (with confirmation)
+runbooks org delete-ou ou-1234567890abcdef --confirm
+```
+
+### **Advanced Multi-Command Workflows**
+
+**Goal**: Combine multiple tools for comprehensive AWS operations
+
+```bash
+# 1. Complete AWS account assessment and remediation workflow
+echo "🔍 Step 1: Security Baseline Assessment"
+runbooks security assess --profile prod --language EN --format json > security-report.json
+
+echo "🏗️ Step 2: Cloud Foundations Assessment"  
+runbooks cfat assess --profile prod --output all --compliance-framework "AWS Well-Architected"
+
+echo "🏢 Step 3: Organizations Structure Review"
+runbooks org list-ous --profile management --output yaml > current-ou-structure.yaml
+
+echo "📊 Step 4: Resource Inventory"
+runbooks inventory collect -r ec2 -r s3 --profile prod --output json > resource-inventory.json
+
+echo "⚙️ Step 5: Automated Remediation"
+runbooks operate s3 set-public-access-block --account-id 123456789012 --profile management
+runbooks operate cloudwatch update-log-retention-policy --retention-days 90 --update-all
+runbooks operate tag apply-template --template production --resource-arns $(cat resource-inventory.json | jq -r '.ec2[].arn')
+
+# 2. Setup new AWS environment workflow with security hardening
+echo "🚀 Setting up new secure AWS environment"
+runbooks org setup-ous --template security --profile management
+runbooks operate s3 set-public-access-block --account-id NEW_ACCOUNT_ID --profile management
+runbooks operate iam update-roles-cross-accounts --role-name CrossAccountAuditRole --trusted-account-ids AUDIT_ACCOUNT_ID
+runbooks security assess --profile new-account --language EN
+runbooks cfat assess --profile new-account --categories iam,s3,vpc,security --output html
+
+# 3. Disaster recovery and cleanup workflow
+echo "🔧 Emergency cleanup and recovery"
+runbooks operate ec2 stop --instance-ids $(runbooks inventory collect -r ec2 --filter state=running --output json | jq -r '.[].InstanceId') --dry-run
+runbooks operate s3 delete-bucket-and-objects --bucket-name old-backup-bucket --dry-run
+runbooks operate cloudformation move-stack-instances --source-stackset old-infra --target-stackset new-infra --dry-run
+
+# 4. Compliance and governance workflow  
+echo "📋 Running compliance checks and governance"
+runbooks security assess --profile all-accounts --format json
+runbooks cfat assess --profile all-accounts --compliance-framework "SOC2" --export-jira
+runbooks org list-ous --profile management --output json
+runbooks operate tag apply-template --template compliance --resource-arns $(runbooks inventory collect --profile all-accounts | jq -r '.[].arn')
+```
+
+### 📈 Performance & Success Metrics
+
+**Enterprise CLI Results (Latest v0.7.3):**
+- ✅ **Production-Ready CLI**: 18+ complete AWS operations across all major services
+- ✅ **Complete EC2 Operations**: 7/7 commands (start, stop, terminate, run, copy, cleanup)
+- ✅ **Complete S3 Operations**: 3/3 commands (create, delete, public-access-block)
+- ✅ **Enterprise CloudFormation**: 3/3 commands (move-instances, lockdown-role, update-stacksets)
+- ✅ **IAM & CloudWatch**: Complete operational commands for enterprise management
+- ✅ **DynamoDB Operations**: 3/3 commands (create-table, delete-table, backup-table)
+- ✅ **KISS Architecture**: No legacy directories - clean, maintainable codebase
+- ✅ **Standardized CLI**: Consistent options across all commands for human & AI-Agent use
+- ✅ **Complete Migration**: All AWS operations properly categorized (inventory vs operate)
+- ✅ **CFAT Module**: Fully integrated with enterprise features and web reporting
+- ✅ **Security Module**: 15+ security checks with multi-language support (EN, JP, KR, VN)
+- ✅ **Organizations Module**: Complete OU management with template-based setup
+- ✅ **Legacy Inventory**: 20/43 core scripts passing (47% success rate) - maintained compatibility
+- ⚡ **Performance**: 8-12 seconds average execution, parallel processing support
+- 🏗️ **Architecture**: Modern modular design with collectors/, core/, operate/, and assessment/ directories
+- 🔧 **Integration**: Enhanced with EC2, S3, CloudFormation, IAM, and CloudWatch operations
+- 🤖 **AI-Agent Ready**: Predictable CLI patterns, consistent error handling, standardized outputs
+
+## 📋 Architecture Overview
+
+### 🏗️ **Enterprise Module Structure**
+
+```
+src/runbooks/
+├── 🏛️ cfat/                     # Cloud Foundations Assessment Tool
+│   ├── assessment/             # Assessment engine and runners
+│   │   ├── runner.py          # CloudFoundationsAssessment (enhanced)
+│   │   ├── collectors.py      # AWS resource collection logic
+│   │   └── validators.py      # Compliance rule validation
+│   ├── reporting/              # Multi-format report generation
+│   │   ├── formatters.py      # HTML, JSON, CSV, Markdown generators
+│   │   ├── templates.py       # Executive, Technical, Compliance templates
+│   │   └── exporters.py       # Jira, Asana, ServiceNow integration
+│   ├── tests/                 # Comprehensive test suite
+│   ├── models.py              # Pydantic data models with validation
+│   └── cli.py                 # Enterprise CLI with web server
+├── 🔒 security/                # Security Baseline Assessment  
+│   ├── checklist/             # 15+ security validation modules
+│   ├── security_baseline_tester.py  # Multi-language assessment engine
+│   ├── report_generator.py    # HTML reports with remediation
+│   └── utils/                 # Security-specific utilities
+├── 📊 inventory/               # Multi-account Resource Discovery
+│   ├── core/                  # Business Logic & Orchestration
+│   │   ├── collector.py       # Main inventory orchestration engine
+│   │   ├── formatter.py       # Multi-format output handling  
+│   │   └── session_manager.py # AWS session management
+│   ├── collectors/            # Specialized Resource Collectors
+│   │   ├── base.py           # Abstract base collector interface
+│   │   ├── aws_compute.py    # EC2, Lambda, ECS, Batch
+│   │   ├── aws_networking.py # VPC, ELB, Route53, CloudFront
+│   │   └── aws_management.py # Organizations, CloudFormation, SSM
+│   ├── models/               # Type-safe Data Structures  
+│   │   ├── account.py        # AWS account representation
+│   │   ├── resource.py       # Resource models with metadata
+│   │   └── inventory.py      # Collection results and analytics
+│   ├── utils/                # Shared Utilities & Helpers
+│   │   ├── aws_helpers.py    # AWS session and API utilities
+│   │   ├── threading_utils.py # Concurrent execution helpers
+│   │   └── validation.py     # Input validation and sanitization
+│   └── 📜 legacy/             # Legacy Script Compatibility
+│       └── migration_guide.md # Legacy script migration guide
+├── ⚙️ operate/                 # AWS Resource Operations (v0.7.3 - KISS Principle)
+│   ├── base.py               # Abstract operation framework
+│   ├── ec2_operations.py     # Complete EC2 lifecycle operations
+│   ├── s3_operations.py      # Complete S3 bucket and object operations
+│   ├── dynamodb_operations.py # DynamoDB table operations
+│   ├── cloudformation_operations.py # CloudFormation and StackSet operations
+│   ├── iam_operations.py     # IAM role and policy operations
+│   ├── cloudwatch_operations.py # CloudWatch logs and metrics
+│   ├── tagging_operations.py # Cross-service resource tagging
+│   └── tags.json            # Shared tag templates (no legacy complexity)
+├── 💰 finops/                  # Cost and Usage Analytics
+├── 🛠️ utils/                   # Core Framework Utilities
+├── 🧪 tests/                   # Enterprise Test Framework
+└── 📖 docs/                    # Comprehensive Documentation
+```
+
+## 🧪 Testing & Development
+
+### Running Tests
+
+```bash
+# Run full test suite
+task test
+
+# Run specific test categories
+pytest tests/unit/test_inventory.py -v
+pytest tests/integration/test_collectors.py -v
+
+# Test with coverage
+task _test.coverage
+
+# Test inventory module specifically
+task inventory.test
+```
+
+### Development Workflow
+
+```bash
+# Install development dependencies
+task install
+
+# Code quality checks
+task code_quality
+
+# Validate module structure
+task inventory.validate
+
+# Full validation workflow
+task validate
+```
+
+## 📚 Documentation
+
+- [API Reference](docs/api-reference.md)
+- [Configuration Guide](docs/configuration.md)
+- [Migration Guide](src/runbooks/inventory/legacy/migration_guide.md)
+- [Contributing Guide](CONTRIBUTING.md)
+
+
+## 🚦 Roadmap
+
+- **v1.0** (Q4 2025): Enhanced AI agent orchestration
+- **v1.5** (Q1 2026): Self-healing infrastructure capabilities
+
+## 📝 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+### Community
+- [GitHub Issues](https://github.com/1xOps/CloudOps-Runbooks/issues)
+- [Discussions](https://github.com/1xOps/CloudOps-Runbooks/discussions)
+
+### Enterprise Support
+- Professional services and training available
+- Custom collector development
+- Enterprise deployment assistance
+- Contact: [info@oceansoft.io](mailto:info@oceansoft.io)
+
+---
+
+**Built with ❤️ by the xOps team at OceanSoft**
+
+[Website](https://cloudops.oceansoft.io) • [Documentation](https://cloudops.oceansoft.io/runbooks/) • [GitHub](https://github.com/1xOps/CloudOps-Runbooks)