truthound 1.0.8__py3-none-any.whl

truthound/plugins/security/exceptions.py

@@ -0,0 +1,332 @@
+"""Security-related exceptions for plugin system.
+
+This module defines a hierarchy of exceptions for security operations:
+- SandboxError: Errors during sandbox execution
+- SignatureError: Errors during signing/verification
+- CertificateError: Certificate management errors
+
+All exceptions include contextual information for debugging.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+class SecurityError(Exception):
+    """Base exception for all plugin security errors.
+
+    Attributes:
+        message: Error message
+        plugin_id: ID of the affected plugin (if applicable)
+        details: Additional error details
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        self.message = message
+        self.plugin_id = plugin_id
+        self.details = details or {}
+        super().__init__(message)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert exception to dictionary for serialization."""
+        return {
+            "error_type": self.__class__.__name__,
+            "message": self.message,
+            "plugin_id": self.plugin_id,
+            "details": self.details,
+        }
+
+
+# =============================================================================
+# Sandbox Exceptions
+# =============================================================================
+
+
+class SandboxError(SecurityError):
+    """Base exception for sandbox-related errors.
+
+    Raised when sandbox creation or execution fails.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        sandbox_id: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        self.sandbox_id = sandbox_id
+        super().__init__(message, plugin_id, details)
+
+
+class SandboxTimeoutError(SandboxError):
+    """Raised when sandbox execution times out.
+
+    Attributes:
+        timeout_seconds: The timeout that was exceeded
+        execution_time: Actual execution time before timeout
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        sandbox_id: str | None = None,
+        timeout_seconds: float = 0.0,
+        execution_time: float = 0.0,
+    ):
+        details = {
+            "timeout_seconds": timeout_seconds,
+            "execution_time": execution_time,
+        }
+        super().__init__(message, plugin_id, sandbox_id, details)
+        self.timeout_seconds = timeout_seconds
+        self.execution_time = execution_time
+
+
+class SandboxResourceError(SandboxError):
+    """Raised when sandbox resource limits are exceeded.
+
+    Attributes:
+        resource_type: Type of resource exceeded (memory, cpu, etc.)
+        limit: The limit that was exceeded
+        actual: Actual value when limit was exceeded
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        sandbox_id: str | None = None,
+        resource_type: str = "",
+        limit: float = 0.0,
+        actual: float = 0.0,
+    ):
+        details = {
+            "resource_type": resource_type,
+            "limit": limit,
+            "actual": actual,
+        }
+        super().__init__(message, plugin_id, sandbox_id, details)
+        self.resource_type = resource_type
+        self.limit = limit
+        self.actual = actual
+
+
+class SandboxSecurityViolation(SandboxError):
+    """Raised when plugin code violates security policy.
+
+    Attributes:
+        violation_type: Type of violation (import, syscall, network, etc.)
+        attempted_action: The action that was blocked
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        sandbox_id: str | None = None,
+        violation_type: str = "",
+        attempted_action: str = "",
+    ):
+        details = {
+            "violation_type": violation_type,
+            "attempted_action": attempted_action,
+        }
+        super().__init__(message, plugin_id, sandbox_id, details)
+        self.violation_type = violation_type
+        self.attempted_action = attempted_action
+
+
+# =============================================================================
+# Signature Exceptions
+# =============================================================================
+
+
+class SignatureError(SecurityError):
+    """Base exception for signature-related errors.
+
+    Raised when signing or verification fails.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        signer_id: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        self.signer_id = signer_id
+        super().__init__(message, plugin_id, details)
+
+
+class SignatureExpiredError(SignatureError):
+    """Raised when a signature has expired.
+
+    Attributes:
+        expired_at: When the signature expired
+        signed_at: When the signature was created
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        signer_id: str | None = None,
+        expired_at: datetime | None = None,
+        signed_at: datetime | None = None,
+    ):
+        details = {
+            "expired_at": expired_at.isoformat() if expired_at else None,
+            "signed_at": signed_at.isoformat() if signed_at else None,
+        }
+        super().__init__(message, plugin_id, signer_id, details)
+        self.expired_at = expired_at
+        self.signed_at = signed_at
+
+
+class SignatureTamperError(SignatureError):
+    """Raised when code tampering is detected.
+
+    Attributes:
+        expected_hash: Hash at signing time
+        actual_hash: Current hash
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        signer_id: str | None = None,
+        expected_hash: str = "",
+        actual_hash: str = "",
+    ):
+        details = {
+            "expected_hash": expected_hash,
+            "actual_hash": actual_hash,
+        }
+        super().__init__(message, plugin_id, signer_id, details)
+        self.expected_hash = expected_hash
+        self.actual_hash = actual_hash
+
+
+class UntrustedSignerError(SignatureError):
+    """Raised when signer is not trusted.
+
+    Attributes:
+        trust_level: Current trust level of the signer
+        required_trust_level: Required trust level
+    """
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        signer_id: str | None = None,
+        trust_level: str = "unknown",
+        required_trust_level: str = "trusted",
+    ):
+        details = {
+            "trust_level": trust_level,
+            "required_trust_level": required_trust_level,
+        }
+        super().__init__(message, plugin_id, signer_id, details)
+        self.trust_level = trust_level
+        self.required_trust_level = required_trust_level
+
+
+class InvalidSignatureError(SignatureError):
+    """Raised when signature is cryptographically invalid."""
+
+    def __init__(
+        self,
+        message: str,
+        plugin_id: str | None = None,
+        signer_id: str | None = None,
+        algorithm: str = "",
+    ):
+        details = {"algorithm": algorithm}
+        super().__init__(message, plugin_id, signer_id, details)
+        self.algorithm = algorithm
+
+
+# =============================================================================
+# Certificate Exceptions
+# =============================================================================
+
+
+class CertificateError(SecurityError):
+    """Base exception for certificate-related errors.
+
+    Raised when certificate operations fail.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        cert_id: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        self.cert_id = cert_id
+        super().__init__(message, details=details)
+
+
+class CertificateExpiredError(CertificateError):
+    """Raised when a certificate has expired."""
+
+    def __init__(
+        self,
+        message: str,
+        cert_id: str | None = None,
+        expired_at: datetime | None = None,
+    ):
+        details = {"expired_at": expired_at.isoformat() if expired_at else None}
+        super().__init__(message, cert_id, details)
+        self.expired_at = expired_at
+
+
+class CertificateRevokedError(CertificateError):
+    """Raised when a certificate has been revoked."""
+
+    def __init__(
+        self,
+        message: str,
+        cert_id: str | None = None,
+        revoked_at: datetime | None = None,
+        reason: str = "",
+    ):
+        details = {
+            "revoked_at": revoked_at.isoformat() if revoked_at else None,
+            "reason": reason,
+        }
+        super().__init__(message, cert_id, details)
+        self.revoked_at = revoked_at
+        self.reason = reason
+
+
+class CertificateNotFoundError(CertificateError):
+    """Raised when a certificate is not found in trust store."""
+
+    pass
+
+
+class InvalidCertificateError(CertificateError):
+    """Raised when a certificate is malformed or invalid."""
+
+    def __init__(
+        self,
+        message: str,
+        cert_id: str | None = None,
+        parse_error: str = "",
+    ):
+        details = {"parse_error": parse_error}
+        super().__init__(message, cert_id, details)
+        self.parse_error = parse_error

truthound/plugins/security/policies.py

@@ -0,0 +1,348 @@
+"""Security policy presets and factory functions.
+
+This module provides pre-configured security policies for common use cases
+and a factory for creating custom policies.
+
+Usage:
+    >>> from truthound.plugins.security.policies import (
+    ...     SecurityPolicyPresets,
+    ...     create_policy,
+    ... )
+    >>>
+    >>> # Use a preset
+    >>> policy = SecurityPolicyPresets.ENTERPRISE
+    >>>
+    >>> # Or create custom policy
+    >>> policy = create_policy(
+    ...     isolation_level="container",
+    ...     allow_network=False,
+    ...     required_signatures=2,
+    ... )
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from truthound.plugins.security.protocols import (
+    IsolationLevel,
+    ResourceLimits,
+    SecurityPolicy,
+)
+
+
+class SecurityPolicyPresets(Enum):
+    """Pre-configured security policy presets.
+
+    Available presets:
+        DEVELOPMENT: No restrictions, for local development
+        TESTING: Minimal restrictions, for testing
+        STANDARD: Balanced security for trusted plugins
+        ENTERPRISE: High security for production
+        STRICT: Maximum security for untrusted code
+        AIRGAPPED: No network, maximum isolation
+    """
+
+    DEVELOPMENT = "development"
+    TESTING = "testing"
+    STANDARD = "standard"
+    ENTERPRISE = "enterprise"
+    STRICT = "strict"
+    AIRGAPPED = "airgapped"
+
+    def to_policy(self) -> SecurityPolicy:
+        """Convert preset to SecurityPolicy instance."""
+        return _PRESET_POLICIES[self]
+
+
+# Policy definitions for each preset
+_PRESET_POLICIES: dict[SecurityPolicyPresets, SecurityPolicy] = {
+    SecurityPolicyPresets.DEVELOPMENT: SecurityPolicy(
+        isolation_level=IsolationLevel.NONE,
+        resource_limits=ResourceLimits(
+            max_memory_mb=4096,
+            max_cpu_percent=100.0,
+            max_execution_time_sec=600.0,
+            max_file_descriptors=10000,
+        ),
+        allow_network=True,
+        allow_subprocess=True,
+        allow_file_write=True,
+        allowed_modules=(),  # All allowed
+        blocked_modules=(),  # None blocked
+        required_signatures=0,
+        require_trusted_signer=False,
+        signature_max_age_days=0,  # No limit
+    ),
+    SecurityPolicyPresets.TESTING: SecurityPolicy(
+        isolation_level=IsolationLevel.NONE,
+        resource_limits=ResourceLimits(
+            max_memory_mb=2048,
+            max_cpu_percent=100.0,
+            max_execution_time_sec=120.0,
+            max_file_descriptors=1000,
+        ),
+        allow_network=True,
+        allow_subprocess=False,
+        allow_file_write=True,
+        allowed_modules=(),  # All allowed
+        blocked_modules=("ctypes", "cffi"),  # Only unsafe FFI blocked
+        required_signatures=0,
+        require_trusted_signer=False,
+        signature_max_age_days=0,
+    ),
+    SecurityPolicyPresets.STANDARD: SecurityPolicy(
+        isolation_level=IsolationLevel.PROCESS,
+        resource_limits=ResourceLimits.standard(),
+        allow_network=False,
+        allow_subprocess=False,
+        allow_file_write=False,
+        required_signatures=1,
+        require_trusted_signer=False,
+        signature_max_age_days=365,
+    ),
+    SecurityPolicyPresets.ENTERPRISE: SecurityPolicy(
+        isolation_level=IsolationLevel.PROCESS,
+        resource_limits=ResourceLimits(
+            max_memory_mb=1024,
+            max_cpu_percent=80.0,
+            max_execution_time_sec=60.0,
+            max_file_descriptors=100,
+        ),
+        allow_network=False,
+        allow_subprocess=False,
+        allow_file_write=False,
+        required_signatures=1,
+        require_trusted_signer=True,
+        signature_max_age_days=180,
+    ),
+    SecurityPolicyPresets.STRICT: SecurityPolicy(
+        isolation_level=IsolationLevel.CONTAINER,
+        resource_limits=ResourceLimits.minimal(),
+        allow_network=False,
+        allow_subprocess=False,
+        allow_file_write=False,
+        required_signatures=2,
+        require_trusted_signer=True,
+        signature_max_age_days=90,
+    ),
+    SecurityPolicyPresets.AIRGAPPED: SecurityPolicy(
+        isolation_level=IsolationLevel.CONTAINER,
+        resource_limits=ResourceLimits(
+            max_memory_mb=256,
+            max_cpu_percent=50.0,
+            max_execution_time_sec=30.0,
+            max_file_descriptors=10,
+            denied_syscalls=(
+                "fork",
+                "vfork",
+                "clone",
+                "execve",
+                "execveat",
+                "socket",
+                "connect",
+                "accept",
+                "bind",
+                "listen",
+            ),
+        ),
+        allow_network=False,
+        allow_subprocess=False,
+        allow_file_write=False,
+        blocked_modules=(
+            "os",
+            "subprocess",
+            "shutil",
+            "socket",
+            "urllib",
+            "requests",
+            "http",
+            "ftplib",
+            "smtplib",
+            "telnetlib",
+            "ctypes",
+            "cffi",
+            "multiprocessing",
+            "threading",
+            "asyncio",
+            "sys",
+            "importlib",
+            "builtins",
+            "code",
+            "codeop",
+            "pickle",
+            "marshal",
+            "shelve",
+            "dbm",
+            "sqlite3",
+            "ssl",
+            "tempfile",
+            "pty",
+            "tty",
+            "fcntl",
+            "mmap",
+            "signal",
+        ),
+        required_signatures=2,
+        require_trusted_signer=True,
+        signature_max_age_days=30,
+    ),
+}
+
+
+def create_policy(
+    preset: str | SecurityPolicyPresets | None = None,
+    isolation_level: str | IsolationLevel | None = None,
+    max_memory_mb: int | None = None,
+    max_cpu_percent: float | None = None,
+    max_execution_time_sec: float | None = None,
+    allow_network: bool | None = None,
+    allow_subprocess: bool | None = None,
+    allow_file_write: bool | None = None,
+    allowed_modules: tuple[str, ...] | list[str] | None = None,
+    blocked_modules: tuple[str, ...] | list[str] | None = None,
+    required_signatures: int | None = None,
+    require_trusted_signer: bool | None = None,
+    signature_max_age_days: int | None = None,
+) -> SecurityPolicy:
+    """Create a security policy with optional customizations.
+
+    Starts from a preset (or STANDARD if not specified) and applies
+    any provided overrides.
+
+    Args:
+        preset: Base preset to start from
+        isolation_level: Override isolation level
+        max_memory_mb: Override memory limit
+        max_cpu_percent: Override CPU limit
+        max_execution_time_sec: Override time limit
+        allow_network: Override network access
+        allow_subprocess: Override subprocess access
+        allow_file_write: Override file write access
+        allowed_modules: Override allowed modules
+        blocked_modules: Override blocked modules
+        required_signatures: Override signature requirement
+        require_trusted_signer: Override trusted signer requirement
+        signature_max_age_days: Override signature age limit
+
+    Returns:
+        Configured SecurityPolicy
+
+    Example:
+        >>> # Start from enterprise preset but allow network
+        >>> policy = create_policy(
+        ...     preset="enterprise",
+        ...     allow_network=True,
+        ... )
+    """
+    # Get base policy
+    if preset is None:
+        base = SecurityPolicy.standard()
+    elif isinstance(preset, SecurityPolicyPresets):
+        base = preset.to_policy()
+    elif isinstance(preset, str):
+        try:
+            preset_enum = SecurityPolicyPresets(preset.lower())
+            base = preset_enum.to_policy()
+        except ValueError:
+            raise ValueError(
+                f"Unknown preset: {preset}. "
+                f"Available: {[p.value for p in SecurityPolicyPresets]}"
+            )
+    else:
+        raise TypeError(f"preset must be str or SecurityPolicyPresets, got {type(preset)}")
+
+    # Parse isolation level
+    if isolation_level is not None:
+        if isinstance(isolation_level, str):
+            try:
+                isolation_level = IsolationLevel[isolation_level.upper()]
+            except KeyError:
+                raise ValueError(
+                    f"Unknown isolation level: {isolation_level}. "
+                    f"Available: {[l.name.lower() for l in IsolationLevel]}"
+                )
+        elif not isinstance(isolation_level, IsolationLevel):
+            raise TypeError(
+                f"isolation_level must be str or IsolationLevel, got {type(isolation_level)}"
+            )
+
+    # Build resource limits if any resource overrides provided
+    resource_overrides = {}
+    if max_memory_mb is not None:
+        resource_overrides["max_memory_mb"] = max_memory_mb
+    if max_cpu_percent is not None:
+        resource_overrides["max_cpu_percent"] = max_cpu_percent
+    if max_execution_time_sec is not None:
+        resource_overrides["max_execution_time_sec"] = max_execution_time_sec
+
+    if resource_overrides:
+        # Create new ResourceLimits with overrides
+        resource_limits = ResourceLimits(
+            max_memory_mb=resource_overrides.get(
+                "max_memory_mb", base.resource_limits.max_memory_mb
+            ),
+            max_cpu_percent=resource_overrides.get(
+                "max_cpu_percent", base.resource_limits.max_cpu_percent
+            ),
+            max_execution_time_sec=resource_overrides.get(
+                "max_execution_time_sec", base.resource_limits.max_execution_time_sec
+            ),
+            max_file_descriptors=base.resource_limits.max_file_descriptors,
+            allowed_paths=base.resource_limits.allowed_paths,
+            writable_paths=base.resource_limits.writable_paths,
+            denied_syscalls=base.resource_limits.denied_syscalls,
+        )
+    else:
+        resource_limits = base.resource_limits
+
+    # Convert list to tuple if needed
+    if isinstance(allowed_modules, list):
+        allowed_modules = tuple(allowed_modules)
+    if isinstance(blocked_modules, list):
+        blocked_modules = tuple(blocked_modules)
+
+    # Create policy with overrides
+    return SecurityPolicy(
+        isolation_level=isolation_level if isolation_level is not None else base.isolation_level,
+        resource_limits=resource_limits,
+        allow_network=allow_network if allow_network is not None else base.allow_network,
+        allow_subprocess=allow_subprocess if allow_subprocess is not None else base.allow_subprocess,
+        allow_file_write=allow_file_write if allow_file_write is not None else base.allow_file_write,
+        allowed_modules=allowed_modules if allowed_modules is not None else base.allowed_modules,
+        blocked_modules=blocked_modules if blocked_modules is not None else base.blocked_modules,
+        required_signatures=required_signatures if required_signatures is not None else base.required_signatures,
+        require_trusted_signer=require_trusted_signer if require_trusted_signer is not None else base.require_trusted_signer,
+        signature_max_age_days=signature_max_age_days if signature_max_age_days is not None else base.signature_max_age_days,
+    )
+
+
+def get_preset(name: str) -> SecurityPolicy:
+    """Get a security policy preset by name.
+
+    Args:
+        name: Preset name (case-insensitive)
+
+    Returns:
+        SecurityPolicy for the preset
+
+    Raises:
+        ValueError: If preset name is unknown
+    """
+    try:
+        preset = SecurityPolicyPresets(name.lower())
+        return preset.to_policy()
+    except ValueError:
+        available = [p.value for p in SecurityPolicyPresets]
+        raise ValueError(f"Unknown preset '{name}'. Available: {available}")
+
+
+def list_presets() -> list[str]:
+    """List all available preset names.
+
+    Returns:
+        List of preset names
+    """
+    return [p.value for p in SecurityPolicyPresets]