runbooks 0.7.0__py3-none-any.whl → 0.7.6__py3-none-any.whl

runbooks/aws/ec2_unused_eips.py

@@ -1,196 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-Find and Report Unused Elastic IPs (EIPs) via AWS SES.
-
-Author: nnthanh101@gmail.com
-Date: 2025-01-07
-Version: 2.0.0
-
-Description:
-    - Identifies unused Elastic IPs in AWS.
-    - Sends details via email using AWS Simple Email Service (SES).
-
-Requirements:
-    - IAM Role Permissions:
-        * ec2:DescribeAddresses
-        * ses:SendEmail
-    - Environment Variables:
-        * SOURCE_EMAIL: Sender email address verified in SES.
-        * DEST_EMAIL: Recipient email address.
-"""
-
-import json
-import logging
-import os
-from typing import Dict, List
-
-import boto3
-from botocore.exceptions import BotoCoreError, ClientError
-
-from runbooks.utils.logger import configure_logger
-
-## ✅ Configure Logger
-logger = configure_logger(__name__)
-
-
-# ==============================
-# AWS CLIENT INITIALIZATION
-# ==============================
-def get_boto3_clients():
-    """
-    Initializes AWS clients for EC2 and SES.
-
-    Returns:
-        Tuple[boto3.client, boto3.client]: EC2 and SES clients.
-    """
-    ec2_client = boto3.client("ec2")
-    ses_client = boto3.client("ses")
-    return ec2_client, ses_client
-
-
-# ==============================
-# CONFIGURATION VARIABLES
-# ==============================
-def load_environment_variables():
-    """
-    Loads and validates environment variables required for execution.
-
-    Returns:
-        Tuple[str, str]: Source and destination email addresses.
-    """
-    source_email = os.getenv("SOURCE_EMAIL")
-    dest_email = os.getenv("DEST_EMAIL")
-
-    if not source_email or not dest_email:
-        raise ValueError("Environment variables SOURCE_EMAIL and DEST_EMAIL must be set.")
-
-    return source_email, dest_email
-
-
-# ==============================
-# EIP UTILITIES
-# ==============================
-def get_unused_eips(ec2_client) -> List[Dict[str, str]]:
-    """
-    Fetches unused Elastic IPs (EIPs).
-
-    Args:
-        ec2_client (boto3.client): EC2 client.
-
-    Returns:
-        List[Dict[str, str]]: List of unused EIPs with details.
-    """
-    try:
-        response = ec2_client.describe_addresses()
-        unused_eips = []
-
-        for address in response["Addresses"]:
-            if "InstanceId" not in address:  ## Not associated with an instance
-                unused_eips.append(
-                    {
-                        "PublicIp": address["PublicIp"],
-                        "AllocationId": address["AllocationId"],
-                        "Domain": address.get("Domain", "N/A"),  ## VPC or standard
-                    }
-                )
-
-        logger.info(f"Found {len(unused_eips)} unused EIPs.")
-        return unused_eips
-
-    except ClientError as e:
-        logger.error(f"Failed to describe addresses: {e.response['Error']['Code']} - {e}")
-        raise
-    except BotoCoreError as e:
-        logger.error(f"BotoCore error occurred: {e}")
-        raise
-
-
-# ==============================
-# EMAIL UTILITIES
-# ==============================
-def format_eip_report(eips: List[Dict[str, str]]) -> str:
-    """
-    Formats the EIPs data as a markdown table for email reporting.
-
-    Args:
-        eips (List[Dict[str, str]]): List of unused EIPs.
-
-    Returns:
-        str: Formatted markdown table.
-    """
-    if not eips:
-        return "No unused EIPs found."
-
-    ## Table Header
-    table = "| Public IP | Allocation ID | Domain |\n|-----------|----------------|--------|\n"
-
-    ## Table Rows
-    for eip in eips:
-        table += f"| {eip['PublicIp']} | {eip['AllocationId']} | {eip['Domain']} |\n"
-
-    return table
-
-
-def send_email_report(ses_client, source_email: str, dest_email: str, eips: List[Dict[str, str]]) -> None:
-    """
-    Sends an email report via AWS SES.
-
-    Args:
-        ses_client (boto3.client): SES client.
-        source_email (str): Sender email address.
-        dest_email (str): Recipient email address.
-        eips (List[Dict[str, str]]): List of unused EIPs.
-    """
-    try:
-        subject = "AWS Report: Unused Elastic IPs (EIPs)"
-        body = format_eip_report(eips)
-
-        logger.info(f"Sending email from {source_email} to {dest_email}...")
-        ses_client.send_email(
-            Source=source_email,
-            Destination={"ToAddresses": [dest_email]},
-            Message={
-                "Subject": {"Data": subject, "Charset": "utf-8"},
-                "Body": {"Text": {"Data": body, "Charset": "utf-8"}},
-            },
-        )
-        logger.info("Email sent successfully.")
-
-    except ClientError as e:
-        logger.error(f"Failed to send email: {e.response['Error']['Code']} - {e}")
-        raise
-    except BotoCoreError as e:
-        logger.error(f"BotoCore error occurred: {e}")
-        raise
-
-
-# ==============================
-# MAIN HANDLER
-# ==============================
-def lambda_handler(event, context):
-    """
-    AWS Lambda handler for reporting unused Elastic IPs.
-
-    Args:
-        event (dict): AWS event data.
-        context: AWS Lambda context.
-    """
-    try:
-        ## ✅ Load configurations
-        source_email, dest_email = load_environment_variables()
-
-        ## ✅ Initialize AWS clients
-        ec2_client, ses_client = get_boto3_clients()
-
-        ## ✅ Fetch unused EIPs
-        unused_eips = get_unused_eips(ec2_client)
-
-        ## ✅ Send email report using SES
-        send_email_report(ses_client, source_email, dest_email, unused_eips)
-
-        return {"statusCode": 200, "body": "Report sent successfully."}
-
-    except Exception as e:
-        logger.error(f"Error: {e}")
-        return {"statusCode": 500, "body": str(e)}

runbooks/aws/ec2_unused_volumes.py

@@ -1,188 +0,0 @@
-#!/usr/bin/env python3
-"""
-AWS EC2 Unused Volume Checker with SNS Notification.
-
-Finds unattached EBS volumes and sends the details via SNS notification.
-
-Author: nnthanh101@gmail.com
-Date: 2025-01-08
-Version: 1.0.0
-"""
-
-import json
-import logging
-import os
-import sys
-from typing import Dict, List
-
-import boto3
-from botocore.exceptions import BotoCoreError, ClientError
-
-from runbooks.utils.logger import configure_logger  # Reusable logger utility
-
-## ✅ Configure Logger
-logger = configure_logger(__name__)
-
-# ==============================
-# CONFIGURATION VARIABLES
-# ==============================
-AWS_REGION = os.getenv("AWS_REGION", "ap-southeast-2")
-SNS_TOPIC_ARN = os.getenv("SNS_TOPIC_ARN", "arn:aws:sns:ap-southeast-2:999999999999:1cloudops")
-
-# ==============================
-# AWS CLIENT INITIALIZATION
-# ==============================
-ec2_client = boto3.client("ec2", region_name=AWS_REGION)
-sns_client = boto3.client("sns", region_name=AWS_REGION)
-
-
-# ==============================
-# VALIDATION UTILITIES
-# ==============================
-def validate_sns_arn(arn: str) -> None:
-    """
-    Validates the format of the SNS Topic ARN.
-
-    Args:
-        arn (str): SNS Topic ARN.
-
-    Raises:
-        ValueError: If the ARN format is invalid.
-    """
-    if not arn.startswith("arn:aws:sns:"):
-        raise ValueError(f"Invalid SNS Topic ARN: {arn}")
-    logger.info(f"✅ Valid SNS ARN: {arn}")
-
-
-# ==============================
-# CORE FUNCTION: FIND UNUSED VOLUMES
-# ==============================
-def find_unused_volumes() -> List[Dict[str, str]]:
-    """
-    Identifies unused (unattached) EBS volumes in the AWS account.
-
-    Returns:
-        List[Dict[str, str]]: List of unused volumes with details.
-    """
-    try:
-        ## ✅ Retrieve all volumes
-        logger.info("🔍 Fetching all EBS volumes...")
-        response = ec2_client.describe_volumes()
-
-        ## ✅ Initialize Unused Volumes List
-        unused_volumes = []
-
-        ## ✅ Enhanced Loop with Debug Logs
-        for vol in response["Volumes"]:
-            if len(vol.get("Attachments", [])) == 0:  ## Unattached volumes
-                ## Log detailed info for debugging
-                logger.debug(f"Unattached Volume: {json.dumps(vol, default=str)}")
-
-                ## Append Volume Details
-                unused_volumes.append(
-                    {
-                        "VolumeId": vol["VolumeId"],
-                        "Size": vol["Size"],
-                        "State": vol["State"],
-                        "Encrypted": vol.get("Encrypted", False),
-                        "VolumeType": vol.get("VolumeType", "unknown"),
-                        "CreateTime": str(vol["CreateTime"]),
-                    }
-                )
-
-        logger.info(f"✅ Found {len(unused_volumes)} unused volumes.")
-        return unused_volumes
-
-    except ClientError as e:
-        logger.error(f"❌ AWS Client Error: {e}")
-        raise
-
-    except Exception as e:
-        logger.error(f"❌ Unexpected error: {e}")
-        raise
-
-
-# ==============================
-# NOTIFICATION FUNCTION: SEND EMAIL
-# ==============================
-def send_sns_notification(unused_volumes: List[Dict[str, str]]) -> None:
-    """
-    Sends unused EBS volume details via SNS notification.
-
-    Args:
-        unused_volumes (List[Dict[str, str]]): List of unused volumes.
-
-    Raises:
-        Exception: If SNS publish fails.
-    """
-    try:
-        ## ✅ Prepare Email Body (Markdown for Readability)
-        email_body = "### Unused EBS Volumes Report 📊\n\n"
-        email_body += "| VolumeId | Size (GiB) | State | Encrypted | VolumeType | CreateTime |\n"
-        email_body += "|----------|------------|-------|-----------|------------|------------|\n"
-        for vol in unused_volumes:
-            email_body += f"| {vol['VolumeId']} | {vol['Size']} | {vol['State']} | {vol['Encrypted']} | {vol['VolumeType']} | {vol['CreateTime']} |\n"
-
-        ## ✅ Publish to SNS
-        logger.info(f"Sending notification to SNS topic: {SNS_TOPIC_ARN}...")
-        logger.info(f"📤 Sending SNS notification to SNS topic: {SNS_TOPIC_ARN}")
-        sns_client.publish(
-            TopicArn=SNS_TOPIC_ARN,
-            Subject="Unused EBS Volumes Report",
-            Message=email_body,
-        )
-        logger.info("✅ SNS notification sent successfully.")
-
-    except ClientError as e:
-        logger.error(f"❌ SNS Client Error: {e}")
-        raise
-
-    except Exception as e:
-        logger.error(f"❌ Unexpected error while sending SNS notification: {e}")
-        raise
-
-
-# ==============================
-# MAIN FUNCTION
-# ==============================
-def main() -> None:
-    """
-    Main function to find unused volumes and send notifications.
-    """
-    try:
-        ## ✅ Validate Inputs/Configuration
-        validate_sns_arn(SNS_TOPIC_ARN)
-
-        ## ✅ Find Unused Volumes
-        unused_volumes = find_unused_volumes()
-
-        if unused_volumes:
-            ## ✅ Send SNS Notification if unused volumes exist
-            send_sns_notification(unused_volumes)
-        else:
-            logger.info("⚠️ No unused volumes found. Exiting without notification.")
-
-    except Exception as e:
-        logger.error(f"❌ Fatal Error: {e}")
-        sys.exit(1)
-
-
-# ==============================
-# LAMBDA HANDLER
-# ==============================
-def lambda_handler(event, context):
-    """
-    AWS Lambda Handler for unused EBS volume detection and notification.
-
-    Args:
-        event (dict): AWS Lambda event.
-        context: AWS Lambda context.
-    """
-    main()  # Reuse the main function for Lambda
-
-
-# ==============================
-# ENTRY POINT
-# ==============================
-if __name__ == "__main__":
-    main()

runbooks/aws/s3_create_bucket.py

@@ -1,142 +0,0 @@
-#!/usr/bin/env python3
-"""
-AWS S3 Bucket Creator Script.
-
-Author: nnthanh101@gmail.com
-Date: 2025-01-09
-Version: 1.0.0
-"""
-
-import os
-import sys
-from typing import Optional
-
-import boto3
-from botocore.exceptions import BotoCoreError, ClientError
-
-from runbooks.utils.logger import configure_logger  # # Import reusable logger
-
-## Initialize Logger
-logger = configure_logger("list_s3_buckets")
-
-# ==============================
-# CONFIGURATION VARIABLES
-# ==============================
-DEFAULT_BUCKET_NAME = os.getenv("S3_BUCKET_NAME", "1cloudops")  # Default bucket name
-DEFAULT_REGION = os.getenv("AWS_REGION", "ap-southeast-2")  # Default AWS region
-
-
-# ==============================
-# VALIDATION UTILITIES
-# ==============================
-def validate_bucket_name(bucket_name: str) -> None:
-    """
-    Validates an S3 bucket name based on AWS naming rules.
-
-    Args:
-        bucket_name (str): The bucket name to validate.
-
-    Raises:
-        ValueError: If the bucket name is invalid.
-    """
-    import re
-
-    ## ✅ AWS Bucket Naming Rules
-    if len(bucket_name) < 3 or len(bucket_name) > 63:
-        raise ValueError("Bucket name must be between 3 and 63 characters long.")
-
-    if not re.match(r"^[a-z0-9.-]+$", bucket_name):
-        raise ValueError("Bucket name can only contain lowercase letters, numbers, hyphens (-), and periods (.).")
-
-    if bucket_name.startswith(".") or bucket_name.endswith("."):
-        raise ValueError("Bucket name cannot start or end with a period (.)")
-
-    if ".." in bucket_name:
-        raise ValueError("Bucket name cannot contain consecutive periods (..).")
-
-    logger.info(f"✅ Bucket name '{bucket_name}' is valid.")
-
-
-# ==============================
-# CORE FUNCTION: CREATE BUCKET
-# ==============================
-def create_s3_bucket(bucket_name: str, region: str) -> Optional[str]:
-    """
-    Creates an S3 bucket in the specified AWS region.
-
-    Args:
-        bucket_name (str): The name of the S3 bucket to create.
-        region (str): The AWS region where the bucket will be created.
-
-    Returns:
-        Optional[str]: The location of the created bucket if successful, None otherwise.
-
-    Raises:
-        Exception: Raises error if bucket creation fails.
-    """
-    ## ✅ Initialize S3 Client
-    try:
-        s3_client = boto3.client("s3", region_name=region)
-        logger.info(f"Creating bucket '{bucket_name}' in region '{region}'...")
-
-        ## ✅ Create bucket with LocationConstraint
-        if region == "us-east-1":  ## Special case: us-east-1 doesn't require LocationConstraint
-            response = s3_client.create_bucket(
-                Bucket=bucket_name,
-                ACL="private",  ## Set access control to private
-            )
-        else:
-            response = s3_client.create_bucket(
-                Bucket=bucket_name,
-                ACL="private",
-                CreateBucketConfiguration={"LocationConstraint": region},
-            )
-
-        logger.info(f"✅ Bucket '{bucket_name}' created successfully at {response['Location']}.")
-        return response["Location"]
-
-    except ClientError as e:
-        logger.error(f"❌ AWS Client Error: {e}")
-        raise
-
-    except BotoCoreError as e:
-        logger.error(f"❌ BotoCore Error: {e}")
-        raise
-
-    except Exception as e:
-        logger.error(f"❌ Unexpected error: {e}")
-        raise
-
-
-# ==============================
-# MAIN FUNCTION
-# ==============================
-def main() -> None:
-    """
-    Main entry point for script execution.
-    """
-    try:
-        ## ✅ Parse Arguments or Use Environment Variables
-        bucket_name = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_BUCKET_NAME
-        region = sys.argv[2] if len(sys.argv) > 2 else DEFAULT_REGION
-
-        ## ✅ Validate Input
-        validate_bucket_name(bucket_name)
-
-        ## ✅ Create S3 Bucket
-        create_s3_bucket(bucket_name, region)
-
-    except ValueError as e:
-        logger.error(f"❌ Input Validation Error: {e}")
-        sys.exit(1)
-
-    except Exception as e:
-        logger.error(f"❌ Fatal Error: {e}")
-        sys.exit(1)
-
-
-# ==============================
-# ENTRY POINT
-# ==============================
-if __name__ == "__main__":
-    main()

runbooks/aws/s3_list_buckets.py

@@ -1,152 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-AWS S3 Bucket Listing Utility with logging and error handling.
-
-Author: nnthanh101@gmail.com
-Date: 2025-01-05
-Version: 1.0.0
-
-Description:
-    This script lists all S3 buckets in the AWS account using the Boto3 library.
-    It implements robust error handling, logging, and modularization for high standards.
-
-Usage:
-    python list_s3_buckets.py
-"""
-
-import json
-import os
-from typing import Dict, List
-
-import boto3
-from botocore.exceptions import ClientError, NoCredentialsError, PartialCredentialsError
-from tabulate import tabulate
-
-from runbooks.utils.logger import configure_logger
-
-## Initialize Logger
-logger = configure_logger("list_s3_buckets")
-
-
-def get_s3_client(region: str = None) -> boto3.client:
-    """
-    Initializes and returns a Boto3 S3 client with optional region support.
-
-    Args:
-        region (str, optional): AWS region. Defaults to None (uses environment or AWS config).
-
-    Returns:
-        boto3.client: Configured S3 client.
-
-    Raises:
-        NoCredentialsError: Raised if AWS credentials are missing.
-        PartialCredentialsError: Raised if AWS credentials are incomplete.
-    """
-    try:
-        ## ✅ Allow region override if specified
-        session = boto3.Session(region_name=region) if region else boto3.Session()
-        client = session.client("s3")
-        logger.info("S3 client initialized successfully.")
-        return client
-    except (NoCredentialsError, PartialCredentialsError) as e:
-        # logger.error("Please configure them using AWS CLI or environment variables.")
-        logger.error(f"AWS Credentials Error: {str(e)}")
-        raise
-    except Exception as e:
-        logger.error(f"Unexpected error: {str(e)}")
-        raise
-
-
-def list_s3_buckets(client: boto3.client) -> List[Dict[str, str]]:
-    """
-    Lists all S3 buckets in the AWS account.
-
-    Args:
-        client (boto3.client): Pre-configured S3 client.
-
-    Returns:
-        List[Dict[str, str]]: List of bucket details including name and creation date.
-
-    Raises:
-        ClientError: For API errors returned by AWS.
-    """
-    try:
-        ## ✅ Call AWS API to list buckets
-        response = client.list_buckets()
-
-        ## ✅ Extract bucket names and creation dates
-        # bucket_list = [{"Name": bucket['Name'], "CreationDate": str(bucket['CreationDate'])} for bucket in buckets]
-        bucket_list = [
-            {
-                "Name": bucket["Name"],
-                "CreationDate": bucket["CreationDate"].strftime("%Y-%m-%d %H:%M:%S"),
-                "Owner": {
-                    "DisplayName": response["Owner"].get("DisplayName", "N/A"),
-                    # "ID": response['Owner'].get('ID', 'N/A')
-                },
-            }
-            for bucket in response.get("Buckets", [])
-        ]
-
-        ## ✅ Log the number of buckets found
-        if not bucket_list:
-            logger.warning("No buckets found.")
-        else:
-            logger.info(f"Found {len(bucket_list)} S3 bucket(s).")
-
-        return bucket_list
-    except ClientError as e:
-        logger.error(f"Failed to list buckets: {e.response['Error']['Message']}")
-        raise
-    except Exception as e:
-        logger.error(f"Unexpected error: {str(e)}")
-        raise
-
-
-def display_buckets(buckets: List[Dict[str, str]]) -> None:
-    """
-    Displays bucket details in JSON format for readability.
-
-    Args:
-        buckets (List[Dict[str, str]]): List of bucket details.
-    """
-
-    # print(json.dumps(buckets, indent=4)) if buckets else print("No buckets found.")
-    ## ✅ Prepare Table Headers and Rows
-    headers = ["Name", "Creation Date", "Owner Display Name", "Owner ID"]
-    rows = [
-        # [bucket["Name"], bucket["CreationDate"], bucket["Owner"]["DisplayName"], bucket["Owner"]["ID"]]
-        [bucket["Name"], bucket["CreationDate"], bucket["Owner"]["DisplayName"]]
-        for bucket in buckets
-    ]
-
-    ## ✅ Render Markdown Table
-    print("### AWS S3 Buckets\n")
-    ## Creating & printing the Markdown Table
-    table = tabulate(rows, headers=headers, tablefmt="github", missingval="N/A")
-    print(table)
-
-
-## ==============================
-## MAIN FUNCTION
-## ==============================
-def main() -> None:
-    """
-    Main entry point for listing S3 buckets.
-    """
-    try:
-        ## ✅ Load AWS region dynamically (fallback to default)
-        region = os.getenv("AWS_REGION", "us-east-1")
-        ## ✅ Initialize S3 client
-        client = get_s3_client(region)
-        ## ✅ Retrieve bucket list
-        buckets = list_s3_buckets(client)
-        ## ✅ Display results
-        display_buckets(buckets)
-    except Exception as e:
-        logger.error(f"Program terminated with error: {str(e)}")
-
-
-if __name__ == "__main__":
-    main()