complio 0.1.1__py3-none-any.whl

complio/tests_library/storage/s3_versioning.py

@@ -0,0 +1,264 @@
+"""
+S3 bucket versioning compliance test.
+
+Checks that all S3 buckets have versioning enabled for data recovery.
+
+ISO 27001 Control: A.8.13 - Information backup
+Requirement: S3 buckets must have versioning enabled
+
+Example:
+    >>> from complio.connectors.aws.client import AWSConnector
+    >>> from complio.tests_library.storage.s3_versioning import S3VersioningTest
+    >>>
+    >>> connector = AWSConnector("production", "us-east-1")
+    >>> connector.connect()
+    >>>
+    >>> test = S3VersioningTest(connector)
+    >>> result = test.run()
+    >>> print(f"Passed: {result.passed}, Score: {result.score}")
+"""
+
+from typing import Any, Dict
+
+from botocore.exceptions import ClientError
+
+from complio.connectors.aws.client import AWSConnector
+from complio.tests_library.base import (
+    ComplianceTest,
+    Severity,
+    TestResult,
+    TestStatus,
+)
+
+
+class S3VersioningTest(ComplianceTest):
+    """Test for S3 bucket versioning compliance.
+
+    Verifies that all S3 buckets have versioning enabled to protect
+    against accidental deletion and provide data recovery capabilities.
+
+    Compliance Requirements:
+        - All S3 buckets must have versioning enabled (Status='Enabled')
+        - MFA Delete is recommended for additional protection (bonus check)
+        - Versioning protects against accidental deletion and modification
+
+    Scoring:
+        - 100% if all buckets have versioning enabled
+        - Proportional score based on compliant/total ratio
+        - 0% if no buckets have versioning enabled
+
+    Example:
+        >>> test = S3VersioningTest(connector)
+        >>> result = test.execute()
+        >>> for finding in result.findings:
+        ...     print(f"{finding.resource_id}: {finding.title}")
+    """
+
+    def __init__(self, connector: AWSConnector) -> None:
+        """Initialize S3 versioning test.
+
+        Args:
+            connector: AWS connector instance
+        """
+        super().__init__(
+            test_id="s3_versioning",
+            test_name="S3 Bucket Versioning Check",
+            description="Verify all S3 buckets have versioning enabled for data recovery",
+            control_id="A.8.13",
+            connector=connector,
+            scope="global",
+        )
+
+    def execute(self) -> TestResult:
+        """Execute S3 bucket versioning compliance test.
+
+        Returns:
+            TestResult with findings for buckets without versioning
+
+        Example:
+            >>> test = S3VersioningTest(connector)
+            >>> result = test.execute()
+            >>> print(result.score)
+            85.0
+        """
+        result = TestResult(
+            test_id=self.test_id,
+            test_name=self.test_name,
+            status=TestStatus.PASSED,
+            passed=True,
+            score=100.0,
+        )
+
+        try:
+            # Get S3 client
+            s3_client = self.connector.get_client("s3")
+
+            # List all buckets
+            self.logger.info("listing_s3_buckets")
+            buckets_response = s3_client.list_buckets()
+            buckets = buckets_response.get("Buckets", [])
+
+            if not buckets:
+                self.logger.info("no_s3_buckets_found")
+                result.metadata["message"] = "No S3 buckets found in account"
+                return result
+
+            self.logger.info("s3_buckets_found", count=len(buckets))
+
+            # Check versioning for each bucket
+            versioning_enabled_count = 0
+
+            for bucket in buckets:
+                bucket_name = bucket["Name"]
+                result.resources_scanned += 1
+
+                try:
+                    # Get bucket versioning configuration
+                    versioning_response = s3_client.get_bucket_versioning(Bucket=bucket_name)
+
+                    # Check versioning status
+                    versioning_status = versioning_response.get("Status", "Disabled")
+                    mfa_delete = versioning_response.get("MFADelete", "Disabled")
+
+                    versioning_enabled = versioning_status == "Enabled"
+
+                    # Create evidence
+                    evidence = self.create_evidence(
+                        resource_id=bucket_name,
+                        resource_type="s3_bucket",
+                        data={
+                            "bucket_name": bucket_name,
+                            "versioning_status": versioning_status,
+                            "mfa_delete": mfa_delete,
+                            "creation_date": bucket.get("CreationDate").isoformat() if bucket.get("CreationDate") else None,
+                        }
+                    )
+                    result.add_evidence(evidence)
+
+                    if versioning_enabled:
+                        versioning_enabled_count += 1
+                        self.logger.debug(
+                            "bucket_versioning_enabled",
+                            bucket=bucket_name,
+                            mfa_delete=mfa_delete
+                        )
+                    else:
+                        # Create finding for bucket without versioning
+                        finding = self.create_finding(
+                            resource_id=bucket_name,
+                            resource_type="s3_bucket",
+                            severity=Severity.MEDIUM,
+                            title="S3 bucket versioning not enabled",
+                            description=f"S3 bucket '{bucket_name}' does not have versioning enabled "
+                                        f"(current status: {versioning_status}). Without versioning, objects "
+                                        "can be permanently deleted or overwritten accidentally. Versioning "
+                                        "protects against unintended user actions, application failures, and "
+                                        "provides the ability to recover previous versions. "
+                                        "ISO 27001 A.8.13 requires proper backup and recovery capabilities.",
+                            remediation=(
+                                f"Enable versioning for S3 bucket '{bucket_name}':\n\n"
+                                "Using AWS CLI:\n"
+                                f"aws s3api put-bucket-versioning --bucket {bucket_name} \\\n"
+                                "  --versioning-configuration Status=Enabled\n\n"
+                                "Or use AWS Console:\n"
+                                "1. Go to AWS S3 console\n"
+                                f"2. Select bucket '{bucket_name}'\n"
+                                "3. Go to 'Properties' tab\n"
+                                "4. Under 'Bucket Versioning', click 'Edit'\n"
+                                "5. Select 'Enable'\n"
+                                "6. Click 'Save changes'\n\n"
+                                "Optional: Enable MFA Delete for additional protection:\n"
+                                f"aws s3api put-bucket-versioning --bucket {bucket_name} \\\n"
+                                "  --versioning-configuration Status=Enabled,MFADelete=Enabled \\\n"
+                                "  --mfa \"arn:aws:iam::ACCOUNT-ID:mfa/root-account-mfa-device XXXXXX\"\n\n"
+                                "Note: MFA Delete requires root account credentials.\n"
+                                "Consider lifecycle policies to manage versioned objects and costs."
+                            ),
+                            evidence=evidence
+                        )
+                        result.add_finding(finding)
+
+                        self.logger.warning(
+                            "bucket_versioning_disabled",
+                            bucket=bucket_name,
+                            status=versioning_status
+                        )
+
+                except ClientError as e:
+                    error_code = e.response.get("Error", {}).get("Code")
+                    if error_code in ["NoSuchBucket", "AccessDenied"]:
+                        self.logger.warning(
+                            "bucket_versioning_check_error",
+                            bucket=bucket_name,
+                            error_code=error_code
+                        )
+                        continue
+                    else:
+                        raise
+
+            # Calculate compliance score
+            result.score = (versioning_enabled_count / len(buckets)) * 100
+
+            # Determine pass/fail
+            result.passed = versioning_enabled_count == len(buckets)
+            result.status = TestStatus.PASSED if result.passed else TestStatus.FAILED
+
+            # Add metadata
+            result.metadata = {
+                "total_buckets": len(buckets),
+                "versioning_enabled": versioning_enabled_count,
+                "versioning_disabled": len(buckets) - versioning_enabled_count,
+                "compliance_percentage": result.score,
+            }
+
+            self.logger.info(
+                "s3_versioning_test_completed",
+                total_buckets=len(buckets),
+                versioning_enabled=versioning_enabled_count,
+                score=result.score,
+                passed=result.passed
+            )
+
+        except ClientError as e:
+            error_code = e.response.get("Error", {}).get("Code")
+            self.logger.error("s3_versioning_test_error", error_code=error_code, error=str(e))
+            result.status = TestStatus.ERROR
+            result.passed = False
+            result.score = 0.0
+            result.error_message = f"AWS API Error: {error_code} - {str(e)}"
+
+        except Exception as e:
+            self.logger.error("s3_versioning_test_error", error=str(e))
+            result.status = TestStatus.ERROR
+            result.passed = False
+            result.score = 0.0
+            result.error_message = str(e)
+
+        return result
+
+
+# ============================================================================
+# CONVENIENCE FUNCTION
+# ============================================================================
+
+
+def run_s3_versioning_test(connector: AWSConnector) -> TestResult:
+    """Run S3 bucket versioning compliance test.
+
+    Convenience function for running the test.
+
+    Args:
+        connector: AWS connector
+
+    Returns:
+        TestResult
+
+    Example:
+        >>> from complio.connectors.aws.client import AWSConnector
+        >>> connector = AWSConnector("production", "us-east-1")
+        >>> connector.connect()
+        >>> result = run_s3_versioning_test(connector)
+        >>> print(f"Score: {result.score}%")
+    """
+    test = S3VersioningTest(connector)
+    return test.execute()

