ec2-security-scanner 1.0.0__py3-none-any.whl

ec2_security_scanner/__init__.py

@@ -0,0 +1,11 @@
+"""EC2 Security Scanner - Comprehensive AWS EC2 security auditing tool
+with multi-framework compliance mapping."""
+
+__version__ = "1.0.0"
+__author__ = "Toc Consulting"
+__email__ = "tarek@tocconsulting.fr"
+
+from .scanner import EC2SecurityScanner
+from .compliance import ComplianceChecker
+
+__all__ = ["EC2SecurityScanner", "ComplianceChecker"]

ec2_security_scanner/checks/__init__.py

@@ -0,0 +1,21 @@
+"""EC2 Security Scanner - Security Check Modules."""
+
+from .instance_security import InstanceSecurityChecker
+from .network_security import NetworkSecurityChecker
+from .storage_security import StorageSecurityChecker
+from .access_control import AccessControlChecker
+from .logging_monitoring import LoggingMonitoringChecker
+from .patch_vulnerability import PatchVulnerabilityChecker
+from .network_exposure import NetworkExposureChecker
+from .tagging_inventory import TaggingInventoryChecker
+
+__all__ = [
+    "InstanceSecurityChecker",
+    "NetworkSecurityChecker",
+    "StorageSecurityChecker",
+    "AccessControlChecker",
+    "LoggingMonitoringChecker",
+    "PatchVulnerabilityChecker",
+    "NetworkExposureChecker",
+    "TaggingInventoryChecker",
+]

ec2_security_scanner/checks/access_control.py

