taipanstack 0.1.0__py3-none-any.whl

taipanstack/security/guards.py

@@ -0,0 +1,362 @@
+"""
+Runtime guards for protection against errors and AI hallucinations.
+
+These guards provide runtime protection against common security issues
+and programming errors that can occur from incorrect AI-generated code.
+All guards raise SecurityError on violation.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Sequence
+from pathlib import Path
+
+
+class SecurityError(Exception):
+    """Raised when a security guard detects a violation.
+
+    Attributes:
+        guard_name: Name of the guard that was triggered.
+        message: Description of the violation.
+        value: The offending value (if safe to log).
+
+    """
+
+    def __init__(
+        self,
+        message: str,
+        guard_name: str = "unknown",
+        value: str | None = None,
+    ) -> None:
+        """Initialize SecurityError.
+
+        Args:
+            message: Description of the violation.
+            guard_name: Name of the guard that triggered.
+            value: The offending value (sanitized).
+
+        """
+        self.guard_name = guard_name
+        self.value = value
+        super().__init__(f"[{guard_name}] {message}")
+
+
+def guard_path_traversal(
+    path: Path | str,
+    base_dir: Path | str | None = None,
+    *,
+    allow_symlinks: bool = False,
+) -> Path:
+    """Prevent path traversal attacks.
+
+    Ensures that the given path does not escape the base directory
+    using techniques like '..' or symlinks.
+
+    Args:
+        path: The path to validate.
+        base_dir: The base directory to constrain to. Defaults to cwd.
+        allow_symlinks: Whether to allow symlinks (default: False).
+
+    Returns:
+        The resolved, validated path.
+
+    Raises:
+        SecurityError: If path traversal is detected.
+
+    Example:
+        >>> guard_path_traversal("../etc/passwd", Path("/app"))
+        SecurityError: [path_traversal] Path escapes base directory
+
+    """
+    path = Path(path) if isinstance(path, str) else path
+    base_dir = Path(base_dir).resolve() if base_dir else Path.cwd().resolve()
+
+    # Check for explicit traversal patterns before resolution
+    path_str = str(path)
+    traversal_patterns = [
+        "..",
+        "~",
+        r"\.\.",
+        "%2e%2e",  # URL encoded ..
+        "%252e%252e",  # Double URL encoded
+    ]
+
+    for pattern in traversal_patterns:
+        if pattern.lower() in path_str.lower():
+            raise SecurityError(
+                f"Path traversal pattern detected: {pattern}",
+                guard_name="path_traversal",
+                value=path_str[:50],  # Truncate for safety
+            )
+
+    # Resolve the path
+    try:
+        resolved = path.resolve() if path.is_absolute() else (base_dir / path).resolve()
+    except (OSError, ValueError) as e:
+        raise SecurityError(
+            f"Invalid path: {e}",
+            guard_name="path_traversal",
+        ) from e
+
+    # Check if resolved path is within base_dir
+    try:
+        resolved.relative_to(base_dir)
+    except ValueError as e:
+        raise SecurityError(
+            f"Path escapes base directory: {resolved} is not under {base_dir}",
+            guard_name="path_traversal",
+            value=str(resolved)[:100],
+        ) from e
+
+    # Check for symlinks if not allowed
+    is_existing_symlink = (
+        not allow_symlinks and resolved.exists() and resolved.is_symlink()
+    )
+    if is_existing_symlink:
+        raise SecurityError(
+            "Symlinks are not allowed",
+            guard_name="path_traversal",
+            value=str(resolved),
+        )
+
+    return resolved
+
+
+def guard_command_injection(
+    command: Sequence[str],
+    *,
+    allowed_commands: Sequence[str] | None = None,
+) -> list[str]:
+    """Prevent command injection attacks.
+
+    Validates that command arguments don't contain shell metacharacters
+    that could lead to command injection.
+
+    Args:
+        command: The command and arguments as a sequence.
+        allowed_commands: Optional whitelist of allowed base commands.
+
+    Returns:
+        The validated command as a list.
+
+    Raises:
+        SecurityError: If command injection is detected.
+
+    Example:
+        >>> guard_command_injection(["echo", "hello; rm -rf /"])
+        SecurityError: [command_injection] Dangerous characters detected
+
+    """
+    if not command:
+        raise SecurityError(
+            "Empty command is not allowed",
+            guard_name="command_injection",
+        )
+
+    cmd_list = list(command)
+
+    # Dangerous shell metacharacters
+    dangerous_patterns: list[tuple[str, str]] = [
+        (";", "command separator"),
+        ("|", "pipe"),
+        ("&", "background/and operator"),
+        ("$", "variable expansion"),
+        ("`", "command substitution"),
+        ("$(", "command substitution"),
+        ("${", "variable expansion"),
+        (">", "redirect"),
+        ("<", "redirect"),
+        (">>", "redirect append"),
+        ("||", "or operator"),
+        ("&&", "and operator"),
+        ("\n", "newline"),
+        ("\r", "carriage return"),
+        ("\x00", "null byte"),
+    ]
+
+    for arg in cmd_list:
+        for pattern, description in dangerous_patterns:
+            if pattern in arg:
+                raise SecurityError(
+                    f"Dangerous shell character detected: {description}",
+                    guard_name="command_injection",
+                    value=arg[:50],
+                )
+
+    # Check against allowed commands whitelist
+    if allowed_commands is not None:
+        base_command = cmd_list[0]
+        # Get just the command name without path
+        command_name = Path(base_command).name
+        cmd_not_allowed = (
+            command_name not in allowed_commands
+            and base_command not in allowed_commands
+        )
+        if cmd_not_allowed:
+            raise SecurityError(
+                f"Command not in allowed list: {command_name}",
+                guard_name="command_injection",
+                value=command_name,
+            )
+
+    return cmd_list
+
+
+def guard_file_extension(
+    filename: str | Path,
+    *,
+    allowed_extensions: Sequence[str] | None = None,
+    denied_extensions: Sequence[str] | None = None,
+) -> Path:
+    """Validate file extension against allow/deny lists.
+
+    Args:
+        filename: The filename to check.
+        allowed_extensions: Extensions to allow (with or without dot).
+        denied_extensions: Extensions to deny (with or without dot).
+
+    Returns:
+        The filename as a Path.
+
+    Raises:
+        SecurityError: If extension is not allowed or is denied.
+
+    """
+    path = Path(filename)
+    ext = path.suffix.lower().lstrip(".")
+
+    # Default dangerous extensions
+    default_denied = {
+        "exe",
+        "dll",
+        "so",
+        "dylib",  # Executables
+        "sh",
+        "bash",
+        "zsh",
+        "ps1",
+        "bat",
+        "cmd",  # Scripts
+        "php",
+        "jsp",
+        "asp",
+        "aspx",  # Server-side scripts
+    }
+
+    # Normalize extension lists
+    def normalize_ext(e: str) -> str:
+        return e.lower().lstrip(".")
+
+    if denied_extensions is not None:
+        denied = {normalize_ext(e) for e in denied_extensions}
+    else:
+        denied = default_denied
+
+    if ext in denied:
+        raise SecurityError(
+            f"File extension '{ext}' is not allowed",
+            guard_name="file_extension",
+            value=str(path.name),
+        )
+
+    if allowed_extensions is not None:
+        allowed = {normalize_ext(e) for e in allowed_extensions}
+        if ext not in allowed:
+            raise SecurityError(
+                f"File extension '{ext}' is not in allowed list",
+                guard_name="file_extension",
+                value=str(path.name),
+            )
+
+    return path
+
+
+def guard_env_variable(
+    name: str,
+    *,
+    allowed_names: Sequence[str] | None = None,
+    denied_names: Sequence[str] | None = None,
+) -> str:
+    """Guard against accessing sensitive environment variables.
+
+    Args:
+        name: The environment variable name.
+        allowed_names: Variable names to allow.
+        denied_names: Variable names to deny.
+
+    Returns:
+        The environment variable value if safe.
+
+    Raises:
+        SecurityError: If variable access is not allowed.
+
+    """
+    # Default sensitive variables
+    default_denied = {
+        "AWS_SECRET_ACCESS_KEY",
+        "AWS_SESSION_TOKEN",
+        "GITHUB_TOKEN",
+        "GH_TOKEN",
+        "GITLAB_TOKEN",
+        "DATABASE_URL",
+        "DB_PASSWORD",
+        "PASSWORD",
+        "SECRET_KEY",
+        "PRIVATE_KEY",
+        "API_KEY",
+        "API_SECRET",
+    }
+
+    name_upper = name.upper()
+
+    if denied_names is not None:
+        denied = {n.upper() for n in denied_names}
+    else:
+        denied = default_denied
+
+    # Check against patterns
+    sensitive_patterns = [
+        r".*SECRET.*",
+        r".*PASSWORD.*",
+        r".*TOKEN.*",
+        r".*PRIVATE.*KEY.*",
+        r".*API.*KEY.*",
+    ]
+
+    if name_upper in denied:
+        raise SecurityError(
+            f"Access to sensitive variable '{name}' is denied",
+            guard_name="env_variable",
+            value=name,
+        )
+
+    for pattern in sensitive_patterns:
+        if re.match(pattern, name_upper):
+            # Only block if not explicitly allowed
+            if allowed_names is not None:
+                allowed = {n.upper() for n in allowed_names}
+                if name_upper not in allowed:
+                    raise SecurityError(
+                        f"Access to potentially sensitive variable '{name}' is denied",
+                        guard_name="env_variable",
+                        value=name,
+                    )
+            else:
+                raise SecurityError(
+                    f"Access to potentially sensitive variable '{name}' is denied",
+                    guard_name="env_variable",
+                    value=name,
+                )
+
+    # Get the variable
+    value = os.environ.get(name)
+    if value is None:
+        raise SecurityError(
+            f"Environment variable '{name}' is not set",
+            guard_name="env_variable",
+            value=name,
+        )
+
+    return value

taipanstack/security/sanitizers.py

@@ -0,0 +1,321 @@
+"""
+Input sanitizers for cleaning untrusted data.
+
+Provides functions to sanitize strings, filenames, and paths
+to remove potentially dangerous characters.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from pathlib import Path
+
+# Constants to avoid magic values (PLR2004)
+MAX_SQL_IDENTIFIER_LENGTH = 128
+
+
+def sanitize_string(
+    value: str,
+    *,
+    max_length: int | None = None,
+    allow_html: bool = False,
+    allow_unicode: bool = True,
+    strip_whitespace: bool = True,
+) -> str:
+    """Sanitize a string by removing dangerous characters.
+
+    Args:
+        value: The string to sanitize.
+        max_length: Maximum length to truncate to.
+        allow_html: Whether to keep HTML tags (default: False).
+        allow_unicode: Whether to keep non-ASCII characters.
+        strip_whitespace: Whether to strip leading/trailing whitespace.
+
+    Returns:
+        The sanitized string.
+
+    Example:
+        >>> sanitize_string("<script>alert('xss')</script>Hello")
+        "scriptalert('xss')/scriptHello"
+
+    """
+    if not value:
+        return ""
+
+    result = value
+
+    # Strip whitespace first
+    if strip_whitespace:
+        result = result.strip()
+
+    # Remove null bytes and control characters
+    result = result.replace("\x00", "")
+    result = "".join(
+        c for c in result if unicodedata.category(c) != "Cc" or c in "\n\r\t"
+    )
+
+    # Handle HTML
+    if not allow_html:
+        # Remove HTML tags
+        result = re.sub(r"<[^>]+>", "", result)
+        # Escape HTML entities
+        result = result.replace("&", "&amp;")
+        result = result.replace("<", "&lt;")
+        result = result.replace(">", "&gt;")
+
+    # Handle unicode
+    if not allow_unicode:
+        result = result.encode("ascii", errors="ignore").decode("ascii")
+
+    # Truncate if needed
+    if max_length is not None and len(result) > max_length:
+        result = result[:max_length]
+
+    return result
+
+
+def sanitize_filename(
+    filename: str,
+    *,
+    max_length: int = 255,
+    replacement: str = "_",
+    preserve_extension: bool = True,
+) -> str:
+    """Sanitize a filename to be safe for filesystem use.
+
+    Removes or replaces characters that are:
+    - Not allowed in filenames on various OSes
+    - Potentially dangerous (path separators, etc.)
+
+    Args:
+        filename: The filename to sanitize.
+        max_length: Maximum length for the filename.
+        replacement: Character to replace invalid chars with.
+        preserve_extension: Keep original extension.
+
+    Returns:
+        The sanitized filename.
+
+    Example:
+        >>> sanitize_filename("my/../file<>:name.txt")
+        'my_file_name.txt'
+
+    """
+    if not filename:
+        return "unnamed"
+
+    # Get parts
+    original_path = Path(filename)
+    stem = original_path.stem
+    suffix = original_path.suffix if preserve_extension else ""
+
+    # Characters not allowed in filenames (Windows + Unix)
+    invalid_chars = r'[<>:"/\\|?*\x00-\x1f]'
+
+    # Remove invalid characters
+    safe_stem = re.sub(invalid_chars, replacement, stem)
+
+    # Remove leading/trailing dots and spaces (Windows issues)
+    safe_stem = safe_stem.strip(". ")
+
+    # Remove path separators that might have snuck through
+    safe_stem = safe_stem.replace("/", replacement)
+    safe_stem = safe_stem.replace("\\", replacement)
+
+    # Collapse multiple replacement chars
+    if replacement:
+        safe_stem = re.sub(f"{re.escape(replacement)}+", replacement, safe_stem)
+        safe_stem = safe_stem.strip(replacement)
+
+    # Handle reserved names (Windows)
+    reserved_names = {
+        "CON",
+        "PRN",
+        "AUX",
+        "NUL",
+        "COM1",
+        "COM2",
+        "COM3",
+        "COM4",
+        "COM5",
+        "COM6",
+        "COM7",
+        "COM8",
+        "COM9",
+        "LPT1",
+        "LPT2",
+        "LPT3",
+        "LPT4",
+        "LPT5",
+        "LPT6",
+        "LPT7",
+        "LPT8",
+        "LPT9",
+    }
+
+    if safe_stem.upper() in reserved_names:
+        safe_stem = f"{replacement}{safe_stem}"
+
+    # Handle empty result
+    if not safe_stem:
+        safe_stem = "unnamed"
+
+    # Construct result
+    result = f"{safe_stem}{suffix}"
+
+    # Truncate if needed (keeping extension)
+    if len(result) > max_length:
+        available = max_length - len(suffix)
+        if available > 0:
+            safe_stem = safe_stem[:available]
+            result = f"{safe_stem}{suffix}"
+        else:
+            result = result[:max_length]
+
+    return result
+
+
+def sanitize_path(
+    path: str | Path,
+    *,
+    base_dir: Path | None = None,
+    max_depth: int | None = 10,
+    resolve: bool = False,
+) -> Path:
+    """Sanitize a path to prevent traversal and normalize it.
+
+    Args:
+        path: The path to sanitize.
+        base_dir: Optional base directory to constrain to.
+        max_depth: Maximum directory depth allowed.
+        resolve: Whether to resolve the path (requires it to exist).
+
+    Returns:
+        The sanitized Path object.
+
+    Raises:
+        ValueError: If path is invalid or too deep.
+
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    # Remove any null bytes
+    path_str = str(path).replace("\x00", "")
+
+    # Normalize the path
+    path = Path(path_str)
+
+    # Remove any .. or . components manually
+    parts: list[str] = []
+    for part in path.parts:
+        if part == "..":
+            if parts and parts[-1] != "..":
+                parts.pop()
+            # Skip the .. entirely if at root
+        elif part != ".":
+            # Sanitize each component
+            safe_part = sanitize_filename(part, preserve_extension=True)
+            if safe_part:  # Skip empty parts
+                parts.append(safe_part)
+
+    # Reconstruct path
+    if path.is_absolute():
+        sanitized = Path("/").joinpath(*parts) if parts else Path("/")
+    else:
+        sanitized = Path().joinpath(*parts) if parts else Path()
+
+    # Check depth (skip if max_depth is None)
+    depth = len(sanitized.parts)
+    if max_depth is not None and depth > max_depth:
+        msg = f"Path depth {depth} exceeds maximum of {max_depth}"
+        raise ValueError(msg)
+
+    # Constrain to base_dir if provided
+    if base_dir is not None:
+        base = Path(base_dir).resolve()
+        if resolve:
+            try:
+                sanitized = sanitized.resolve()
+            except (OSError, RuntimeError) as e:
+                msg = f"Cannot resolve path: {e}"
+                raise ValueError(msg) from e
+        # Make absolute relative to base
+        elif not sanitized.is_absolute():
+            sanitized = base / sanitized
+
+    return sanitized
+
+
+def sanitize_env_value(
+    value: str,
+    *,
+    max_length: int = 4096,
+    allow_multiline: bool = False,
+) -> str:
+    """Sanitize a value for use as an environment variable.
+
+    Args:
+        value: The value to sanitize.
+        max_length: Maximum length allowed.
+        allow_multiline: Whether to allow newlines.
+
+    Returns:
+        The sanitized value.
+
+    """
+    if not value:
+        return ""
+
+    result = value
+
+    # Remove null bytes
+    result = result.replace("\x00", "")
+
+    # Handle newlines
+    if not allow_multiline:
+        result = result.replace("\n", " ").replace("\r", " ")
+
+    # Truncate
+    if len(result) > max_length:
+        result = result[:max_length]
+
+    return result
+
+
+def sanitize_sql_identifier(identifier: str) -> str:
+    """Sanitize a SQL identifier (table/column name).
+
+    Note: This is NOT for SQL values - use parameterized queries for those!
+
+    Args:
+        identifier: The identifier to sanitize.
+
+    Returns:
+        The sanitized identifier.
+
+    Raises:
+        ValueError: If identifier is empty or too long.
+
+    """
+    if not identifier:
+        msg = "SQL identifier cannot be empty"
+        raise ValueError(msg)
+
+    # Only allow alphanumeric and underscore
+    result = re.sub(r"[^a-zA-Z0-9_]", "", identifier)
+
+    # Must start with letter or underscore
+    if result and not (result[0].isalpha() or result[0] == "_"):
+        result = f"_{result}"
+
+    # Check length (most DBs limit to 128 chars)
+    if len(result) > MAX_SQL_IDENTIFIER_LENGTH:
+        result = result[:MAX_SQL_IDENTIFIER_LENGTH]
+
+    if not result:
+        msg = "SQL identifier contains no valid characters"
+        raise ValueError(msg)
+
+    return result