complio 0.1.1__py3-none-any.whl

complio/config/settings.py

@@ -0,0 +1,333 @@
+"""
+Configuration management for Complio.
+
+This module provides centralized configuration using Pydantic Settings.
+Supports environment variables, defaults, and validation.
+
+Configuration Sources (priority order):
+1. Environment variables (COMPLIO_*)
+2. Configuration file (~/.complio/config.yaml)
+3. Default values
+
+Example:
+    >>> from complio.config.settings import get_settings
+    >>> settings = get_settings()
+    >>> print(settings.default_region)
+    'us-east-1'
+"""
+
+from pathlib import Path
+from typing import List, Optional
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# ============================================================================
+# CONSTANTS
+# ============================================================================
+
+# Application version
+VERSION = "0.1.0"
+
+# Default configuration directory
+DEFAULT_CONFIG_DIR = Path.home() / ".complio"
+DEFAULT_CONFIG_FILE = DEFAULT_CONFIG_DIR / "config.yaml"
+DEFAULT_CREDENTIALS_FILE = DEFAULT_CONFIG_DIR / "credentials.enc"
+DEFAULT_LOG_DIR = DEFAULT_CONFIG_DIR / "logs"
+DEFAULT_REPORT_DIR = DEFAULT_CONFIG_DIR / "reports"
+
+# Valid AWS regions (as of 2024)
+VALID_AWS_REGIONS: List[str] = [
+    "us-east-1",
+    "us-east-2",
+    "us-west-1",
+    "us-west-2",
+    "af-south-1",
+    "ap-east-1",
+    "ap-south-1",
+    "ap-southeast-1",
+    "ap-southeast-2",
+    "ap-southeast-3",
+    "ap-northeast-1",
+    "ap-northeast-2",
+    "ap-northeast-3",
+    "ca-central-1",
+    "eu-central-1",
+    "eu-west-1",
+    "eu-west-2",
+    "eu-west-3",
+    "eu-south-1",
+    "eu-north-1",
+    "me-south-1",
+    "sa-east-1",
+]
+
+# Valid output formats
+VALID_OUTPUT_FORMATS: List[str] = ["json", "markdown", "pdf", "html"]
+
+# Valid log levels
+VALID_LOG_LEVELS: List[str] = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+# ============================================================================
+# SETTINGS MODEL
+# ============================================================================
+
+
+class ComplioSettings(BaseSettings):
+    """Application settings with validation and defaults.
+
+    Settings can be configured via:
+    - Environment variables (COMPLIO_DEFAULT_REGION, etc.)
+    - Configuration file (~/.complio/config.yaml)
+    - Default values (defined here)
+
+    Attributes:
+        default_region: Default AWS region for scans
+        default_profile: Default credential profile name
+        default_output_format: Default report format
+        log_level: Logging level
+        log_to_file: Enable file logging
+        log_dir: Directory for log files
+        log_max_bytes: Max log file size before rotation
+        log_backup_count: Number of backup log files to keep
+        config_dir: Configuration directory path
+        credentials_file: Path to encrypted credentials
+        report_dir: Directory for generated reports
+        aws_timeout: Timeout for AWS API calls (seconds)
+        max_concurrent_tests: Maximum concurrent compliance tests
+        enable_colors: Enable colored terminal output
+        verbose: Enable verbose output
+
+    Example:
+        >>> settings = ComplioSettings()
+        >>> print(settings.default_region)
+        'us-east-1'
+
+        >>> # Override with environment variable
+        >>> import os
+        >>> os.environ['COMPLIO_DEFAULT_REGION'] = 'eu-west-1'
+        >>> settings = ComplioSettings()
+        >>> print(settings.default_region)
+        'eu-west-1'
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="COMPLIO_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+    )
+
+    # Application Version
+    VERSION: str = Field(
+        default=VERSION,
+        description="Application version",
+    )
+
+    # AWS Configuration
+    default_region: str = Field(
+        default="us-east-1",
+        description="Default AWS region for compliance scans",
+    )
+    default_profile: str = Field(
+        default="default",
+        description="Default credential profile name",
+    )
+    aws_timeout: int = Field(
+        default=30,
+        ge=1,
+        le=300,
+        description="Timeout for AWS API calls in seconds",
+    )
+
+    # Output Configuration
+    default_output_format: str = Field(
+        default="json",
+        description="Default format for compliance reports",
+    )
+    enable_colors: bool = Field(
+        default=True,
+        description="Enable colored terminal output",
+    )
+    verbose: bool = Field(
+        default=False,
+        description="Enable verbose output",
+    )
+
+    # Logging Configuration
+    log_level: str = Field(
+        default="INFO",
+        description="Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
+    )
+    log_to_file: bool = Field(
+        default=True,
+        description="Enable logging to file",
+    )
+    log_dir: Path = Field(
+        default=DEFAULT_LOG_DIR,
+        description="Directory for log files",
+    )
+    log_max_bytes: int = Field(
+        default=10_000_000,  # 10 MB
+        ge=1_000_000,  # Min 1 MB
+        le=100_000_000,  # Max 100 MB
+        description="Maximum log file size before rotation",
+    )
+    log_backup_count: int = Field(
+        default=5,
+        ge=1,
+        le=20,
+        description="Number of backup log files to keep",
+    )
+
+    # Directory Configuration
+    config_dir: Path = Field(
+        default=DEFAULT_CONFIG_DIR,
+        description="Configuration directory path",
+    )
+    credentials_file: Path = Field(
+        default=DEFAULT_CREDENTIALS_FILE,
+        description="Path to encrypted credentials file",
+    )
+    report_dir: Path = Field(
+        default=DEFAULT_REPORT_DIR,
+        description="Directory for generated reports",
+    )
+
+    # Test Execution Configuration
+    max_concurrent_tests: int = Field(
+        default=10,
+        ge=1,
+        le=50,
+        description="Maximum number of concurrent compliance tests",
+    )
+
+    # Validation
+    @field_validator("default_region")
+    @classmethod
+    def validate_region(cls, v: str) -> str:
+        """Validate AWS region.
+
+        Args:
+            v: Region string to validate
+
+        Returns:
+            Validated region string
+
+        Raises:
+            ValueError: If region is invalid
+        """
+        if v not in VALID_AWS_REGIONS:
+            raise ValueError(
+                f"Invalid AWS region: {v}. Must be one of: {', '.join(VALID_AWS_REGIONS)}"
+            )
+        return v
+
+    @field_validator("default_output_format")
+    @classmethod
+    def validate_output_format(cls, v: str) -> str:
+        """Validate output format.
+
+        Args:
+            v: Format string to validate
+
+        Returns:
+            Validated format string (lowercase)
+
+        Raises:
+            ValueError: If format is invalid
+        """
+        v_lower = v.lower()
+        if v_lower not in VALID_OUTPUT_FORMATS:
+            raise ValueError(
+                f"Invalid output format: {v}. Must be one of: {', '.join(VALID_OUTPUT_FORMATS)}"
+            )
+        return v_lower
+
+    @field_validator("log_level")
+    @classmethod
+    def validate_log_level(cls, v: str) -> str:
+        """Validate log level.
+
+        Args:
+            v: Log level string to validate
+
+        Returns:
+            Validated log level string (uppercase)
+
+        Raises:
+            ValueError: If log level is invalid
+        """
+        v_upper = v.upper()
+        if v_upper not in VALID_LOG_LEVELS:
+            raise ValueError(
+                f"Invalid log level: {v}. Must be one of: {', '.join(VALID_LOG_LEVELS)}"
+            )
+        return v_upper
+
+    def ensure_directories(self) -> None:
+        """Create required directories if they don't exist.
+
+        Creates:
+        - Configuration directory
+        - Log directory
+        - Report directory
+
+        Sets appropriate permissions (700 for directories).
+
+        Example:
+            >>> settings = ComplioSettings()
+            >>> settings.ensure_directories()
+            >>> assert settings.log_dir.exists()
+        """
+        for directory in [self.config_dir, self.log_dir, self.report_dir]:
+            directory.mkdir(parents=True, exist_ok=True)
+            # Set directory permissions to 700 (rwx------)
+            directory.chmod(0o700)
+
+
+# ============================================================================
+# SINGLETON SETTINGS INSTANCE
+# ============================================================================
+
+_settings: Optional[ComplioSettings] = None
+
+
+def get_settings() -> ComplioSettings:
+    """Get application settings singleton.
+
+    Returns cached settings instance if available, otherwise creates new one.
+    This ensures consistent settings across the application.
+
+    Returns:
+        ComplioSettings instance
+
+    Example:
+        >>> settings = get_settings()
+        >>> print(settings.default_region)
+        'us-east-1'
+
+        >>> # Subsequent calls return same instance
+        >>> settings2 = get_settings()
+        >>> assert settings is settings2
+    """
+    global _settings
+    if _settings is None:
+        _settings = ComplioSettings()
+        # Ensure required directories exist
+        _settings.ensure_directories()
+    return _settings
+
+
+def reset_settings() -> None:
+    """Reset settings singleton.
+
+    Useful for testing to force re-initialization of settings.
+
+    Example:
+        >>> reset_settings()
+        >>> settings = get_settings()  # Creates new instance
+    """
+    global _settings
+    _settings = None

complio/connectors/__init__.py

@@ -0,0 +1,9 @@
+"""Cloud connector modules for Complio."""
+
+from complio.connectors.base import CloudConnector
+from complio.connectors.aws.client import AWSConnector
+
+__all__ = [
+    "CloudConnector",
+    "AWSConnector",
+]

complio/connectors/aws/client.py

@@ -0,0 +1,342 @@
+"""
+AWS connector using boto3.
+
+This module provides AWS connectivity using standard AWS credentials (from
+~/.aws/credentials, environment variables, or IAM roles) via boto3 SDK.
+
+Security Features:
+    - Uses boto3's standard credential chain
+    - Reads from ~/.aws/credentials (same as AWS CLI)
+    - Supports environment variables and IAM roles
+    - Optional encrypted credential storage (legacy mode)
+    - STS validation before use
+    - Configurable timeouts
+    - Automatic retry with exponential backoff
+    - No credential logging
+
+Example:
+    >>> from complio.connectors.aws.client import AWSConnector
+    >>> # Uses credentials from ~/.aws/credentials (no password needed)
+    >>> connector = AWSConnector(profile_name="default", region="us-east-1")
+    >>> connector.connect()
+    >>> # Validate credentials
+    >>> result = connector.validate_credentials()
+    >>> print(result["account_id"])
+    '123456789012'
+    >>> # Get AWS clients
+    >>> s3 = connector.get_client("s3")
+    >>> ec2 = connector.get_client("ec2")
+"""
+
+from typing import Any, Dict, Optional
+
+import boto3
+from boto3.session import Session
+from botocore.config import Config
+from botocore.exceptions import ClientError, NoCredentialsError, PartialCredentialsError
+
+from complio.config.settings import get_settings
+from complio.connectors.base import CloudConnector
+from complio.utils.exceptions import AWSConnectionError, AWSCredentialsError
+from complio.utils.logger import get_logger, log_aws_api_call
+
+logger = get_logger(__name__)
+
+
+class AWSConnector(CloudConnector):
+    """AWS cloud connector using boto3.
+
+    Manages AWS connections using standard AWS credentials (from ~/.aws/credentials,
+    environment variables, or IAM roles). Optionally supports encrypted credential
+    storage for legacy compatibility.
+
+    Attributes:
+        profile_name: Credential profile name (from ~/.aws/credentials)
+        region: AWS region
+        password: Optional password for encrypted credentials (legacy mode)
+        session: Boto3 session (created on connect)
+        connected: Connection status
+
+    Example:
+        >>> # Standard usage (reads from ~/.aws/credentials)
+        >>> connector = AWSConnector("default", "us-east-1")
+        >>> connector.connect()
+        >>> s3_client = connector.get_client("s3")
+        >>> buckets = s3_client.list_buckets()
+    """
+
+    def __init__(
+        self,
+        profile_name: str,
+        region: Optional[str] = None,
+    ) -> None:
+        """Initialize AWS connector.
+
+        Args:
+            profile_name: Name of credential profile (from ~/.aws/credentials)
+            region: AWS region (defaults to settings.default_region)
+
+        Example:
+            >>> connector = AWSConnector("default", "us-east-1")
+            >>> connector.connect()
+        """
+        settings = get_settings()
+        region = region or settings.default_region
+
+        super().__init__(profile_name=profile_name, region=region)
+
+        self.session: Optional[Session] = None
+        self._clients: Dict[str, Any] = {}
+        self._account_id: Optional[str] = None
+        self._user_arn: Optional[str] = None
+
+    def connect(self) -> bool:
+        """Connect to AWS using standard AWS credentials.
+
+        Uses boto3's default credential chain (reads from ~/.aws/credentials, environment
+        variables, EC2 instance metadata, etc). Falls back to encrypted credentials if
+        password is explicitly provided.
+
+        Returns:
+            True if connection successful
+
+        Raises:
+            AWSCredentialsError: If credentials cannot be loaded or are invalid
+            AWSConnectionError: If connection fails
+
+        Example:
+            >>> connector.connect()
+            True
+        """
+        logger.info("connecting_to_aws", profile=self.profile_name, region=self.region)
+
+        try:
+            # Use standard AWS credential chain
+            # This reads from:
+            # 1. ~/.aws/credentials (AWS config file)
+            # 2. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+            # 3. IAM role (for EC2 instances)
+            # 4. Other boto3 credential providers
+            logger.debug("using_standard_aws_credentials", profile=self.profile_name)
+
+            # Create boto3 session using profile from ~/.aws/credentials
+            self.session = boto3.Session(
+                profile_name=self.profile_name if self.profile_name != "default" else None,
+                region_name=self.region
+            )
+
+            self.connected = True
+            logger.info("aws_connection_established", profile=self.profile_name, region=self.region)
+
+            return True
+
+        except AWSCredentialsError:
+            raise
+        except Exception as e:
+            logger.error("aws_connection_failed", error=str(e), profile=self.profile_name)
+            raise AWSConnectionError(
+                f"Failed to connect to AWS: {str(e)}",
+                details={"profile": self.profile_name, "region": self.region}
+            ) from e
+
+    def disconnect(self) -> None:
+        """Disconnect from AWS.
+
+        Clears session and cached clients.
+
+        Example:
+            >>> connector.disconnect()
+        """
+        self.session = None
+        self._clients = {}
+        self.connected = False
+        logger.info("aws_disconnected", profile=self.profile_name)
+
+    def get_client(self, service_name: str, region: Optional[str] = None) -> Any:
+        """Get boto3 client for AWS service.
+
+        Creates and caches boto3 clients with proper configuration.
+
+        Args:
+            service_name: AWS service name (e.g., 's3', 'ec2', 'iam')
+            region: AWS region (uses connector region if not specified)
+
+        Returns:
+            Boto3 client for the specified service
+
+        Raises:
+            AWSConnectionError: If not connected
+
+        Example:
+            >>> s3 = connector.get_client("s3")
+            >>> buckets = s3.list_buckets()
+        """
+        if not self.connected or not self.session:
+            raise AWSConnectionError(
+                "Not connected to AWS. Call connect() first.",
+                details={"profile": self.profile_name}
+            )
+
+        region = region or self.region
+        cache_key = f"{service_name}:{region}"
+
+        # Return cached client if available
+        if cache_key in self._clients:
+            return self._clients[cache_key]
+
+        # Create new client with configuration
+        settings = get_settings()
+
+        client_config = Config(
+            region_name=region,
+            retries={
+                "max_attempts": 3,
+                "mode": "adaptive"
+            },
+            connect_timeout=settings.aws_timeout,
+            read_timeout=settings.aws_timeout,
+        )
+
+        try:
+            client = self.session.client(service_name, config=client_config)
+            self._clients[cache_key] = client
+
+            logger.debug("aws_client_created", service=service_name, region=region)
+
+            return client
+
+        except Exception as e:
+            logger.error("aws_client_creation_failed", service=service_name, error=str(e))
+            raise AWSConnectionError(
+                f"Failed to create {service_name} client: {str(e)}",
+                details={"service": service_name, "region": region}
+            ) from e
+
+    def validate_credentials(self) -> Dict[str, Any]:
+        """Validate AWS credentials using STS GetCallerIdentity.
+
+        Returns:
+            Dictionary with validation result:
+                {
+                    "valid": True,
+                    "account_id": "123456789012",
+                    "user_arn": "arn:aws:iam::123456789012:user/admin",
+                    "user_id": "AIDAI..."
+                }
+
+        Raises:
+            AWSCredentialsError: If credentials are invalid
+            AWSConnectionError: If not connected
+
+        Example:
+            >>> result = connector.validate_credentials()
+            >>> print(f"Connected to account: {result['account_id']}")
+        """
+        if not self.connected:
+            raise AWSConnectionError(
+                "Not connected to AWS. Call connect() first.",
+                details={"profile": self.profile_name}
+            )
+
+        logger.info("validating_aws_credentials", profile=self.profile_name)
+
+        try:
+            sts = self.get_client("sts")
+            log_aws_api_call(logger, "sts", "get_caller_identity", self.region)
+
+            response = sts.get_caller_identity()
+
+            result = {
+                "valid": True,
+                "account_id": response["Account"],
+                "user_arn": response["Arn"],
+                "user_id": response["UserId"],
+            }
+
+            # Cache for future use
+            self._account_id = result["account_id"]
+            self._user_arn = result["user_arn"]
+
+            logger.info(
+                "aws_credentials_valid",
+                account_id=result["account_id"],
+                user_id=result["user_id"]
+            )
+
+            return result
+
+        except (ClientError, NoCredentialsError, PartialCredentialsError) as e:
+            logger.error("aws_credential_validation_failed", error=str(e))
+            raise AWSCredentialsError(
+                f"AWS credential validation failed: {str(e)}",
+                details={"profile": self.profile_name}
+            ) from e
+
+    def test_connection(self) -> bool:
+        """Test if AWS connection is working.
+
+        Performs a simple STS call to verify connectivity.
+
+        Returns:
+            True if connection is healthy, False otherwise
+
+        Example:
+            >>> if connector.test_connection():
+            ...     print("AWS connection is healthy")
+        """
+        try:
+            self.validate_credentials()
+            return True
+        except Exception as e:
+            logger.warning("aws_connection_test_failed", error=str(e))
+            return False
+
+    def get_account_id(self) -> str:
+        """Get AWS account ID.
+
+        Returns:
+            AWS account ID
+
+        Raises:
+            AWSConnectionError: If credentials haven't been validated
+
+        Example:
+            >>> account_id = connector.get_account_id()
+            >>> print(account_id)
+            '123456789012'
+        """
+        if not self._account_id:
+            # Validate to get account ID
+            self.validate_credentials()
+
+        if not self._account_id:
+            raise AWSConnectionError(
+                "Account ID not available. Validate credentials first.",
+                details={"profile": self.profile_name}
+            )
+
+        return self._account_id
+
+    def list_regions(self, service: str = "ec2") -> list[str]:
+        """List available AWS regions for a service.
+
+        Args:
+            service: AWS service name (default: ec2)
+
+        Returns:
+            List of region names
+
+        Example:
+            >>> regions = connector.list_regions()
+            >>> print(regions)
+            ['us-east-1', 'us-west-2', 'eu-west-1', ...]
+        """
+        try:
+            client = self.get_client(service)
+            regions = client.describe_regions()["Regions"]
+            return [region["RegionName"] for region in regions]
+        except Exception as e:
+            logger.warning("failed_to_list_regions", error=str(e))
+            # Return default list if API call fails
+            from complio.config.settings import VALID_AWS_REGIONS
+            return VALID_AWS_REGIONS