runbooks 0.6.1__py3-none-any.whl → 0.7.5__py3-none-any.whl

runbooks/{security_baseline → security}/README.md

@@ -2,25 +2,58 @@
 
 ## 📖 Overview
 
-The **CloudOps Runbooks: Security Baseline Assessment** is a comprehensive tool designed to evaluate the security of AWS environments in accordance with basic security advisories. It provides a structured way to assess your account and workload configurations against **AWS security best practices** and the **AWS Startup Security Baseline (SSB)**. This tool supports **Python (via pip or Docker)** and **AWS Lambda** deployments, offering flexibility for local testing, CI/CD integration, and scalable cloud execution.
+The **CloudOps Runbooks: Security Baseline Assessment** is a comprehensive tool designed to evaluate the security of AWS environments in accordance with basic security advisories. It provides a structured way to assess your account and workload configurations against **AWS security best practices** and the **AWS Startup Security Baseline (SSB)**. 
+
+**Fully integrated with the CloudOps Runbooks CLI**, this tool offers enterprise-grade security assessment capabilities with multilingual reporting, parallel execution, and comprehensive remediation guidance. The tool is designed for DevOps teams, SRE engineers, and security professionals who need automated, actionable security insights.
 
 By automating **15+ critical AWS account security and workload security checks**, this solution empowers startups, enterprises, and DevOps teams to validate their cloud security posture, generate actionable reports, and align with AWS Well-Architected principles.
 
+Key capabilities include:
+- **Enterprise CLI Integration**: Seamlessly integrated with `runbooks security` commands
+- **Multilingual Reports**: Generate reports in English, Japanese, Korean, and Vietnamese
+- **Parallel Execution**: Fast assessment with configurable worker pools
+- **Rich Console Output**: Beautiful terminal output with progress indicators
+- **Multiple Output Formats**: HTML reports with actionable remediation steps
+
 In the **Test Report**, we provide numerous techniques for successfully responding to security threats on AWS with minimal resources. This script is appropriate for usage by early-stage businesses that cannot afford to invest much in security. 
 
 
 ## ✨ Features: Core Capabilities
 
-1. **Account and Workload Security Checks**:
-   - Validates IAM configurations, S3 bucket policies, VPC security groups, and CloudTrail settings.
-2. **Report Generation**:
-   - Generates **multi-language HTML reports** (English, Korean, Japanese).
-3. **Actionable Insights**:
-   - Provides remediation steps for failed checks, mapped to AWS documentation.
-4. **Flexible Deployment**:
-   - Usable as a Python library (pip), containerized application (Docker), or AWS Lambda function.
-5. **Read-Only Permissions**:
-   - Ensures compliance with AWS's **least privilege principle** for non-intrusive diagnostics.
+1. **🚀 Enterprise CLI Integration**:
+   - Seamlessly integrated with `runbooks security` commands for professional workflows
+   - Rich console output with progress indicators and beautiful terminal formatting
+   - Unified CLI interface with other CloudOps tools (CFAT, inventory, organizations)
+
+2. **🌍 Multilingual Reporting**:
+   - Generate reports in **4 languages**: English, Korean, Japanese, Vietnamese
+   - Localized error messages and remediation guidance
+   - Cultural context for international DevOps teams
+
+3. **⚡ Performance & Scalability**:
+   - Parallel execution with configurable worker pools for faster assessments
+   - Modern dependency management with UV (Rust-based package manager)
+   - Optimized AWS API calls to minimize execution time
+
+4. **📊 Comprehensive Security Coverage**:
+   - **15+ critical security checks** covering account, IAM, infrastructure, and operational security
+   - Validates IAM configurations, S3 bucket policies, VPC security groups, and CloudTrail settings
+   - Aligned with AWS Security Best Practices and Well-Architected Framework
+
+5. **🔧 Multiple Output Formats**:
+   - **HTML reports** with interactive elements and remediation links
+   - **JSON output** for programmatic processing and CI/CD integration
+   - **Console output** for immediate feedback and debugging
+
+6. **🛡️ Enterprise Security Features**:
+   - Support for multiple AWS authentication methods (IAM roles, SSO, CloudShell)
+   - Read-only permissions ensuring compliance with **least privilege principle**
+   - Audit trail and logging for compliance requirements
+
+7. **🔄 CI/CD Integration Ready**:
+   - Designed for automated security scanning in pipelines
+   - JSON output format for integration with security dashboards
+   - Exit codes and structured logging for automation scripts
 
 ---
 