complio/utils/__init__.py

@@ -0,0 +1,26 @@
+"""Utility modules for Complio."""
+
+from complio.utils.exceptions import (
+    AWSConnectionError,
+    AWSCredentialsError,
+    AWSError,
+    ComplioError,
+    InvalidRegionError,
+    ValidationError,
+)
+from complio.utils.logger import get_logger, setup_logging
+
+__all__ = [
+    # Logging
+    "get_logger",
+    "setup_logging",
+    # Exceptions - Base
+    "ComplioError",
+    "AWSError",
+    # Exceptions - AWS
+    "AWSConnectionError",
+    "AWSCredentialsError",
+    "InvalidRegionError",
+    # Exceptions - Validation
+    "ValidationError",
+]

complio/utils/errors.py

@@ -0,0 +1,179 @@
+"""
+User-friendly error message translation for Complio.
+
+This module translates technical AWS and system errors into actionable,
+user-friendly messages with clear next steps.
+
+Example:
+    >>> from complio.utils.errors import handle_aws_error
+    >>> try:
+    >>>     connector.connect()
+    >>> except Exception as e:
+    >>>     handle_aws_error(e)
+"""
+
+import configparser
+import os
+import sys
+from typing import NoReturn
+
+import click
+from botocore.exceptions import (
+    ClientError,
+    EndpointConnectionError,
+    NoCredentialsError,
+    PartialCredentialsError,
+    ProfileNotFound,
+)
+
+
+def handle_aws_error(error: Exception) -> NoReturn:
+    """Translate technical AWS errors to user-friendly messages.
+
+    This function catches common AWS errors and displays helpful messages
+    with actionable next steps instead of technical stack traces.
+
+    Args:
+        error: The exception that was raised
+
+    Raises:
+        SystemExit: Always exits with code 1 after displaying the error
+
+    Example:
+        >>> try:
+        >>>     session = boto3.Session(profile_name="nonexistent")
+        >>> except Exception as e:
+        >>>     handle_aws_error(e)
+        >>> # Displays: "❌ AWS profile 'nonexistent' not found"
+        >>> # Then lists available profiles
+    """
+
+    if isinstance(error, NoCredentialsError):
+        click.echo("❌ AWS credentials not found", err=True)
+        click.echo("\nTo configure AWS credentials:", err=True)
+        click.echo("  1. Run: aws configure", err=True)
+        click.echo("  2. Enter your Access Key ID and Secret Access Key", err=True)
+        click.echo("\nFor help: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html", err=True)
+        sys.exit(1)
+
+    elif isinstance(error, PartialCredentialsError):
+        click.echo("❌ Incomplete AWS credentials", err=True)
+        click.echo("\nYour AWS credentials are missing required information.", err=True)
+        click.echo("Run: aws configure", err=True)
+        sys.exit(1)
+
+    elif isinstance(error, ProfileNotFound):
+        # Extract profile name from error message
+        profile = str(error).split("'")[1] if "'" in str(error) else "unknown"
+        click.echo(f"❌ AWS profile '{profile}' not found", err=True)
+        click.echo(f"\nAvailable profiles in ~/.aws/credentials:", err=True)
+        try:
+            config = configparser.ConfigParser()
+            config.read(os.path.expanduser('~/.aws/credentials'))
+            if config.sections():
+                for prof in config.sections():
+                    click.echo(f"  • {prof}", err=True)
+            else:
+                click.echo("  (No profiles configured)", err=True)
+                click.echo("\nRun 'aws configure' to create a profile", err=True)
+        except Exception:
+            click.echo("  (Unable to read credentials file)", err=True)
+        sys.exit(1)
+
+    elif isinstance(error, EndpointConnectionError):
+        click.echo("❌ Cannot connect to AWS", err=True)
+        click.echo("\nPossible causes:", err=True)
+        click.echo("  • No internet connection", err=True)
+        click.echo("  • Invalid region specified", err=True)
+        click.echo("  • Corporate firewall blocking AWS", err=True)
+        sys.exit(1)
+
+    elif isinstance(error, ClientError):
+        error_code = error.response.get('Error', {}).get('Code', 'Unknown')
+        error_message = error.response.get('Error', {}).get('Message', '')
+
+        if error_code == 'UnauthorizedOperation':
+            click.echo("❌ Insufficient AWS permissions", err=True)
+            click.echo("\nYour AWS user needs the 'SecurityAudit' policy.", err=True)
+            click.echo("Contact your AWS administrator to grant permissions.", err=True)
+
+        elif error_code == 'InvalidClientTokenId':
+            click.echo("❌ Invalid AWS credentials", err=True)
+            click.echo("\nYour Access Key ID is not recognized by AWS.", err=True)
+            click.echo("Run 'aws configure' to update your credentials.", err=True)
+
+        elif error_code == 'SignatureDoesNotMatch':
+            click.echo("❌ Invalid AWS credentials", err=True)
+            click.echo("\nYour Secret Access Key is incorrect.", err=True)
+            click.echo("Run 'aws configure' to update your credentials.", err=True)
+
+        elif error_code == 'AccessDenied':
+            click.echo("❌ Access denied", err=True)
+            click.echo(f"\n{error_message}", err=True)
+            click.echo("\nYour AWS user needs additional permissions.", err=True)
+            click.echo("Contact your AWS administrator.", err=True)
+
+        elif error_code == 'InvalidRegion':
+            click.echo("❌ Invalid AWS region", err=True)
+            click.echo("\nValid regions: us-east-1, eu-west-1, eu-west-3, etc.", err=True)
+
+        else:
+            click.echo(f"❌ AWS Error: {error_code}", err=True)
+            if error_message:
+                click.echo(f"\n{error_message}", err=True)
+            click.echo(f"\nFor help: https://docs.complio.tech/errors", err=True)
+
+        sys.exit(1)
+
+    else:
+        # Unknown error - show technical message but add help
+        click.echo(f"❌ Unexpected error: {str(error)}", err=True)
+        click.echo(f"\nFor help: https://docs.complio.tech/troubleshooting", err=True)
+        click.echo(f"Support: support@complio.tech", err=True)
+        sys.exit(1)
+
+
+def validate_region_format(region: str) -> bool:
+    """Validate AWS region format.
+
+    Args:
+        region: Region string to validate
+
+    Returns:
+        True if valid format, False otherwise
+
+    Example:
+        >>> validate_region_format("us-east-1")
+        True
+        >>> validate_region_format("invalid")
+        False
+    """
+    import re
+    # AWS region format: 2 letters, dash, direction/location, dash, number
+    # Examples: us-east-1, eu-west-3, ap-southeast-2
+    pattern = r'^[a-z]{2}-[a-z]+-\d+$'
+    return bool(re.match(pattern, region))
+
+
+def validate_profile_exists(profile: str) -> bool:
+    """Check if AWS profile exists in credentials file.
+
+    Args:
+        profile: Profile name to check
+
+    Returns:
+        True if profile exists, False otherwise
+
+    Example:
+        >>> validate_profile_exists("default")
+        True
+    """
+    if profile == "default":
+        return True  # Default profile is implicit
+
+    try:
+        config = configparser.ConfigParser()
+        config.read(os.path.expanduser('~/.aws/credentials'))
+        return profile in config.sections()
+    except Exception:
+        return True  # If can't read file, let boto3 handle it

