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

runbooks/python101/exceptions.py

@@ -0,0 +1,16 @@
+class CalculatorError(Exception):
+    """Custom exception for errors in the Calculator."""
+
+    pass
+
+
+class InvalidOperationError(CalculatorError):
+    """Raised when an invalid operation is attempted."""
+
+    pass
+
+
+class InputValidationError(CalculatorError):
+    """Raised when input validation fails."""
+
+    pass

runbooks/python101/file_manager.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+
+"""
+Utilities to create a specified folder and an empty file inside it with safe error handling.
+
+Author: Python Developer
+Date: 2025-01-05
+Version: 1.0.0
+
+Usage:
+    file_manager.py <folder_name> <file_name>
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Union
+
+
+## ==============================
+## VALIDATION UTILITIES
+## ==============================
+def validate_input(value: Union[str, float, int]) -> float:
+    """
+    Validates and converts input into a float.
+
+    Args:
+        value (Union[str, float, int]): The input value to validate and convert.
+
+    Returns:
+        float: The validated and converted float value.
+
+    Raises:
+        TypeError: If input type is unsupported.
+        ValueError: If input cannot be converted to float, or fails constraints.
+    """
+
+    ## ✅ Step 1.1: Input Type Validation
+    if not isinstance(value, (str, int, float)):
+        raise TypeError(f"Invalid type '{type(value).__name__}'. Expected str, int, or float.")
+
+    ## ✅ Step 1.2: Handle Empty String
+    if isinstance(value, str) and not value.strip():
+        raise ValueError(f"Invalid input '{value}'. Input cannot be empty or whitespace-only.")
+
+    ## ✅ Step 2: Convert Input to Float
+    try:
+        result = float(value)  ## Attempt numeric conversion
+    except ValueError as e:
+        raise ValueError(f"Invalid input '{value}'. Must be a valid number.") from e
+
+    ## ✅ Step 3: Return Validated Float
+    return result
+
+
+def validate_folder_name(folder_name: str) -> None:
+    """
+    Validates folder name for OS-specific constraints.
+
+    Args:
+        folder_name (str): The folder name to validate.
+
+    Raises:
+        ValueError: If the folder name violates naming constraints.
+    """
+    if not folder_name:
+        raise ValueError("Folder name cannot be empty.")
+
+    if len(folder_name) > 255:  # Max length in most file systems
+        raise ValueError("Folder name exceeds maximum length (255 characters).")
+
+    invalid_chars = '<>:"/\\|?*'  # Reserved characters in Windows
+    if any(char in invalid_chars for char in folder_name):
+        raise ValueError(f"Folder name '{folder_name}' contains invalid characters.")
+
+    if folder_name in {"CON", "PRN", "AUX", "NUL"}:  # Reserved Windows names
+        raise ValueError(f"Folder name '{folder_name}' is a reserved keyword.")
+
+    if folder_name.startswith(" ") or folder_name.endswith(" "):
+        raise ValueError("Folder name cannot start or end with spaces.")
+
+
+def validate_file_name(file_name: str) -> None:
+    """
+    Validates file name for OS-specific constraints.
+
+    Args:
+        file_name (str): The file name to validate.
+
+    Raises:
+        ValueError: If the file name violates naming constraints.
+    """
+    if not file_name:
+        raise ValueError("File name cannot be empty.")
+
+    if len(file_name) > 255:
+        raise ValueError("File name exceeds maximum length (255 characters).")
+
+    invalid_chars = '<>:"/\\|?*'
+    if any(char in invalid_chars for char in file_name):
+        raise ValueError(f"File name '{file_name}' contains invalid characters.")
+
+    if file_name.startswith(" ") or file_name.endswith(" "):
+        raise ValueError("File name cannot start or end with spaces.")
+
+    if len(Path(file_name).suffix) == 0:  # Ensure file has an extension
+        raise ValueError("File name must include a valid extension (e.g., '.txt').")
+
+
+## ==============================
+## FILE SYSTEM UTILITIES
+## ==============================
+def create_folder_and_file(folder_name: str, file_name: str) -> None:
+    """
+    Create a folder and an empty file safely with robust error handling.
+
+    Args:
+        folder_name (str): Name of the folder to be created.
+        file_name (str): Name of the file to be created inside the folder.
+
+    Raises:
+        FileExistsError: If the folder already exists.
+        FileNotFoundError: If the folder path is invalid.
+        PermissionError: If there are insufficient permissions.
+        ValueError: If inputs are invalid.
+    """
+    ## ✅ Input Validation
+    validate_folder_name(folder_name)
+    validate_file_name(file_name)
+
+    ## ✅ Create Path Object
+    folder_path = Path(folder_name)
+    file_path = folder_path / file_name
+
+    try:
+        ## ✅ Create folder if it doesn't exist; same behavior as the POSIX `mkdir -p` command
+        folder_path.mkdir(parents=True, exist_ok=True)  ## Safe parent directory creation
+        print(f"✅ Folder '{folder_name}' created successfully.")
+
+        ## ✅ Create an empty file inside the folder
+        # os.chdir(folder_name) ## May Raise FileNotFoundError
+        # with open(file_name, 'a'):
+        #     pass
+        if file_path.exists():
+            raise FileExistsError(f"File '{file_name}' already exists in '{folder_name}'.")
+
+        file_path.touch(exist_ok=False)  ## Create an empty file; Fails safely if file exists
+        print(f"✅ File '{file_name}' created successfully inside '{folder_name}'.")
+
+    except FileExistsError as e:
+        raise FileExistsError(str(e))  # Re-raise exception without exiting
+
+    except PermissionError:
+        print("❌ Permission denied. Check your user permissions.")
+        sys.exit(1)
+
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}")
+        sys.exit(1)
+
+
+## ✅ Handle Arguments Dynamically for Terminal and Debugger Compatibility
+def parse_arguments() -> tuple[str, str]:
+    """
+    Parses and validates command-line arguments for both terminal and VSCode debugger compatibility.
+
+    Returns:
+        tuple[str, str]: A tuple containing folder_name and file_name.
+
+    Raises:
+        ValueError: If arguments are invalid or insufficient.
+    """
+    import shlex  # Safely split arguments with quotes (if present)
+
+    ## ✅ Check Arguments Length
+    if len(sys.argv) < 2:
+        raise ValueError("Provide exactly 2 arguments: <folder_name> <file_name>")
+
+    ## ✅ Handle Debugger Inputs (Single Combined Argument)
+    if len(sys.argv) == 2:
+        args = shlex.split(sys.argv[1])  # Split safely with quote handling
+    else:
+        args = sys.argv[1:]  # Use normal command-line arguments
+
+    ## ✅ Validate Number of Arguments
+    if len(args) != 2:
+        raise ValueError("❌ Invalid arguments. Provide exactly 2 arguments: <folder_name> <file_name>")
+
+    ## ✅ Extract Folder and File Names
+    folder_name, file_name = args[0], args[1]
+    return folder_name, file_name
+
+
+## ==============================
+## MAIN FUNCTION
+## ==============================
+def main() -> None:
+    """
+    Main entry point for the script.
+    """
+    try:
+        ## ✅ Handle Debugger Arguments (Optional for Debugging Tools)
+        folder_name, file_name = parse_arguments()
+
+        ## ✅ Execute Function for Folder and File Creation
+        print(f"✅ Usage: file_manager.py '{folder_name}' '{file_name}'")
+        create_folder_and_file(folder_name, file_name)
+    except ValueError as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+
+    except Exception as e:
+        print(f"❌ Unexpected Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

runbooks/python101/toolkit.py

@@ -0,0 +1,153 @@
+"""
+Toolkit Module: Implements basic arithmetic operations.
+
+This module provides functions to perform addition, subtraction,
+multiplication, and division with detailed input validation.
+
+Features:
+- Handles edge cases like NaN, Infinity, and division by zero.
+- Supports logging for better traceability.
+- Enforces type checks for input safety.
+
+Author: Python Developer
+"""
+
+from typing import Union
+
+from loguru import logger
+
+# Define a type alias for supported numeric types
+Number = Union[int, float]
+
+# Configure loguru logger to simplify logs for testing
+logger.remove()
+logger.add(lambda msg: print(msg, end=""), format="{message}", level="DEBUG")
+
+
+def _validate_inputs(a: Number, b: Number, allow_zero: bool = True) -> None:
+    """
+    Validates numeric inputs and checks edge cases.
+
+    Args:
+        a (Number): The first input value.
+        b (Number): The second input value.
+        allow_zero (bool): Whether zero is allowed as a value for `b`. Default is True.
+
+    Raises:
+        TypeError: If inputs are not integers or floats.
+        ValueError: If inputs are NaN or Infinity.
+        ZeroDivisionError: If `b` is zero and `allow_zero` is False.
+    """
+    # Type check
+    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
+        raise TypeError(f"Inputs must be numbers. Received: {type(a)} and {type(b)}")
+
+    # Edge cases: NaN or Infinity
+    for value in [a, b]:
+        if value != value or value in [float("inf"), float("-inf")]:
+            raise ValueError(f"Invalid input {value}. Must be a finite number.")
+
+    # Zero Division Check
+    if not allow_zero and b == 0:
+        raise ZeroDivisionError("division by zero")
+
+
+def add(a: Number, b: Number) -> float:
+    """
+    Adds two numbers and returns the result.
+
+    Examples:
+        >>> add(4.0, 2.0)
+        6.0
+        >>> add(4, 2)
+        6.0
+
+    Args:
+        a (Number): The first number.
+        b (Number): The second number.
+
+    Returns:
+        float: The sum of `a` and `b`.
+
+    Raises:
+        TypeError: If inputs are not numbers.
+    """
+    _validate_inputs(a, b)
+    logger.debug(f"Adding {a} + {b}")
+    return float(a + b)
+
+
+def subtract(a: Number, b: Number) -> float:
+    """
+    Subtracts the second number from the first.
+
+    Examples:
+        >>> subtract(4.0, 2.0)
+        2.0
+        >>> subtract(4, 2)
+        2.0
+
+    Args:
+        a (Number): The first number.
+        b (Number): The second number.
+
+    Returns:
+        float: The result of `a - b`.
+
+    Raises:
+        TypeError: If inputs are not numbers.
+    """
+    _validate_inputs(a, b)
+    logger.debug(f"Subtracting {a} - {b}")
+    return float(a - b)
+
+
+def multiply(a: Number, b: Number) -> float:
+    """
+    Multiplies two numbers and returns the result.
+
+    Examples:
+        >>> multiply(4.0, 2.0)
+        8.0
+        >>> multiply(4, 2)
+        8.0
+
+    Args:
+        a (Number): The first number.
+        b (Number): The second number.
+
+    Returns:
+        float: The result of `a * b`.
+
+    Raises:
+        TypeError: If inputs are not numbers.
+    """
+    _validate_inputs(a, b)
+    logger.debug(f"Multiplying {a} * {b}")
+    return float(a * b)
+
+
+def divide(a: Number, b: Number) -> float:
+    """
+    Divides the first number by the second.
+
+    Examples:
+        >>> divide(4.0, 2.0)
+        2.0
+        >>> divide(4, 2)
+        2.0
+
+    Args:
+        a (Number): The numerator.
+        b (Number): The denominator.
+
+    Returns:
+        float: The result of `a / b`.
+
+    Raises:
+        TypeError: If inputs are not numbers.
+        ZeroDivisionError: If `b` is zero.
+    """
+    _validate_inputs(a, b, allow_zero=False)
+    logger.debug(f"Dividing {a} / {b}")
+    return float(a / b)

runbooks/security_baseline/checklist/__init__.py

@@ -0,0 +1,17 @@
+__all__ = [
+    "root_mfa",
+    "root_usage",
+    "root_access_key",
+    "iam_user_mfa",
+    "iam_password_policy",
+    "direct_attached_policy",
+    "alternate_contacts",
+    "trail_enabled",
+    "multi_region_trail",
+    "account_level_bucket_public_access",
+    "bucket_public_access",
+    "cloudwatch_alarm_configuration",
+    "multi_region_instance_usage",
+    "guardduty_enabled",
+    "trusted_advisor",
+]

runbooks/security_baseline/checklist/account_level_bucket_public_access.py

@@ -0,0 +1,86 @@
+import logging
+
+import botocore.exceptions
+from utils import common
+from utils import level_const as level
+
+
+def check_account_level_bucket_public_access(session, translator) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["Policy Name", "Public Access Setting"]
+
+    sts_client = session.client("sts")
+    s3control_client = session.client("s3control")
+
+    try:
+        account_id = sts_client.get_caller_identity()["Account"]
+    except botocore.exceptions.ClientError as e:
+        logging.error(f"Failed to get caller identity: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("failed_get_identity")
+        ret.result_rows.append(["ERR", "ERR"])
+        ret.error_message = str(e)
+        return ret
+
+    try:
+        account_policy = s3control_client.get_public_access_block(AccountId=account_id)[
+            "PublicAccessBlockConfiguration"
+        ]
+    except s3control_client.exceptions.NoSuchPublicAccessBlockConfiguration:
+        ret.level = level.danger
+        ret.msg = translator.translate("no_such_public_access_block_config")
+        ret.result_rows.append(["ALL", "Not Exist"])
+        return ret
+    except botocore.exceptions.ClientError as e:
+        error_code = e.response["Error"]["Code"]
+        error_message = e.response["Error"]["Message"]
+        logging.error(f"AWS API error: {error_code} - {error_message}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("aws_api_error")
+        ret.result_rows.append(["ERR", "ERR"])
+        ret.error_message = f"{error_code}: {error_message}"
+        return ret
+    except botocore.exceptions.BotoCoreError as e:
+        logging.error(f"Boto3 error occurred: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("boto3_error")
+        ret.result_rows.append(["ERR", "ERR"])
+        ret.error_message = str(e)
+        return ret
+    except Exception as e:
+        logging.error(f"Unexpected error occurred: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("unexpected_error")
+        ret.result_rows.append(["ERR", "ERR"])
+        ret.error_message = str(e)
+        return ret
+
+    public_allow_policy_counter = 0
+    for policy_name, setting in account_policy.items():
+        # if setting == False:  ## E712 lint error
+        if not setting:
+            public_allow_policy_counter += 1
+            ret.result_rows.append([policy_name, "Allow"])
+        else:
+            ret.result_rows.append([policy_name, "Block"])
+
+    nums_of_public_block_access_policies = len(account_policy.items())
+
+    if public_allow_policy_counter == 0:
+        ret.level = level.success
+        ret.msg = translator.translate("success")
+    elif 0 < public_allow_policy_counter < nums_of_public_block_access_policies:
+        ret.level = level.warning
+        ret.msg = translator.translate("warning")
+    elif public_allow_policy_counter == nums_of_public_block_access_policies:
+        ret.level = level.danger
+        ret.msg = translator.translate("danger")
+    else:
+        ret.level = level.error
+        ret.msg = translator.translate("unexpected_error")
+        ret.result_rows = ["ERR", "ERR"]
+
+    return ret

runbooks/security_baseline/checklist/alternate_contacts.py

@@ -0,0 +1,65 @@
+import logging
+
+import botocore.exceptions
+from utils import common
+from utils import level_const as level
+
+
+def check_alternate_contact_filling(session, translator) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["Contact Type", "Name", "E-Mail", "Contacts"]
+
+    contact_type_list = ["BILLING", "SECURITY", "OPERATIONS"]
+    client = session.client("account")
+    ret.level = level.success
+
+    for contact_type in contact_type_list:
+        try:
+            contact = client.get_alternate_contact(AlternateContactType=contact_type)["AlternateContact"]
+        except client.exceptions.ResourceNotFoundException:
+            ret.level = level.warning
+            contact = {"Name": "-", "EmailAddress": "-", "PhoneNumber": "-"}
+        except client.exceptions.ValidationException as e:
+            ret.level = level.error
+            contact = {"Name": "ERR", "EmailAddress": "ERR", "PhoneNumber": "ERR"}
+            ret.error_message = f"Validation Exception: {str(e)}"
+            logging.error(ret.error_message, exc_info=True)
+        except client.exceptions.AccessDeniedException as e:
+            ret.level = level.error
+            contact = {"Name": "ERR", "EmailAddress": "ERR", "PhoneNumber": "ERR"}
+            ret.error_message = f"Access Denied: {str(e)}"
+            logging.error(ret.error_message, exc_info=True)
+        except client.exceptions.TooManyRequestsException:
+            ret.level = level.error
+            contact = {"Name": "ERR", "EmailAddress": "ERR", "PhoneNumber": "ERR"}
+            ret.error_message = "Too Many Request Exception. Please Try Again Later."
+            logging.error(ret.error_message, exc_info=True)
+        except client.exceptions.InternalServerException:
+            ret.level = level.error
+            contact = {"Name": "ERR", "EmailAddress": "ERR", "PhoneNumber": "ERR"}
+            ret.error_message = "Internal Server Exception"
+            logging.error(ret.error_message, exc_info=True)
+        except botocore.exceptions.ClientError as e:
+            ret.level = level.error
+            contact = {"Name": "ERR", "EmailAddress": "ERR", "PhoneNumber": "ERR"}
+            ret.error_message = f"Unexpected ClientError: {str(e)}"
+            logging.error(ret.error_message, exc_info=True)
+        except Exception as e:
+            ret.level = level.error
+            contact = {"Name": "ERR", "EmailAddress": "ERR", "PhoneNumber": "ERR"}
+            ret.error_message = f"Unexpected Exception: {str(e)}"
+            logging.error(ret.error_message, exc_info=True)
+        finally:
+            ret.result_rows.append([contact_type, contact["Name"], contact["EmailAddress"], contact["PhoneNumber"]])
+
+    if ret.level == level.success:
+        ret.msg = translator.translate("success")
+    elif ret.level == level.warning:
+        ret.msg = translator.translate("warning")
+    else:
+        ret.msg = translator.translate("error")
+
+    return ret

runbooks/security_baseline/checklist/bucket_public_access.py

@@ -0,0 +1,82 @@
+import logging
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import botocore.exceptions
+from utils import common
+from utils import level_const as level
+
+MAXIMUM_NUMBER_OF_BUCKET_LIMIT = 1000
+
+
+def get_bucket_info(client, bucket_name) -> tuple:
+    try:
+        bucket_info = client.get_public_access_block(Bucket=bucket_name)
+    except botocore.exceptions.ClientError as e:
+        if e.response["Error"]["Code"] == "NoSuchPublicAccessBlockConfiguration":
+            return level.danger, [bucket_name, "All Allowed"]
+        else:
+            logging.error(f"Error getting public access block for bucket {bucket_name}: {str(e)}", exc_info=True)
+            return level.error, [bucket_name, "ERR"]
+
+    public_access_block_policy_counter = sum(
+        1 for policy_status in bucket_info["PublicAccessBlockConfiguration"].values() if policy_status
+    )
+    nums_of_public_access_block_policies = len(bucket_info["PublicAccessBlockConfiguration"])
+
+    if public_access_block_policy_counter == 0:
+        return level.danger, [bucket_name, "All Allowed"]
+    elif 0 < public_access_block_policy_counter < nums_of_public_access_block_policies:
+        return level.warning, [bucket_name, "Partially Allowed"]
+    elif public_access_block_policy_counter == nums_of_public_access_block_policies:
+        return level.success, [bucket_name, "All Blocked"]
+    else:
+        return level.error, [bucket_name, "Unexpected Exception"]
+
+
+def check_bucket_public_access(session, translator) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["Bucket Name", "Public Access Setting"]
+
+    s3_client = session.client("s3")
+
+    try:
+        bucket_list = s3_client.list_buckets()["Buckets"]
+    except botocore.exceptions.ClientError as e:
+        logging.error(f"Error listing buckets: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("unexpected_error")
+        ret.result_rows.append(["ERR", "ERR"])
+        ret.error_message = str(e)
+        return ret
+
+    with ThreadPoolExecutor() as thread_executor:
+        futures = []
+        if len(bucket_list) > MAXIMUM_NUMBER_OF_BUCKET_LIMIT:
+            ret.level = level.error
+            ret.msg = translator.translate("bucket_limit_warning").format(MAXIMUM_NUMBER_OF_BUCKET_LIMIT)
+            bucket_list = bucket_list[:MAXIMUM_NUMBER_OF_BUCKET_LIMIT]
+
+        for bucket in bucket_list:
+            futures.append(thread_executor.submit(get_bucket_info, s3_client, bucket["Name"]))
+
+        level_flag = level.success
+        for future in as_completed(futures):
+            result_level, result = future.result()
+            if result_level > level_flag:
+                level_flag = result_level
+            ret.result_rows.append(result)
+
+    if level_flag == level.success:
+        ret.msg = translator.translate("success")
+    elif level_flag == level.warning:
+        ret.msg = translator.translate("warning")
+    elif level_flag == level.danger:
+        ret.msg = translator.translate("danger")
+    elif ret.level != level.error:  # Don't overwrite bucket limit warning
+        ret.msg = translator.translate("error")
+
+    ret.level = level_flag
+    return ret