@@ -30,12 +63,14 @@ This modular structure ensures maintainability and supports seamless integration
 
 ```plaintext
 src/runbooks/
-├── security-baseline/
+├── security/                       # Integrated security module
 │   ├── checklist/                  # Security check modules
 │   │   ├── iam_password_policy.py  # Checks IAM password policy
 │   │   ├── bucket_public_access.py # Validates S3 bucket policies
+│   │   ├── root_mfa.py            # Root account MFA validation
+│   │   ├── cloudtrail_enabled.py  # CloudTrail configuration checks
 │   │   └── ...                     # More checks for IAM, S3, CloudTrail, etc.
-│   ├── lib/                        # Core utilities and constants
+│   ├── utils/                      # Core utilities and constants
 │   │   ├── common.py               # Shared helper functions
 │   │   ├── enums.py                # Enumerations for reporting
 │   │   ├── language.py             # Multi-language support
@@ -43,10 +78,14 @@ src/runbooks/
 │   ├── config.json                 # Configurable parameters for checks
 │   ├── permission.json             # IAM policy for execution
 │   ├── report_generator.py         # HTML report generator
-│   ├── run_script.py               # Main execution script
-│   └── report_template_en.html    # Report templates
-├── utils/
-│   └── logger.py                   # Logging utilities
+│   ├── security_baseline_tester.py # Core assessment engine
+│   ├── run_script.py               # Legacy script support
+│   ├── __init__.py                 # Module exports and API
+│   └── report_template_*.html     # Multilingual report templates
+├── cfat/                           # Cloud Foundations Assessment Tool
+├── inventory/                      # Multi-account resource discovery
+├── organizations/                  # AWS Organizations management
+└── main.py                         # Central CLI entry point
 ```
 
 ---
@@ -54,59 +93,96 @@ src/runbooks/
 
 ## 🚀 Deployment and Usage
 
-The tool offers multiple deployment options tailored for different use cases, such as local testing, CI/CD pipelines, and cloud-native executions.
+The security baseline assessment is fully integrated into the CloudOps Runbooks CLI, providing enterprise-grade security assessment capabilities with a simple, intuitive interface.
 