complio/utils/exceptions.py

@@ -0,0 +1,151 @@
+"""
+Custom exceptions for Complio.
+
+This module defines all custom exceptions used throughout the application.
+All exceptions inherit from ComplioError for easy catching of all application errors.
+"""
+
+from typing import Optional
+
+
+class ComplioError(Exception):
+    """Base exception for all Complio errors.
+
+    All custom exceptions should inherit from this class to allow
+    catching all application-specific errors.
+    """
+
+    def __init__(self, message: str, details: Optional[dict[str, str]] = None) -> None:
+        """Initialize ComplioError.
+
+        Args:
+            message: Human-readable error message
+            details: Optional dictionary with additional error context
+        """
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+
+class CryptoError(ComplioError):
+    """Base exception for cryptography-related errors."""
+    pass
+
+
+class EncryptionError(CryptoError):
+    """Raised when encryption operations fail.
+
+    Examples:
+        - Encryption algorithm failure
+        - Invalid encryption key
+        - Corrupted data during encryption
+    """
+    pass
+
+
+class DecryptionError(CryptoError):
+    """Raised when decryption operations fail.
+
+    Examples:
+        - Invalid decryption key (wrong password)
+        - Corrupted encrypted data
+        - Tampered encrypted file
+        - Invalid token format
+    """
+    pass
+
+
+class CredentialError(ComplioError):
+    """Base exception for credential-related errors."""
+    pass
+
+
+class InvalidCredentialsError(CredentialError):
+    """Raised when AWS credentials are invalid or malformed.
+
+    Examples:
+        - Empty access key or secret key
+        - Invalid access key format (not AKIA...)
+        - Credentials that don't match AWS format requirements
+    """
+    pass
+
+
+class CredentialStorageError(CredentialError):
+    """Raised when credential storage operations fail.
+
+    Examples:
+        - Unable to create credentials directory
+        - Insufficient permissions to write credentials file
+        - Disk full when saving credentials
+    """
+    pass
+
+
+class CredentialNotFoundError(CredentialError):
+    """Raised when attempting to load non-existent credentials.
+
+    Examples:
+        - Credentials file doesn't exist
+        - Profile name not found in credentials file
+    """
+    pass
+
+
+class InvalidPasswordError(CredentialError):
+    """Raised when password validation fails.
+
+    Examples:
+        - Password too short (< 8 characters)
+        - Password doesn't meet complexity requirements
+        - Wrong password during decryption
+    """
+    pass
+
+
+class ValidationError(ComplioError):
+    """Raised when input validation fails.
+
+    Examples:
+        - Invalid AWS region
+        - Malformed account ID
+        - Invalid file path
+    """
+    pass
+
+
+class AWSError(ComplioError):
+    """Base exception for AWS-related errors."""
+    pass
+
+
+class AWSCredentialsError(AWSError):
+    """Raised when AWS API rejects credentials.
+
+    Examples:
+        - Invalid access key or secret key
+        - Expired temporary credentials
+        - Insufficient IAM permissions
+    """
+    pass
+
+
+class AWSConnectionError(AWSError):
+    """Raised when unable to connect to AWS API.
+
+    Examples:
+        - Network timeout
+        - DNS resolution failure
+        - AWS service unavailable
+    """
+    pass
+
+
+class InvalidRegionError(AWSError):
+    """Raised when AWS region is invalid.
+
+    Examples:
+        - Non-existent region name
+        - Region not enabled for account
+    """
+    pass