@@ -0,0 +1,266 @@
+"""Access Control Checker - Checks D.1 through D.4.
+
+Covers: IAM role least privilege, key pair usage, serial console access,
+and EC2 Instance Connect endpoints.
+"""
+
+import json
+import logging
+from typing import Dict, Any
+
+from botocore.exceptions import ClientError
+
+from .base import BaseChecker
+
+
+logger = logging.getLogger("ec2_security_scanner")
+
+# Known overly permissive managed policies
+ADMIN_POLICIES = [
+    "arn:aws:iam::aws:policy/AdministratorAccess",
+    "arn:aws:iam::aws:policy/PowerUserAccess",
+    "arn:aws:iam::aws:policy/IAMFullAccess",
+    "arn:aws:iam::aws:policy/AmazonEC2FullAccess",
+    "arn:aws:iam::aws:policy/AmazonS3FullAccess",
+]
+
+
+class AccessControlChecker(BaseChecker):
+    """Checks D.1-D.4: Access control configuration."""
+
+    def check_iam_role(
+        self, instance: Dict, region: str
+    ) -> Dict[str, Any]:
+        """D.1 - IAM roles attached to instances should follow least privilege.
+
+        Flags roles with *:* actions, AdministratorAccess, or wildcard resources.
+        """
+        iam_profile = instance.get("IamInstanceProfile")
+        if not iam_profile:
+            return {
+                "has_admin_access": False,
+                "has_wildcard_actions": False,
+                "overly_permissive_policies": [],
+            }
+
+        profile_arn = iam_profile.get("Arn", "")
+        profile_name = (
+            profile_arn.split("/")[-1] if "/" in profile_arn else profile_arn
+        )
+
+        try:
+            iam = self.get_client("iam")
+            overly_permissive = []
+            has_admin = False
+            has_wildcard = False
+
+            # Get instance profile to find the role
+            ip_response = iam.get_instance_profile(
+                InstanceProfileName=profile_name
+            )
+            roles = ip_response.get("InstanceProfile", {}).get("Roles", [])
+
+            for role in roles:
+                role_name = role["RoleName"]
+
+                # Check attached managed policies
+                attached_policies = []
+                att_paginator = iam.get_paginator(
+                    "list_attached_role_policies"
+                )
+                for page in att_paginator.paginate(
+                    RoleName=role_name
+                ):
+                    attached_policies.extend(
+                        page.get("AttachedPolicies", [])
+                    )
+                for policy in attached_policies:
+                    policy_arn = policy["PolicyArn"]
+
+                    # Check for known admin policies
+                    if any(
+                        admin_arn in policy_arn
+                        for admin_arn in ADMIN_POLICIES
+                    ):
+                        has_admin = True
+                        overly_permissive.append(policy["PolicyName"])
+                        continue
+
+                    # Check policy document for wildcards
+                    try:
+                        policy_detail = iam.get_policy(
+                            PolicyArn=policy_arn
+                        )
+                        version_id = policy_detail["Policy"][
+                            "DefaultVersionId"
+                        ]
+                        version = iam.get_policy_version(
+                            PolicyArn=policy_arn, VersionId=version_id
+                        )
+                        document = version["PolicyVersion"]["Document"]
+                        if isinstance(document, str):
+                            document = json.loads(document)
+
+                        if self._has_wildcard_permissions(document):
+                            has_wildcard = True
+                            overly_permissive.append(policy["PolicyName"])
+                    except ClientError:
+                        continue
+
+                # Check inline policies
+                inline_names = []
+                inl_paginator = iam.get_paginator(
+                    "list_role_policies"
+                )
+                for page in inl_paginator.paginate(
+                    RoleName=role_name
+                ):
+                    inline_names.extend(
+                        page.get("PolicyNames", [])
+                    )
+                for policy_name in inline_names:
+                    try:
+                        inline_policy = iam.get_role_policy(
+                            RoleName=role_name, PolicyName=policy_name
+                        )
+                        document = inline_policy.get("PolicyDocument", {})
+                        if isinstance(document, str):
+                            document = json.loads(document)
+
+                        if self._has_wildcard_permissions(document):
+                            has_wildcard = True
+                            overly_permissive.append(policy_name)
+                    except ClientError:
+                        continue
+
+            return {
+                "has_admin_access": has_admin,
+                "has_wildcard_actions": has_wildcard,
+                "overly_permissive_policies": list(set(overly_permissive)),
+            }
+        except ClientError as e:
+            return self.handle_client_error(e, {
+                "has_admin_access": False,
+                "has_wildcard_actions": False,
+                "overly_permissive_policies": [],
+            })
+
+    def _has_wildcard_permissions(self, document: Dict) -> bool:
+        """Check if a policy document contains overly broad permissions.
+
+        Flags:
+        - Full wildcard: Action=* (regardless of Resource).
+        - NotAction or NotResource: inverse statements grant everything
+          except what's listed, almost always over-broad.
+        - Service or resource wildcard: Action=<service>:*  with a
+          Resource that is "*" or ends with ":*" (e.g. "arn:aws:s3:::*").
+        """
+        statements = document.get("Statement", [])
+        if not isinstance(statements, list):
+            statements = [statements]
+
+        def _is_wild_resource(value: str) -> bool:
+            return value == "*" or value.endswith(":*")
+
+        for stmt in statements:
+            if stmt.get("Effect") != "Allow":
+                continue
+
+            # NotAction / NotResource almost always over-broad.
+            if "NotAction" in stmt or "NotResource" in stmt:
+                return True
+
+            actions = stmt.get("Action", [])
+            if isinstance(actions, str):
+                actions = [actions]
+
+            resources = stmt.get("Resource", [])
+            if isinstance(resources, str):
+                resources = [resources]
+
+            # Action == "*" is admin regardless of Resource.
+            if any(a == "*" for a in actions if isinstance(a, str)):
+                return True
+
+            # Service-wildcard action + any wildcardish resource.
+            has_service_wildcard = any(
+                isinstance(a, str) and a.endswith(":*") for a in actions
+            )
+            has_wild_resource = any(
+                isinstance(r, str) and _is_wild_resource(r)
+                for r in resources
+            )
+            if has_service_wildcard and has_wild_resource:
+                return True
+
+        return False
+
+    def check_key_pair(
+        self, instance: Dict, instance_id: str, region: str
+    ) -> Dict[str, Any]:
+        """D.2 - Review instances using key pairs.
+
+        Prefer SSM Session Manager or Instance Connect over SSH key pairs.
+        """
+        key_name = instance.get("KeyName")
+
+        # Check if SSM-managed (mitigates key pair concern)
+        ssm_managed = False
+        try:
+            ssm = self.get_client("ssm", region)
+            response = ssm.describe_instance_information(
+                Filters=[{
+                    "Key": "InstanceIds",
+                    "Values": [instance_id],
+                }]
+            )
+            instances = response.get("InstanceInformationList", [])
+            ssm_managed = len(instances) > 0
+        except ClientError:
+            pass
+
+        return {
+            "has_key_pair": key_name is not None,
+            "key_name": key_name,
+            "ssm_managed": ssm_managed,
+        }
+
+    def check_serial_console(self, region: str) -> Dict[str, Any]:
+        """D.3 - EC2 serial console access should be disabled at account level.
+
+        Account-level check — runs once per scan.
+        """
+        try:
+            ec2 = self.get_client("ec2", region)
+            response = ec2.get_serial_console_access_status()
+            enabled = response.get("SerialConsoleAccessEnabled", False)
+            return {"enabled": enabled}
+        except ClientError as e:
+            return self.handle_client_error(e, {"enabled": False})
+
+    def check_instance_connect(
+        self, vpc_id: str, region: str
+    ) -> Dict[str, Any]:
+        """D.4 - Check if EC2 Instance Connect endpoints are configured.
+
+        Informational check for secure access without public IPs.
+        """
+        try:
+            ec2 = self.get_client("ec2", region)
+            endpoints = []
+            paginator = ec2.get_paginator(
+                "describe_instance_connect_endpoints"
+            )
+            for page in paginator.paginate(
+                Filters=[{"Name": "vpc-id", "Values": [vpc_id]}]
+            ):
+                endpoints.extend(
+                    page.get("InstanceConnectEndpoints", [])
+                )
+            return {
+                "endpoints_configured": len(endpoints) > 0,
+            }
+        except ClientError as e:
+            return self.handle_client_error(
+                e, {"endpoints_configured": False}
+            )