-> TBD: [Watch Video Guide](https://youtu.be/)
+> **⚡ Quick Start**: `pip install runbooks && runbooks security assess`
 
-### **Option 1: Run Locally with Python**
+### **Option 1: Install via PyPI (Recommended)**
 
-1. **Clone the Repository**:
+1. **Install the Package**:
+   ```bash
+   pip install runbooks
+   ```
+
+2. **Run Security Assessment**:
    ```bash
-   git clone https://github.com/nnthanh101/runbooks.git
-    ```
-
-2. Prerequisites: $ `task -d ~ install`
-    ```
-    echo "Verify the development environment: Python Virtual Environment ..."
-    task -d ~ check-tools
-    task -d ~ check-aws
-    echo "Install Dependencies using uv ..."
-    task -d ~ install
-    ```
-
-2. **Run the Script**:
+   # Basic security assessment
+   runbooks security assess
+   
+   # Assessment with specific AWS profile and language
+   runbooks security assess --profile production --language EN
+   
+   # Generate Korean language report
+   runbooks security assess --language KR --output ./security-reports
+   ```
+
+3. **List Available Security Checks**:
    ```bash
-   python run_script.py --profile PROFILE_NAME --language EN
+   runbooks security list-checks
    ```
 
 ---
 
-### **Option 2: Run with Docker**
+### **Option 2: Development Installation**
+
+1. **Clone the Repository**:
+   ```bash
+   git clone https://github.com/1xOps/CloudOps-Runbooks.git
+   cd CloudOps-Runbooks
+   ```
 
-1. **Build the Docker Image**:
+2. **Install Dependencies using UV** (Rust-based package manager):
    ```bash
-   docker build -t security-baseline-tester .
+   # Install UV if not already installed
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   
+   # Install dependencies and activate environment
+   uv sync --all-extras
    ```
 
-2. **Run the Container**:
+3. **Run Security Assessment**:
    ```bash
-   docker run --rm -it -v ~/.aws:/root/.aws:ro security-baseline-tester --profile PROFILE_NAME --language EN
+   uv run python -m runbooks security assess --profile PROFILE_NAME --language EN
    ```
 
 ---
 
-### **Option 3: AWS Lambda Deployment**
+### **Option 3: Using Task Automation**
+
+1. **Prerequisites Check**:
+   ```bash
+   task -d ~ check-tools
+   task -d ~ check-aws
+   ```
 
-1. **Prepare the Lambda Function**:
-   - Package the `security-baseline` directory into a ZIP file.
-   - Ensure dependencies are included by using tools like **pipenv** or **venv**.
+2. **Install and Run**:
+   ```bash
+   task install
+   task security.assess
+   ```
 
-2. **Deploy to AWS Lambda**:
-   - Create a Lambda function in the AWS Management Console or using AWS CLI.
-   - Attach the `permission.json` IAM policy to the function's execution role.
+---
 
-3. **Invoke the Function**:
-   - Use AWS CLI or a scheduled event trigger (e.g., CloudWatch Events).
+### **CLI Command Reference**
+
+```bash
+# Main security commands
+runbooks security --help                    # Show security help
+runbooks security assess                    # Run comprehensive assessment
+runbooks security assess --profile prod     # Use specific AWS profile  
+runbooks security assess --language KR      # Generate Korean report
+runbooks security assess --output /reports  # Custom output directory
+
+# Individual security checks
+runbooks security check root_mfa            # Check root MFA
+runbooks security check iam_password_policy # Check IAM password policy
+runbooks security list-checks               # List all available checks
+
+# Advanced usage
+runbooks security assess --format html      # HTML report (default)
+runbooks security assess --format json      # JSON output
+runbooks security assess --format console   # Console output only
+```
 
 ---
 
@@ -255,23 +331,49 @@ Let’s work together to make cloud security accessible, effective, and scalable
 
 ---
 
-### **Run the Script**
+### **Quick Start Examples**
 
-1. **Run the Script**:
+1. **Basic Security Assessment**:
    ```bash
-   python3 run_script.py
+   runbooks security assess
    ```
 
-2. **Use Profile or Language Options** *(Optional)*:
-   - If you configured AWS CLI with a specific profile, run:
-     ```bash
-     python3 run_script.py --profile PROFILE_NAME --language EN
-     ```
+2. **Assessment with Custom Profile and Language**:
+   ```bash
+   runbooks security assess --profile production --language EN
+   ```
    - Supported languages: **English (EN)**, **Korean (KR)**, **Japanese (JP)**, **Vietnamese (VN)**.
 
-3. **View Results**:
-   - Upon completion, an HTML report will be generated in the `results/` directory.
-   - If running on AWS CloudShell, download the report locally. [How to download files from AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/getting-started.html#download-file).
+3. **Generate Reports in Different Languages**:
+   ```bash
+   # English report
+   runbooks security assess --language EN --output ./reports/english
+   
+   # Korean report
+   runbooks security assess --language KR --output ./reports/korean
+   
+   # Japanese report  
+   runbooks security assess --language JP --output ./reports/japanese
+   
+   # Vietnamese report
+   runbooks security assess --language VN --output ./reports/vietnamese
+   ```
+
+4. **View Results**:
+   - Upon completion, an HTML report will be generated in the specified output directory (default: `./results/`)
+   - The CLI provides rich console output with immediate feedback on security findings
+   - Reports include actionable remediation steps with links to AWS documentation
+
+5. **List Available Security Checks**:
+   ```bash
+   runbooks security list-checks
+   ```
+
+6. **Run Individual Security Checks** *(Coming Soon)*:
+   ```bash
+   runbooks security check root_mfa
+   runbooks security check iam_password_policy
+   ```
 
 > ![Sample Report](./images/report_sample_en.png)
 
@@ -306,19 +408,40 @@ To scan additional AWS accounts in the same organization, you must:
 
 ---
 
-### **4. Can I use this script without an IAM Access Key?**
+### **4. Can I use this tool without an IAM Access Key?**
+
+Yes, you can run the security assessment without an IAM Access Key by leveraging IAM roles.
+The integrated `runbooks security` CLI fully supports IAM roles and various AWS authentication methods.
 
-Yes, you can run the script without an IAM Access Key by leveraging IAM roles.
-Starting from the **01/Aug/2023**, you can configure and use **IAM Roles** instead of access keys.
+**Supported Authentication Methods**:
+1. **IAM Roles** (Recommended): Configure and use IAM roles instead of access keys
+2. **AWS SSO**: Use AWS Single Sign-On for centralized authentication
+3. **Environment Variables**: Set AWS credentials via environment variables
+4. **Instance Profiles**: Automatically use instance profiles when running on EC2
+5. **AWS CloudShell**: Run directly in AWS CloudShell without any setup
 
-Follow these steps:
-1. Refer to [Overview of using IAM roles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-role-overview) to configure a role profile in the AWS CLI.
-2. Execute the script with the `--profile` option as shown below:
+**Setup Examples**:
+
+**Using IAM Roles**:
+1. Configure a role profile in AWS CLI: [IAM roles guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-role-overview)
+2. Run the assessment:
+   ```bash
+   runbooks security assess --profile ROLE_PROFILE_NAME --language EN
+   ```
+
+**Using AWS SSO**:
+1. Configure SSO profile: `aws configure sso`
+2. Run the assessment:
+   ```bash
+   runbooks security assess --profile sso-profile --language EN
+   ```
 
+**Using AWS CloudShell**:
 ```bash
-python3 run_script.py --profile PROFILE_NAME --language EN
+pip install runbooks
+runbooks security assess --language EN
 ```
 
-This approach enhances security by reducing the dependency on long-term access keys.
+This approach enhances security by reducing the dependency on long-term access keys and provides enterprise-grade authentication options.
 
 ---

runbooks/security/__init__.py

@@ -0,0 +1,70 @@
+"""
+AWS Security Baseline Testing Module.
+
+This module provides comprehensive AWS security baseline testing capabilities
+with multilingual reporting and enterprise-grade assessment features.
+
+The security module evaluates AWS accounts against security best practices
+and generates detailed HTML reports with findings and remediation guidance.
+
+Features:
+    - Comprehensive security checklist validation
+    - Multilingual report generation (EN, JP, KR, VN)
+    - Parallel execution for performance
+    - Enterprise-ready HTML reporting
+    - CLI integration with runbooks
+    - AWS Organizations and multi-account support
+
+Example:
+    ```python
+    from runbooks.security import SecurityBaselineTester
+
+    # Initialize security tester
+    tester = SecurityBaselineTester(
+        profile="prod",
+        lang_code="EN",
+        output_dir="./security-reports"
+    )
+
+    # Run security assessment
+    tester.run()
+    ```
+
+CLI Usage:
+    ```bash
+    # Run security assessment
+    runbooks security assess --profile prod --language EN
+
+    # Generate Korean language report
+    runbooks security assess --language KR --output /reports
+
+    # Run specific security checks
+    runbooks security check root-mfa --profile production
+    ```
+
+Author: CloudOps Runbooks Team
+Version: 1.1.0
+"""
+
+from .report_generator import ReportGenerator, generate_html_report
+from .run_script import main as run_security_script
+from .run_script import parse_arguments
+from .security_baseline_tester import SecurityBaselineTester
+
+# Version info
+__version__ = "0.7.5"
+__author__ = "CloudOps Runbooks Team"
+
+# Public API
+__all__ = [
+    # Core functionality
+    "SecurityBaselineTester",
+    "ReportGenerator",
+    "generate_html_report",
+    # CLI functions
+    "run_security_script",
+    "parse_arguments",
+    # Metadata
+    "__version__",
+    "__author__",
+]

runbooks/{security_baseline → security}/security_baseline_tester.py

@@ -9,8 +9,10 @@ from pathlib import Path
 import boto3
 import botocore
 
-from . import report_generator
-from .checklist import *  # noqa: F403
+from . import (
+    checklist,  # noqa: F403
+    report_generator,
+)
 from .utils import common, language, level_const
 
 # from .utils.language import get_translator
@@ -108,7 +110,7 @@ class SecurityBaselineTester:
 
     def _run_check(self, check_name, credential_report):
         # check_module = __import__(f"checklist.{check_name}", fromlist=[check_name])
-        check_module = importlib.import_module(f"runbooks.security_baseline.checklist.{check_name}")
+        check_module = importlib.import_module(f"runbooks.security.checklist.{check_name}")
         check_method = getattr(check_module, self.config["checks"][check_name])
         translator = language.get_translator(check_name, self.language)