runbooks 0.1.7__py3-none-any.whl → 0.1.8__py3-none-any.whl

runbooks/aws/s3_list_buckets.py

@@ -0,0 +1,152 @@
+#!/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()

runbooks/aws/s3_list_objects.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+
+"""
+List all objects inside a specified S3 bucket with logging and error handling.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-06
+Version: 1.0.0
+
+Usage:
+    python list_s3_objects.py <bucket_name>
+"""
+
+import argparse
+import sys
+from typing import Dict, List, Optional
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError, NoCredentialsError
+from tabulate import tabulate
+
+from runbooks.utils.logger import configure_logger
+
+## ✅ Configure Logger
+logger = configure_logger(__name__)
+
+
+## ==============================
+## AWS S3 UTILITIES
+## ==============================
+def s3_list_objects(
+    bucket_name: str,
+    prefix: Optional[str] = None,
+    max_keys: int = 1000,
+) -> List[Dict[str, str]]:
+    """
+    List objects in the specified S3 bucket.
+
+    Args:
+        bucket_name (str): The name of the S3 bucket.
+        prefix (Optional[str]): Filter objects by prefix (default: None).
+        max_keys (int): Maximum number of keys to retrieve per request (default: 1000).
+
+    Returns:
+        List[Dict[str, str]]: List of object details, including key, size, and last modified date.
+
+    Raises:
+        NoCredentialsError: If AWS credentials are missing.
+        ClientError: If there is an issue accessing the bucket.
+    """
+    try:
+        logger.info(f"Initializing S3 client for bucket: {bucket_name}")
+        client = boto3.client("s3")
+
+        ## ✅ Prepare Parameters
+        params = {"Bucket": bucket_name, "MaxKeys": max_keys}
+        if prefix:
+            params["Prefix"] = prefix
+
+        ## ✅ Fetch Objects with Pagination Support
+        paginator = client.get_paginator("list_objects_v2")
+        page_iterator = paginator.paginate(**params)
+
+        object_list = []
+        for page in page_iterator:
+            if "Contents" in page:  # Check if there are objects
+                for obj in page["Contents"]:
+                    object_list.append(
+                        {
+                            "Key": obj["Key"],
+                            "Size (KB)": f"{obj['Size'] / 1024:.2f}",  # Convert bytes to KB
+                            "LastModified": obj["LastModified"].strftime("%Y-%m-%d %H:%M:%S"),
+                        }
+                    )
+
+        ## ✅ Log Results
+        logger.info(f"Found {len(object_list)} object(s) in bucket '{bucket_name}'.")
+        return object_list
+
+    except NoCredentialsError:
+        logger.error("AWS credentials not found. Ensure ~/.aws/credentials is configured.")
+        raise
+
+    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
+
+
+## ==============================
+## DISPLAY UTILITIES
+## ==============================
+def display_objects(objects: List[Dict[str, str]], bucket_name: str) -> None:
+    """
+    Displays S3 object details in Markdown table format.
+
+    Args:
+        objects (List[Dict[str, str]]): List of S3 object details.
+        bucket_name (str): Name of the S3 bucket.
+    """
+    if not objects:
+        print(f"No objects found in bucket: {bucket_name}")
+        return
+
+    ## ✅ Prepare Table Headers and Rows
+    headers = ["Key", "Size (KB)", "Last Modified"]
+    rows = [[obj["Key"], obj["Size (KB)"], obj["LastModified"]] for obj in objects]
+
+    ## ✅ Render Markdown Table
+    print(f"### S3 Objects in Bucket: `{bucket_name}`\n")
+    print(tabulate(rows, headers=headers, tablefmt="github"))
+
+
+## ==============================
+## MAIN FUNCTION
+## ==============================
+def main():
+    """
+    Main entry point for listing S3 objects.
+    """
+    ## ✅ Parse Command-Line Arguments
+    parser = argparse.ArgumentParser(description="List objects in an AWS S3 bucket.")
+    parser.add_argument("--bucket", required=True, help="The name of the S3 bucket.")
+    parser.add_argument("--prefix", default=None, help="Filter objects by prefix.")
+    parser.add_argument("--max-keys", type=int, default=1000, help="Max number of keys to fetch (default: 1000).")
+
+    args = parser.parse_args()
+
+    try:
+        ## ✅ Fetch and Display S3 Objects
+        objects = s3_list_objects(
+            bucket_name=args.bucket,
+            prefix=args.prefix,
+            max_keys=args.max_keys,
+        )
+        display_objects(objects, args.bucket)
+
+    except Exception as e:
+        logger.error(f"Program terminated with error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

runbooks/aws/s3_object_operations.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+
+"""
+S3 Object Operations: Upload and Delete Objects in Amazon S3.
+
+This script provides functionality to:
+1. Upload a file to an S3 bucket.
+2. Delete a file from an S3 bucket.
+
+Designed for usage in Python (pip), Docker, and AWS Lambda environments.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-08
+Version: 1.0.0
+"""
+
+import logging
+import os
+from typing import Optional
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError
+
+# ==============================
+# CONFIGURATION VARIABLES
+# ==============================
+AWS_REGION = os.getenv("AWS_REGION", "us-east-1")
+S3_BUCKET = os.getenv("S3_BUCKET", "my-default-bucket")
+S3_KEY = os.getenv("S3_KEY", "default-key.txt")
+LOCAL_FILE_PATH = os.getenv("LOCAL_FILE_PATH", "default.txt")
+ACL = os.getenv("ACL", "private")  ## Options: 'private', 'public-read', etc.
+
+# ==============================
+# LOGGING CONFIGURATION
+# ==============================
+logging.basicConfig(format="%(asctime)s - %(levelname)s - %(message)s", level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ==============================
+# AWS CLIENT INITIALIZATION
+# ==============================
+try:
+    s3_client = boto3.client("s3", region_name=AWS_REGION)
+    logger.info("✅ S3 client initialized successfully.")
+except Exception as e:
+    logger.error(f"❌ Failed to initialize S3 client: {e}")
+    raise
+
+
+# ==============================
+# UPLOAD FUNCTION
+# ==============================
+def put_object(bucket: str, key: str, file_path: str, acl: str = "private") -> None:
+    """
+    Uploads a file to an S3 bucket.
+
+    Args:
+        bucket (str): The name of the S3 bucket.
+        key (str): The object key in S3.
+        file_path (str): Local file path to be uploaded.
+        acl (str): Access control list (default: 'private').
+
+    Raises:
+        Exception: Any upload failure.
+    """
+    try:
+        # ✅ Check if the file exists locally
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"File '{file_path}' not found.")
+
+        logger.info(f"🚀 Uploading '{file_path}' to bucket '{bucket}' with key '{key}'...")
+        with open(file_path, "rb") as file_reader:
+            s3_client.put_object(ACL=acl, Body=file_reader, Bucket=bucket, Key=key)
+        logger.info(f"✅ File '{file_path}' uploaded successfully to '{bucket}/{key}'.")
+
+    except FileNotFoundError as e:
+        logger.error(f"❌ File Not Found: {e}")
+        raise
+
+    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
+
+
+# ==============================
+# DELETE FUNCTION
+# ==============================
+def delete_object(bucket: str, key: str) -> None:
+    """
+    Deletes an object from an S3 bucket.
+
+    Args:
+        bucket (str): The name of the S3 bucket.
+        key (str): The object key to delete.
+
+    Raises:
+        Exception: Any deletion failure.
+    """
+    try:
+        logger.info(f"🗑️ Deleting object '{key}' from bucket '{bucket}'...")
+        s3_client.delete_object(Bucket=bucket, Key=key)
+        logger.info(f"✅ Object '{key}' deleted successfully from '{bucket}'.")
+
+    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 (CLI/DOCKER)
+# ==============================
+def main():
+    """
+    Main entry point for CLI/Docker execution.
+    """
+    try:
+        # ✅ Upload Object
+        put_object(S3_BUCKET, S3_KEY, LOCAL_FILE_PATH, ACL)
+
+        # ✅ Delete Object (Uncomment if needed)
+        # delete_object(S3_BUCKET, S3_KEY)
+
+    except Exception as e:
+        logger.error(f"❌ Error in main: {e}")
+        raise
+
+
+# ==============================
+# AWS LAMBDA HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda handler for S3 object operations.
+
+    Args:
+        event (dict): AWS Lambda event payload with 'action', 'bucket', 'key', and 'file_path'.
+        context: AWS Lambda context object.
+
+    Returns:
+        dict: Status code and message.
+    """
+    try:
+        action = event.get("action")  # 'upload' or 'delete'
+        bucket = event.get("bucket", S3_BUCKET)
+        key = event.get("key", S3_KEY)
+        file_path = event.get("file_path", LOCAL_FILE_PATH)
+        acl = event.get("acl", ACL)
+
+        if action == "upload":
+            put_object(bucket, key, file_path, acl)
+            return {"statusCode": 200, "body": f"File '{key}' uploaded to '{bucket}'."}
+        elif action == "delete":
+            delete_object(bucket, key)
+            return {"statusCode": 200, "body": f"File '{key}' deleted from '{bucket}'."}
+        else:
+            raise ValueError("Invalid action. Supported actions: 'upload', 'delete'.")
+
+    except Exception as e:
+        logger.error(f"❌ Lambda Error: {e}")
+        return {"statusCode": 500, "body": str(e)}
+
+
+# ==============================
+# SCRIPT ENTRY POINT
+# ==============================
+if __name__ == "__main__":
+    main()

runbooks/aws/tagging_lambda_handler.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+
+"""
+AWS Lambda Function for Auto-Tagging EC2 Instances Based on S3 Configuration.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-07
+Version: 1.0.0
+
+Description:
+    - Fetches tagging configuration from an S3 bucket.
+    - Applies tags dynamically to an EC2 instance when triggered by AWS CloudTrail events.
+
+Requirements:
+    - IAM Role Permissions:
+        * s3:GetObject
+        * ec2:CreateTags
+        * sts:GetCallerIdentity
+    - Environment Variables:
+        * S3_BUCKET: Name of the S3 bucket storing tags.json
+        * S3_OBJECT_KEY: Key for the tags.json file
+"""
+
+import json
+import os
+import re
+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__)
+
+## ✅ Initialize AWS Clients
+s3 = boto3.client("s3")
+ec2 = boto3.client("ec2")
+
+# ==============================
+# CONFIGURATIONS: dafault S3 bucket and object key
+# ==============================
+BUCKET_NAME = os.getenv("S3_BUCKET", "os-auto-tagging")  ## Default S3 bucket name
+OBJECT_KEY = os.getenv("S3_OBJECT_KEY", "tags.json")  ## Default S3 object key
+LOCAL_FILE_PATH = "/tmp/tags.json"  ## Local Temp file path
+
+# ==============================
+# VALIDATION CONFIGURATIONS
+# ==============================
+REQUIRED_TAGS = ["Account Name", "Functional Area", "WBS Code", "Business Unit", "Managed by", "CostGroup", "TechOwner"]
+
+TAG_VALUE_REGEX = r"^[a-zA-Z0-9\s\-_@]+$"  ## Allowed characters for tag values
+
+
+def validate_tags(tags: List[Dict[str, str]]) -> None:
+    """
+    Validates that all required tags are present in the tag key-value list.
+
+    Args:
+        tags (List[Dict[str, str]]): List of tags to validate.
+
+    Raises:
+        ValueError: If any required tag is missing.
+    """
+    tag_keys = {tag["Key"] for tag in tags}  ## Extract tag keys
+    missing_tags = [tag for tag in REQUIRED_TAGS if tag not in tag_keys]
+
+    if missing_tags:
+        raise ValueError(f"Missing required tags: {', '.join(missing_tags)}")
+
+    ## Validate tag values
+    for tag in tags:
+        if not re.match(TAG_VALUE_REGEX, tag["Value"]):
+            raise ValueError(f"Invalid value '{tag['Value']}' for tag '{tag['Key']}'.")
+
+    logger.info("All required tags are validated and meet constraints.")
+
+
+# ==============================
+# S3 UTILITIES
+# ==============================
+def download_tags_from_s3(bucket: str, key: str, local_path: str) -> List[Dict[str, str]]:
+    """
+    Downloads the tagging configuration file from S3 and parses it.
+
+    Args:
+        bucket (str): The S3 bucket name.
+        key (str): The object key in the bucket.
+        local_path (str): The local path to store the file.
+
+    Returns:
+        List[Dict[str, str]]: List of tags.
+    """
+    try:
+        ## ✅ Download tags.json File from S3
+        logger.info(f"Downloading '{key}' from bucket '{bucket}'...")
+        s3.download_file(bucket, key, local_path)
+        logger.info(f"File downloaded successfully to {local_path}.")
+
+        ## ✅ Parse the tags.json file
+        with open(local_path, "r") as file:
+            ## Load tags as a list of dictionaries
+            tags = json.load(file)
+
+        validate_tags(tags)  ## Validate required tags
+        return tags
+
+    except FileNotFoundError:
+        logger.error("Local file not found after download.")
+        raise
+
+    except ClientError as e:
+        logger.error(f"S3 Client Error: {e}")
+        raise
+
+    except Exception as e:
+        logger.error(f"Unexpected error while downloading tags: {e}")
+        raise
+
+
+# ==============================
+# EC2 UTILITIES
+# ==============================
+def apply_tags_to_instance(instance_id: str, tags: List[Dict[str, str]]) -> None:
+    """
+    Applies tags to the specified EC2 instance.
+
+    Args:
+        instance_id (str): The ID of the EC2 instance.
+        tags (List[Dict[str, str]]): Tags to apply.
+
+    Raises:
+        Exception: Any AWS tagging errors.
+    """
+    try:
+        logger.info(f"Applying tags to EC2 instance: {instance_id}")
+        ec2.create_tags(Resources=[instance_id], Tags=tags)
+        logger.info(f"Tags successfully applied to instance {instance_id}: {tags}")
+
+    except ClientError as e:
+        logger.error(f"EC2 Client Error: {e}")
+        raise
+
+
+# ==============================
+# MAIN HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda Handler for applying tags to EC2 instances.
+
+    Args:
+        event (dict): AWS event data.
+        context: AWS Lambda context.
+    """
+    try:
+        ## ✅ Extract instance ID from the event
+        instance_id = event["detail"]["responseElements"]["instancesSet"]["items"][0]["instanceId"]
+        logger.info(f"Processing instance ID: {instance_id}")
+
+        ## ✅ Download and Parse Tags
+        tags = download_tags_from_s3(BUCKET_NAME, OBJECT_KEY, LOCAL_FILE_PATH)
+
+        ## ✅ Apply Tags to Instance
+        apply_tags_to_instance(instance_id, tags)
+
+        ## ✅ Success Response
+        return {"statusCode": 200, "body": json.dumps(f"Tags successfully applied to instance {instance_id}")}
+    except Exception as e:
+        logger.error(f"Error during tagging process: {e}")
+        return {"statusCode": 500, "body": json.dumps(f"Error: {str(e)}")}

runbooks/python101/calculator.py

@@ -0,0 +1,34 @@
+from typing import Union
+
+from runbooks.python101.config import DEFAULT_CONFIG
+from runbooks.python101.exceptions import CalculatorError
+
+
+class Calculator:
+    """Calculator class supporting arithmetic operations with configurable precision."""
+
+    def __init__(self, precision: int = DEFAULT_CONFIG["precision"]):
+        """Initialize calculator with configurable precision."""
+        self.precision = precision
+
+    def _format_result(self, result: Union[int, float]) -> Union[int, float]:
+        """Format result based on precision."""
+        return round(result, self.precision)
+
+    def add(self, x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
+        """Adds two numbers."""
+        return self._format_result(x + y)
+
+    def subtract(self, x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
+        """Subtracts second number from first."""
+        return self._format_result(x - y)
+
+    def multiply(self, x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
+        """Multiplies two numbers."""
+        return self._format_result(x * y)
+
+    def divide(self, x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
+        """Divides first number by second."""
+        if y == 0:
+            raise CalculatorError("Division by zero is not allowed.")
+        return self._format_result(x / y)

runbooks/python101/config.py

@@ -0,0 +1 @@
+DEFAULT_CONFIG = {"precision": 2, "allow_negative": True, "debug": False, "log_file": "calculator.log"}