ec2_security_scanner/checks/base.py

@@ -0,0 +1,101 @@
+"""Base class for all security checkers."""
+
+import logging
+
+import boto3
+from botocore.exceptions import ClientError
+from typing import Dict, Any
+
+
+logger = logging.getLogger("ec2_security_scanner")
+
+
+# Error codes that all mean "the scanning role lacks this permission".
+# EC2 raises UnauthorizedOperation; IAM/STS/SSM raise AccessDenied or
+# AccessDeniedException depending on the service.
+ACCESS_DENIED_CODES = frozenset({
+    "AccessDenied",
+    "AccessDeniedException",
+    "UnauthorizedOperation",
+    "UnauthorizedAccess",
+    "AuthFailure",
+})
+
+
+class BaseChecker:
+    """Base class for all security checkers.
+
+    Provides thread-safe AWS client creation via session_factory
+    and standardized error handling.
+    """
+
+    def __init__(self, session_factory=None):
+        """Initialize the checker with optional session factory.
+
+        Args:
+            session_factory: Callable that returns a boto3 session
+                (for thread safety) or a boto3 session object
+                (for backward compatibility).
+        """
+        self.session_factory = session_factory
+
+    def get_client(self, service_name: str, region_name: str = None):
+        """Get AWS client for the specified service.
+
+        Uses the thread-safe session factory to create clients,
+        ensuring each thread gets its own session.
+
+        Args:
+            service_name: AWS service name (e.g., 'ec2', 'iam', 'ssm')
+            region_name: AWS region name (optional)
+
+        Returns:
+            boto3 client for the service
+        """
+        if self.session_factory:
+            session = (
+                self.session_factory()
+                if callable(self.session_factory)
+                else self.session_factory
+            )
+            kwargs = {"region_name": region_name} if region_name else {}
+            return session.client(service_name, **kwargs)
+        else:
+            kwargs = {"region_name": region_name} if region_name else {}
+            return boto3.client(service_name, **kwargs)
+
+    def handle_client_error(
+        self, e: ClientError, default_response: Dict[str, Any] = None
+    ) -> Dict[str, Any]:
+        """Handle ClientError exceptions consistently.
+
+        Logs the error and returns a safe default response dict.
+        Special handling for AccessDeniedException to allow graceful
+        degradation when permissions are insufficient.
+
+        Args:
+            e: ClientError exception
+            default_response: Default response dict to return
+
+        Returns:
+            Error response dict with 'error' key
+        """
+        error_code = e.response.get("Error", {}).get("Code", "Unknown")
+        error_msg = str(e)
+
+        if error_code in ACCESS_DENIED_CODES:
+            logger.warning(
+                f"Access denied ({error_code}): {error_msg} - "
+                "scan will continue with limited results"
+            )
+        else:
+            logger.warning(f"AWS API error: {error_msg}")
+
+        if default_response is None:
+            default_response = {
+                "error": error_msg,
+            }
+        else:
+            default_response["error"] = error_msg
+
+        return default_response