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

runbooks/security_baseline/checklist/cloudwatch_alarm_configuration.py

@@ -0,0 +1,66 @@
+import logging
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import botocore.exceptions
+from utils import common
+from utils import level_const as level
+
+
+def get_cloudwatch_alarms(client, region):
+    try:
+        alarms = client.describe_alarms()["MetricAlarms"]
+        return region, alarms
+    except (client.exceptions.InvalidNextToken, botocore.exceptions.ClientError) as e:
+        logging.error(f"Error getting CloudWatch alarms for region {region}: {str(e)}", exc_info=True)
+        return region, "ERR"
+
+
+def check_cloudwatch_alarm_configuration(session, translator) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["Region", "Name"]
+
+    ec2_client = session.client("ec2")
+
+    try:
+        regions = common.get_opted_in_regions(ec2_client)
+    except botocore.exceptions.ClientError as e:
+        logging.error(f"Error getting opted-in regions: {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 = [
+            thread_executor.submit(get_cloudwatch_alarms, session.client("cloudwatch", region_name=region), region)
+            for region in regions
+        ]
+
+        is_alarm_exist = False
+        ret.result_rows = []
+        error_occurred = False
+
+        for future in as_completed(futures):
+            region, alarms = future.result()
+            if alarms == "ERR":
+                error_occurred = True
+                ret.result_rows.append([region, "ERR"])
+            elif alarms:
+                is_alarm_exist = True
+                ret.result_rows.extend([region, alarm["AlarmName"]] for alarm in alarms)
+
+    if error_occurred:
+        ret.level = level.error
+        ret.msg = translator.translate("retrieval_error")
+    elif is_alarm_exist:
+        ret.level = level.success
+        ret.msg = translator.translate("alarm_exist")
+    else:
+        ret.level = level.warning
+        ret.msg = translator.translate("alarm_not_exist")
+
+    return ret

runbooks/security_baseline/checklist/direct_attached_policy.py

@@ -0,0 +1,69 @@
+import logging
+
+import botocore.exceptions
+from utils import common
+from utils import level_const as level
+
+
+def get_user_policies(client, user_name):
+    try:
+        direct_attached = len(client.list_attached_user_policies(UserName=user_name)["AttachedPolicies"])
+        inline = len(client.list_user_policies(UserName=user_name)["PolicyNames"])
+        return str(direct_attached), str(inline)
+    except botocore.exceptions.ClientError as e:
+        logging.error(f"Error getting policies for user {user_name}: {str(e)}", exc_info=True)
+        return "ERR", "ERR"
+
+
+def check_iam_direct_attached_policy(session, translator) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    client = session.client("iam")
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["IAM User", "Direct Attached Managed Policy", "Inline Policy"]
+
+    try:
+        user_list = client.list_users()["Users"]
+    except client.exceptions.NoSuchEntityException:
+        ret.level = level.warning
+        ret.msg = translator.translate("no_user")
+        ret.result_rows.append(["-", "-", "-"])
+        return ret
+    except client.exceptions.ServiceFailureException as e:
+        ret.level = level.error
+        ret.msg = translator.translate("service_failure")
+        ret.result_rows.append(["ERR", "ERR", "ERR"])
+        ret.error_message = str(e)
+        logging.error(f"Service Failure: {str(e)}", exc_info=True)
+        return ret
+    except botocore.exceptions.ClientError as e:
+        ret.level = level.error
+        ret.msg = translator.translate("unexpected_error")
+        ret.result_rows.append(["ERR", "ERR", "ERR"])
+        ret.error_message = str(e)
+        logging.error(f"Unexpected Error: {str(e)}", exc_info=True)
+        return ret
+
+    if not user_list:
+        ret.level = level.warning
+        ret.msg = translator.translate("no_user")
+        return ret
+
+    ret.level = level.success
+    ret.msg = translator.translate("success")
+
+    for user in user_list:
+        user_name = user["UserName"]
+        direct_attached, inline = get_user_policies(client, user_name)
+
+        if direct_attached == "ERR" or inline == "ERR":
+            ret.level = level.error
+            ret.msg = translator.translate("unexpected_error")
+        else:
+            ret.result_rows.append([user_name, direct_attached, inline])
+            if int(direct_attached) > 0 or int(inline) > 0:
+                ret.level = level.warning
+                ret.msg = translator.translate("warning")
+
+    return ret

runbooks/security_baseline/checklist/guardduty_enabled.py

@@ -0,0 +1,71 @@
+import logging
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import botocore.exceptions
+from utils import common
+from utils import level_const as level
+
+
+def get_guard_duty_configuration(client, region):
+    try:
+        detectors = client.list_detectors()["DetectorIds"]
+        return region, len(detectors)
+    except (
+        client.exceptions.BadRequestException,
+        client.exceptions.InternalServerErrorException,
+        botocore.exceptions.ClientError,
+    ) as e:
+        logging.error(f"Error getting GuardDuty configuration for region {region}: {str(e)}", exc_info=True)
+        return region, "ERR"
+
+
+def check_guard_duty_enabled(session, translator) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["Region", "GuardDuty Setting"]
+
+    ec2_client = session.client("ec2")
+
+    try:
+        regions = common.get_opted_in_regions(ec2_client)
+    except botocore.exceptions.ClientError as e:
+        logging.error(f"Error getting opted-in regions: {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 executor:
+        futures = [
+            executor.submit(get_guard_duty_configuration, session.client("guardduty", region_name=region), region)
+            for region in regions
+        ]
+
+        nums_of_guardduty_enabled = 0
+        error_occurred = False
+
+        for future in as_completed(futures):
+            region, number_of_detectors = future.result()
+            if number_of_detectors == "ERR":
+                error_occurred = True
+                ret.result_rows.append([region, "ERR"])
+            elif number_of_detectors > 0:
+                nums_of_guardduty_enabled += 1
+                ret.result_rows.append([region, "Activated"])
+            else:
+                ret.result_rows.append([region, "Inactivated"])
+
+    if error_occurred:
+        ret.level = level.error
+        ret.msg = translator.translate("retrieval_error")
+    else:
+        ret.level = level.info
+        if nums_of_guardduty_enabled > 0:
+            ret.msg = translator.translate("is_activated")
+        else:
+            ret.msg = translator.translate("is_not_activated")
+
+    return ret

runbooks/security_baseline/checklist/iam_password_policy.py

@@ -0,0 +1,43 @@
+import logging
+
+import botocore.exceptions
+from utils import common
+from utils import level_const as level
+
+
+def check_iam_password_policy(session, translator) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    client = session.client("iam")
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["Password Policy"]
+
+    try:
+        client.get_account_password_policy()
+        ret.level = level.success
+        ret.msg = translator.translate("success")
+    except client.exceptions.NoSuchEntityException:
+        ret.level = level.warning
+        ret.msg = translator.translate("warning")
+        ret.result_rows.append(["Not Set"])
+    except client.exceptions.ServiceFailureException as e:
+        logging.error(f"Service Failure: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("service_failure")
+        ret.result_rows.append(["ERR"])
+        ret.error_message = str(e)
+    except botocore.exceptions.ClientError as e:
+        logging.error(f"Unexpected ClientError: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("unexpected_error")
+        ret.result_rows.append(["ERR"])
+        ret.error_message = str(e)
+    except Exception as e:
+        logging.error(f"Unexpected error: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("unexpected_error")
+        ret.result_rows.append(["ERR"])
+        ret.error_message = str(e)
+
+    return ret

runbooks/security_baseline/checklist/iam_user_mfa.py

@@ -0,0 +1,39 @@
+import logging
+
+from utils import common
+from utils import level_const as level
+
+
+def check_iam_user_mfa_setting(session, translator, credential_report) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["IAM User", "MFA Enabled"]
+
+    if not credential_report:
+        ret.level = level.error
+        ret.msg = translator.translate("credential_report_error")
+        ret.result_rows.append(["ERR", "ERR"])
+        return ret
+
+    user_info_list = common.get_iam_credential_report(credential_report)
+
+    if not user_info_list:
+        ret.level = level.warning
+        ret.msg = translator.translate("no_iam_user")
+        return ret
+
+    ret.level = level.success
+    ret.msg = translator.translate("success")
+
+    for user_info in user_info_list:
+        user_name = user_info[common.CREDENTIAL_REPORT_COLS.USER.value]
+        mfa_status = user_info[common.CREDENTIAL_REPORT_COLS.MFA_ACTIVE.value].upper()
+        ret.result_rows.append([user_name, mfa_status])
+
+        if mfa_status == "FALSE":
+            ret.level = level.danger
+            ret.msg = translator.translate("danger")
+
+    return ret

runbooks/security_baseline/checklist/multi_region_instance_usage.py

@@ -0,0 +1,55 @@
+import logging
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import botocore.exceptions
+from utils import common
+from utils import level_const as level
+
+
+def get_instance_usage_by_region(client, region):
+    try:
+        number_of_instances = sum(
+            len(reservation["Instances"]) for reservation in client.describe_instances()["Reservations"]
+        )
+        return region, str(number_of_instances)
+    except botocore.exceptions.ClientError as e:
+        logging.error(f"Error getting instance usage for region {region}: {str(e)}", exc_info=True)
+        return region, "ERR"
+
+
+def check_multiregion_instance_usage(session, translator) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["Region", "Instance Usage"]
+
+    ec2_client = session.client("ec2")
+
+    try:
+        regions = common.get_opted_in_regions(ec2_client)
+    except botocore.exceptions.ClientError as e:
+        logging.error(f"Error getting opted-in regions: {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 executor:
+        futures = [
+            executor.submit(get_instance_usage_by_region, session.client("ec2", region_name=region), region)
+            for region in regions
+        ]
+
+        ret.level = level.info
+        ret.msg = translator.translate("info_msg")
+
+        for future in as_completed(futures):
+            region, number_of_instances = future.result()
+            if number_of_instances == "ERR":
+                ret.level = level.error
+                ret.msg = translator.translate("retrieval_error")
+            ret.result_rows.append([region, number_of_instances])
+
+    return ret

runbooks/security_baseline/checklist/multi_region_trail.py

@@ -0,0 +1,64 @@
+import logging
+
+import botocore.exceptions
+from utils import common
+from utils import level_const as level
+
+
+def check_multi_region_trail_enabled(session, translator) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["Trail", "Multi-Region Logging"]
+
+    client = session.client("cloudtrail")
+
+    try:
+        trails = client.describe_trails()["trailList"]
+    except (
+        client.exceptions.UnsupportedOperationException,
+        client.exceptions.OperationNotPermittedException,
+        client.exceptions.NoManagementAccountSLRExistsException,
+        botocore.exceptions.ClientError,
+    ) as e:
+        logging.error(f"Error describing trails: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("describe_trails_error")
+        ret.result_rows.append(["ERR", "ERR"])
+        ret.error_message = str(e)
+        return ret
+
+    if not trails:
+        ret.level = level.danger
+        ret.msg = translator.translate("no_trail")
+        ret.result_rows.append(["-", "-"])
+        return ret
+
+    logging_disabled_counter = 0
+    for trail in trails:
+        trail_arn = trail["TrailARN"]
+        try:
+            is_multi_region = client.get_trail(Name=trail_arn)["Trail"]["IsMultiRegionTrail"]
+            ret.result_rows.append([trail_arn, str(is_multi_region)])
+            if not is_multi_region:
+                logging_disabled_counter += 1
+        except botocore.exceptions.ClientError as e:
+            logging.error(f"Error getting trail {trail_arn}: {str(e)}", exc_info=True)
+            ret.result_rows.append([trail_arn, "ERR"])
+            ret.level = level.error
+            ret.msg = translator.translate("get_trail_error")
+            ret.error_message = str(e)
+
+    if ret.level != level.error:
+        if logging_disabled_counter == len(trails):
+            ret.level = level.danger
+            ret.msg = translator.translate("danger")
+        elif logging_disabled_counter > 0:
+            ret.level = level.warning
+            ret.msg = translator.translate("warning")
+        else:
+            ret.level = level.success
+            ret.msg = translator.translate("success")
+
+    return ret

runbooks/security_baseline/checklist/root_access_key.py

@@ -0,0 +1,72 @@
+import logging
+from datetime import datetime, timedelta, timezone
+
+from utils import common
+from utils import level_const as level
+
+
+def get_last_used_days(date):
+    if date in ("N/A", "no_information"):
+        return timedelta.max
+    return datetime.now(timezone.utc) - datetime.fromisoformat(date[:-6])
+
+
+def format_last_used(last_used_days):
+    if last_used_days == timedelta.max:
+        return "N/A"
+    if last_used_days.days == 0:
+        return "Today"
+    return f"{last_used_days.days} days before"
+
+
+def check_access_key(root_credential_report, key_number):
+    key_active = root_credential_report[
+        getattr(common.CREDENTIAL_REPORT_COLS, f"ACCESS_KEY_{key_number}_ACTIVE").value
+    ].upper()
+    key_last_used = root_credential_report[
+        getattr(common.CREDENTIAL_REPORT_COLS, f"ACCESS_KEY_{key_number}_LAST_USED_DATE").value
+    ]
+
+    if key_active == "TRUE":
+        last_used_days = get_last_used_days(key_last_used)
+        return f"AccessKey{key_number}", "In Use", format_last_used(last_used_days), True
+    return f"AccessKey{key_number}", "Not In Use", "N/A", False
+
+
+def check_root_accesskey_usage(session, translator, credential_report) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["Access Key", "Status", "Last Used Date"]
+
+    if not credential_report:
+        ret.level = level.error
+        ret.msg = translator.translate("credential_report_error")
+        ret.result_rows.append(["ERR", "ERR", "ERR"])
+        return ret
+
+    try:
+        root_credential_report = common.get_root_credential_report(credential_report)
+
+        key_in_use = False
+        for key_number in [1, 2]:
+            key, status, last_used, is_active = check_access_key(root_credential_report, key_number)
+            ret.result_rows.append([key, status, last_used])
+            key_in_use = key_in_use or is_active
+
+        if key_in_use:
+            ret.level = level.danger
+            ret.msg = translator.translate("danger")
+        else:
+            ret.level = level.success
+            ret.msg = translator.translate("success")
+
+    except Exception as e:
+        logging.error(f"Error processing root access key check: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("processing_error")
+        ret.result_rows.append(["ERR", "ERR", "ERR"])
+        ret.error_message = str(e)
+
+    return ret

runbooks/security_baseline/checklist/root_mfa.py

@@ -0,0 +1,39 @@
+import logging
+
+from utils import common
+from utils import level_const as level
+
+
+def check_root_mfa_setting(session, translator, credential_report) -> common.CheckResult:
+    logging.info(translator.translate("checking"))
+
+    ret = common.CheckResult()
+    ret.title = translator.translate("title")
+    ret.result_cols = ["MFA Setting"]
+
+    if not credential_report:
+        ret.level = level.error
+        ret.msg = translator.translate("credential_report_error")
+        ret.result_rows.append(["ERR"])
+        return ret
+
+    try:
+        root_credential_report = common.get_root_credential_report(credential_report)
+        mfa_status = root_credential_report[common.CREDENTIAL_REPORT_COLS.MFA_ACTIVE.value].upper()
+    except Exception as e:
+        logging.error(f"Error processing root credential report: {str(e)}", exc_info=True)
+        ret.level = level.error
+        ret.msg = translator.translate("processing_error")
+        ret.result_rows.append(["ERR"])
+        ret.error_message = str(e)
+        return ret
+
+    if mfa_status == "TRUE":
+        ret.level = level.success
+        ret.msg = translator.translate("success")
+    else:
+        ret.level = level.danger
+        ret.msg = translator.translate("danger")
+
+    ret.result_rows.append([mfa_status])
+    return ret

runbooks/security_baseline/checklist/root_usage.py

@@ -0,0 +1,128 @@
+from datetime import datetime, timedelta, timezone
+
+from utils import common
+from utils import level_const as level
+
+from runbooks.utils.logger import configure_logger
+
+logger = configure_logger(__name__)  ## ✅ Configure Logger
+
+## Define the standard threshold for root account access
+ROOT_ACCESS_DAYS_STANDARD = 7
+
+
+## @depreciated def get_root_access_days(date):
+def get_root_access_days(date: str) -> timedelta:
+    """
+    Calculates the timedelta between a given ISO datetime string and now, with robust error handling.
+
+    Args:
+        date (str): The ISO format string to parse.
+
+    Returns:
+        timedelta: The time difference between the given date and now,
+                   or timedelta.max for invalid or missing dates.
+    """
+    if not date or date in ("N/A", "no_information"):
+        return timedelta.max
+
+    try:
+        parsed_date = datetime.fromisoformat(date)
+    except ValueError:
+        try:
+            ## Strips the last 6 characters in the timezone offset (e.g., +00:00).
+            parsed_date = datetime.fromisoformat(date[:-6])
+        except ValueError:
+            logger.warning(f"Invalid date format encountered: {date}")
+            return timedelta.max
+
+    return datetime.now(timezone.utc) - parsed_date
+
+
+def format_last_access_message(last_used_timedelta):
+    """
+    Formats a user-friendly message for last access time.
+
+    Args:
+        last_used_timedelta (timedelta): Time since last access.
+
+    Returns:
+        str: A descriptive message.
+    """
+    if last_used_timedelta == timedelta.max:
+        return "No history"
+    if last_used_timedelta.days == 0:
+        return "Today"
+    return f"{last_used_timedelta.days} days ago"
+
+
+def check_root_usage(session, translator, credential_report) -> common.CheckResult:
+    """
+    Performs a security check on root account usage.
+
+    Args:
+        session: AWS session object (reserved for future extensions).
+        translator: Translator for multi-language support.
+        credential_report: Credential report from AWS.
+
+    Returns:
+        common.CheckResult: The result of the root usage security check.
+    """
+    logger.info(translator.translate("checking"))
+
+    result = common.CheckResult()
+    result.title = translator.translate("title")
+    result.result_cols = ["Credential Type", "Last Access Date"]
+
+    ## Handle missing credential report
+    if not credential_report:
+        result.level = level.error
+        result.msg = translator.translate("credential_report_error")
+        result.result_rows.append(["ERR", "No Credential Report Available"])
+        return result
+
+    try:
+        ## Retrieve root credential details
+        root_credential_report = common.get_root_credential_report(credential_report)
+
+        ## Calculate days since last usage for each credential type
+        password_last_used = get_root_access_days(
+            root_credential_report[common.CREDENTIAL_REPORT_COLS.PASSWORD_LAST_USED.value]
+        )
+        access_key1_last_used = get_root_access_days(
+            root_credential_report[common.CREDENTIAL_REPORT_COLS.ACCESS_KEY_1_LAST_USED_DATE.value]
+        )
+        access_key2_last_used = get_root_access_days(
+            root_credential_report[common.CREDENTIAL_REPORT_COLS.ACCESS_KEY_2_LAST_USED_DATE.value]
+        )
+
+        ## Determine the most recent access across all credentials
+        last_access_days = min(password_last_used, access_key1_last_used, access_key2_last_used)
+
+        if last_access_days > timedelta(ROOT_ACCESS_DAYS_STANDARD):
+            result.level = level.success
+            result.msg = translator.translate("success").format(ROOT_ACCESS_DAYS_STANDARD)
+        elif last_access_days.days == 0:
+            result.level = level.danger
+            result.msg = translator.translate("access_today")
+        else:
+            result.level = level.danger
+            result.msg = translator.translate("danger").format(last_access_days.days)
+
+        ## Add detailed result rows for each credential type
+        result.result_rows.extend(
+            [
+                ["PASSWORD", format_last_access_message(password_last_used)],
+                ["ACCESS KEY1", format_last_access_message(access_key1_last_used)],
+                ["ACCESS KEY2", format_last_access_message(access_key2_last_used)],
+            ]
+        )
+
+    except Exception as e:
+        logger.error(f"Error processing root usage check: {str(e)}", exc_info=True)
+        result.level = level.error
+        result.msg = translator.translate("processing_error")
+        result.result_rows.append(["ERR", "Processing Error"])
+        result.error_message = str(e)
+
+    return result