ostruct-cli 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

ostruct/cli/security/errors.py

@@ -0,0 +1,184 @@
+"""Error definitions for the security package.
+
+This module defines custom exceptions and error reason constants used throughout
+the security modules.
+"""
+
+from typing import Any, Dict, List, Optional
+
+
+class PathSecurityError(Exception):
+    """Base exception for security-related errors.
+
+    This class provides rich error information for security-related issues,
+    including context and error wrapping capabilities.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        path: str = "",
+        context: Optional[Dict[str, Any]] = None,
+        error_logged: bool = False,
+    ) -> None:
+        """Initialize the error.
+
+        Args:
+            message: The error message.
+            path: The path that caused the error.
+            context: Additional context about the error.
+            error_logged: Whether this error has already been logged.
+        """
+        super().__init__(message)
+        self.path = path
+        self.context = context or {}
+        self._error_logged = error_logged
+        self._wrapped = False
+
+    def __str__(self) -> str:
+        """Format the error message with context if available."""
+        msg = super().__str__()
+
+        # Add expanded path information if available
+        if self.context:
+            if (
+                "original_path" in self.context
+                and "expanded_path" in self.context
+            ):
+                msg = (
+                    f"{msg}\n"
+                    f"Original path: {self.context['original_path']}\n"
+                    f"Expanded path: {self.context['expanded_path']}"
+                )
+            if "base_dir" in self.context:
+                msg = f"{msg}\nBase directory: {self.context['base_dir']}"
+            if "allowed_dirs" in self.context:
+                msg = f"{msg}\nAllowed directories: {self.context['allowed_dirs']!r}"
+
+        return msg
+
+    @property
+    def has_been_logged(self) -> bool:
+        """Whether this error has been logged."""
+        return self._error_logged
+
+    @has_been_logged.setter
+    def has_been_logged(self, value: bool) -> None:
+        """Set whether this error has been logged."""
+        self._error_logged = value
+
+    @property
+    def wrapped(self) -> bool:
+        """Whether this error is wrapping another error."""
+        return self._wrapped
+
+    def format_with_context(
+        self,
+        original_path: str,
+        expanded_path: str,
+        base_dir: str,
+        allowed_dirs: List[str],
+    ) -> str:
+        """Format the error message with additional context.
+
+        Args:
+            original_path: The original path that caused the error
+            expanded_path: The expanded/absolute path
+            base_dir: The base directory for security checks
+            allowed_dirs: List of allowed directories
+
+        Returns:
+            A formatted error message with context
+        """
+        lines = [
+            str(self),
+            f"Original path: {original_path}",
+            f"Expanded path: {expanded_path}",
+            f"Base directory: {base_dir}",
+            f"Allowed directories: {allowed_dirs}",
+            "Use --allowed-dir to add more allowed directories",
+        ]
+        return "\n".join(lines)
+
+    @classmethod
+    def wrap_error(
+        cls, message: str, original: "PathSecurityError"
+    ) -> "PathSecurityError":
+        """Wrap an existing error with additional context.
+
+        Args:
+            message: The new error message
+            original: The original error to wrap
+
+        Returns:
+            A new PathSecurityError instance wrapping the original
+        """
+        wrapped = cls(
+            f"{message}: {str(original)}",
+            path=original.path,
+            context=original.context,
+            error_logged=original.has_been_logged,
+        )
+        wrapped._wrapped = True
+        return wrapped
+
+    @classmethod
+    def from_expanded_paths(
+        cls,
+        original_path: str,
+        expanded_path: str,
+        base_dir: str,
+        allowed_dirs: List[str],
+        error_logged: bool = False,
+    ) -> "PathSecurityError":
+        """Create an error instance with expanded path information.
+
+        Args:
+            original_path: The original path that caused the error
+            expanded_path: The expanded/absolute path
+            base_dir: The base directory for security checks
+            allowed_dirs: List of allowed directories
+            error_logged: Whether this error has already been logged
+
+        Returns:
+            A new PathSecurityError instance with expanded path context
+        """
+        message = f"Path '{original_path}' is outside the base directory and not in allowed directories"
+        context = {
+            "original_path": original_path,
+            "expanded_path": expanded_path,
+            "base_dir": base_dir,
+            "allowed_dirs": allowed_dirs,
+        }
+        return cls(
+            message,
+            path=original_path,
+            context=context,
+            error_logged=error_logged,
+        )
+
+
+class DirectoryNotFoundError(PathSecurityError):
+    """Raised when a directory that is expected to exist does not."""
+
+
+class SecurityErrorReasons:
+    """Constants for common security error reasons."""
+
+    # Path validation errors
+    PATH_TRAVERSAL = "path_traversal"
+    UNSAFE_UNICODE = "unsafe_unicode"
+    NORMALIZATION_ERROR = "normalization_error"
+    CASE_MISMATCH = "case_mismatch"
+
+    # Symlink-related errors
+    SYMLINK_LOOP = "symlink_loop"
+    SYMLINK_ERROR = "symlink_error"
+    SYMLINK_TARGET_NOT_ALLOWED = "symlink_target_not_allowed"
+    SYMLINK_MAX_DEPTH = "symlink_max_depth"
+    SYMLINK_BROKEN = "symlink_broken"
+
+    # Directory access errors
+    PATH_NOT_IN_BASE = "path_not_in_base"
+    PATH_OUTSIDE_ALLOWED = "path_outside_allowed"
+    TEMP_PATHS_NOT_ALLOWED = "temp_paths_not_allowed"

ostruct/cli/security/normalization.py

@@ -0,0 +1,161 @@
+"""Path normalization module.
+
+This module provides functions to normalize file paths by:
+- Performing Unicode normalization (NFKC)
+- Normalizing path separators and redundant parts
+- Converting relative paths to absolute paths
+- Validating Unicode safety
+
+Security Design Choices:
+1. Unicode Normalization:
+   - Uses NFKC form for maximum compatibility
+   - Blocks known unsafe Unicode characters
+   - Basic protection against homograph attacks
+   - Does not handle all possible confusable sequences
+
+2. Path Separators:
+   - Normalizes to forward slashes
+   - Collapses multiple slashes
+   - Converts backslashes on all platforms
+   - Note: This breaks Windows UNC and device paths
+
+3. Parent Directory References:
+   - Allows ".." components in raw input
+   - Security checks done after path resolution
+   - Directory traversal prevented by final path validation
+
+4. Absolute Paths:
+   - Converts relative to absolute using CWD
+   - No environment variable expansion
+   - No home directory (~) expansion
+   - Thread-safety warning for CWD operations
+
+Known Limitations:
+1. Windows-Specific:
+   - UNC paths (r"\\\\server\\share") break when normalized
+   - Device paths (r"\\\\?\\", r"\\\\.") become invalid
+   - Drive-relative paths may resolve incorrectly
+   - Reserved names (CON, NUL, etc.) not handled
+   - ADS (:stream) not detected
+   - Case sensitivity not handled (delegated to CaseManager)
+
+2. Unicode Handling:
+   - Some confusable characters may pass checks
+   - Zero-width characters not fully covered
+   - Advanced homograph attacks possible
+   - Duplicate entries in safety pattern need review
+
+3. Threading:
+   - CWD operations not thread-safe
+   - Race conditions possible during path resolution
+"""
+
+import os
+import re
+import unicodedata
+from pathlib import Path
+from typing import Union
+
+from .errors import PathSecurityError, SecurityErrorReasons
+
+# Patterns for path normalization and validation
+_UNICODE_SAFETY_PATTERN = re.compile(
+    r"[\u0000-\u001F\u007F-\u009F\u2028-\u2029\u0085]"  # Control chars and line separators
+    r"|\.{2,}"  # Directory traversal attempts
+    r"|[\u2024\u2025\uFE52\u2024\u2025\u2026\uFE19\uFE30\uFE52\uFF0E\uFF61]"  # Alternative dots and separators
+)
+_BACKSLASH_PATTERN = re.compile(r"\\")
+_MULTIPLE_SLASH_PATTERN = re.compile(r"/+")
+
+
+def normalize_path(path: Union[str, Path]) -> Path:
+    """Normalize a path string with security checks.
+
+    This function:
+    1. Converts to Unicode NFKC form
+    2. Checks for unsafe Unicode characters
+    3. Normalizes path separators
+    4. Uses os.path.normpath to collapse redundant separators and dots
+    5. Converts to absolute path if needed
+    6. Returns a pathlib.Path object
+
+    Security Features:
+    - Unicode NFKC normalization
+    - Blocks unsafe Unicode characters
+    - Normalizes path separators
+    - Converts to absolute paths
+
+    Design Choices:
+    - No environment variable expansion
+    - No home directory (~) expansion
+    - No symlink resolution (handled separately)
+    - Case sensitivity handled by CaseManager
+    - Thread-safety warning: CWD operations are not atomic
+
+    Args:
+        path: A string or Path object representing a file path.
+
+    Returns:
+        A pathlib.Path object for the normalized absolute path.
+
+    Raises:
+        PathSecurityError: If the path contains unsafe Unicode characters.
+        TypeError: If path is None.
+
+    Note:
+        This function has known limitations with Windows paths:
+        - UNC paths are not properly handled
+        - Device paths are not supported
+        - Drive-relative paths may resolve incorrectly
+        - Reserved names are not checked
+        - ADS is not detected
+    """
+    if path is None:
+        raise TypeError("Path cannot be None")
+
+    path_str = str(path)
+
+    # Unicode normalization
+    try:
+        normalized = unicodedata.normalize("NFKC", path_str)
+    except Exception as e:
+        raise PathSecurityError(
+            "Unicode normalization failed",
+            path=path_str,
+            context={
+                "reason": SecurityErrorReasons.UNSAFE_UNICODE,
+                "error": str(e),
+            },
+        ) from e
+
+    # Check for unsafe characters and directory traversal
+    if match := _UNICODE_SAFETY_PATTERN.search(normalized):
+        matched_text = match.group(0)
+        if ".." in matched_text:
+            raise PathSecurityError(
+                "Directory traversal not allowed",
+                path=path_str,
+                context={
+                    "reason": SecurityErrorReasons.PATH_TRAVERSAL,
+                    "matched": matched_text,
+                },
+            )
+        else:
+            raise PathSecurityError(
+                "Path contains unsafe characters",
+                path=path_str,
+                context={
+                    "reason": SecurityErrorReasons.UNSAFE_UNICODE,
+                    "matched": matched_text,
+                },
+            )
+
+    # Normalize path separators
+    normalized = _BACKSLASH_PATTERN.sub("/", normalized)
+    normalized = _MULTIPLE_SLASH_PATTERN.sub("/", normalized)
+
+    # Convert to absolute path if needed
+    if not os.path.isabs(normalized):
+        normalized = os.path.abspath(normalized)
+
+    return Path(normalized)

ostruct/cli/security/safe_joiner.py

@@ -0,0 +1,211 @@
+"""Safe path joining module.
+
+This module provides a safe_join function that is inspired by Werkzeug's safe_join.
+It safely joins untrusted path components to a trusted base directory while avoiding
+directory traversal issues.
+
+Security Design Choices:
+1. Parent Directory (..) References:
+   - Explicitly blocked for security, even in "safe" contexts
+   - This is a deliberate choice to prevent directory traversal
+   - No exceptions are made, even for legitimate uses
+
+2. Environment Variables:
+   - No expansion of environment variables (%VAR%, $HOME)
+   - Must be handled explicitly at a higher level if needed
+   - Prevents unexpected path resolution
+
+3. Home Directory:
+   - No expansion of ~ (tilde)
+   - Must be expanded explicitly before passing to this function
+   - Prevents unexpected user directory access
+
+4. Symlinks:
+   - Not resolved in this module
+   - Handled separately by the resolve_symlink function
+   - Allows for explicit symlink security policies
+
+5. Case Sensitivity:
+   - Basic normalization only
+   - Full case handling delegated to CaseManager
+   - Ensures consistent cross-platform behavior
+
+Known Limitations:
+1. Windows-Specific:
+   - UNC paths (r"\\\\server\\share") are handled but must be complete
+   - Device paths (r"\\\\?\\", r"\\\\.") are rejected for security
+   - Drive-relative paths (C:folder) must be absolute
+   - Reserved names (CON, NUL, etc.) are rejected
+   - Alternate Data Streams (:stream) are rejected
+
+2. Unicode:
+   - Basic NFKC normalization only
+   - Some confusable characters may not be detected
+   - Advanced homograph attack prevention requires additional checks
+
+3. Threading:
+   - Current working directory calls are not thread-safe
+   - Race conditions possible if CWD changes during execution
+"""
+
+import os
+import posixpath
+import re
+from typing import Optional
+
+# Compute alternative separators (if any) that differ from "/"
+_os_alt_seps = list(
+    {sep for sep in [os.path.sep, os.path.altsep] if sep and sep != "/"}
+)
+
+# Windows-specific patterns
+_WINDOWS_DEVICE_PATH = re.compile(r"^\\\\[?.]\\")  # \\?\ and \\.\ paths
+_WINDOWS_DRIVE_RELATIVE = re.compile(
+    r"^[A-Za-z]:(?![/\\])"
+)  # C:folder (no slash)
+_WINDOWS_RESERVED_NAMES = re.compile(
+    r"^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)", re.IGNORECASE
+)
+_WINDOWS_UNC = re.compile(r"^\\\\[^?./\\]")  # UNC but not device paths
+_WINDOWS_ADS = re.compile(r":.+$")  # Alternate Data Streams
+
+
+def safe_join(directory: str, *pathnames: str) -> Optional[str]:
+    """Safely join zero or more untrusted path components to a trusted base directory.
+
+    This function is inspired by Werkzeug's safe_join and ensures that the
+    resulting path is always within the base directory, preventing directory
+    traversal attacks.
+
+    Security Features:
+    - Rejects absolute path components
+    - Blocks all parent directory references (..)
+    - Normalizes path separators to forward slashes
+    - Performs final containment check against base directory
+    - Handles Windows-specific security concerns:
+        * Rejects device paths (r"\\\\?\\", r"\\\\.")
+        * Rejects relative drive paths (C:folder)
+        * Rejects reserved names (CON, PRN, etc.)
+        * Rejects Alternate Data Streams
+        * Safely handles UNC paths
+
+    Design Choices:
+    - No environment variable expansion
+    - No home directory (~) expansion
+    - No symlink resolution (handled separately)
+    - Case sensitivity handled by CaseManager
+    - Thread-safety warning: CWD operations are not atomic
+
+    Args:
+        directory: The trusted base directory.
+        pathnames: Untrusted path components relative to the base directory.
+
+    Returns:
+        A safe path as a string if successful; otherwise, None.
+
+    Example:
+        >>> safe_join("/base", "subdir", "file.txt")
+        '/base/subdir/file.txt'
+        >>> safe_join("/base", "../etc/passwd")
+        None
+    """
+    if not directory and not pathnames:
+        return None
+
+    if not directory:
+        directory = "."
+
+    # Handle None values in pathnames
+    if any(p is None for p in pathnames):
+        return None
+
+    # Convert and normalize base directory
+    directory = str(directory)
+    directory = directory.replace("\\", "/")
+    base_dir = posixpath.normpath(directory)
+
+    # Windows-specific base directory checks
+    if os.name == "nt":
+        # Check for device paths
+        if _WINDOWS_DEVICE_PATH.search(base_dir):
+            return None
+        # Check for relative drive paths
+        if _WINDOWS_DRIVE_RELATIVE.search(base_dir):
+            return None
+        # Check for reserved names
+        if _WINDOWS_RESERVED_NAMES.search(base_dir):
+            return None
+        # Check for ADS
+        if _WINDOWS_ADS.search(base_dir):
+            return None
+        # Handle UNC paths - must be complete
+        if _WINDOWS_UNC.search(base_dir):
+            if base_dir.count("/") < 3:  # Needs server and share
+                return None
+
+    # Process and validate each component
+    normalized_parts = []
+    for filename in pathnames:
+        if filename == "":
+            continue
+
+        # Convert to string and normalize separators
+        filename = str(filename)
+        filename = filename.replace("\\", "/")
+
+        # Windows-specific component checks
+        if os.name == "nt":
+            # Check for device paths
+            if _WINDOWS_DEVICE_PATH.search(filename):
+                return None
+            # Check for relative drive paths
+            if _WINDOWS_DRIVE_RELATIVE.search(filename):
+                return None
+            # Check for reserved names
+            if _WINDOWS_RESERVED_NAMES.search(filename):
+                return None
+            # Check for ADS
+            if _WINDOWS_ADS.search(filename):
+                return None
+            # Reject UNC in components
+            if _WINDOWS_UNC.search(filename):
+                return None
+
+        # Reject absolute paths and parent directory traversal
+        if (
+            filename.startswith("/")
+            or filename == ".."
+            or filename.startswith("../")
+            or filename.endswith("/..")
+            or "/../" in filename
+        ):
+            return None
+
+        # Normalize the component
+        normalized = posixpath.normpath(filename)
+        if normalized == ".":
+            continue
+        normalized_parts.append(normalized)
+
+    # Join all parts
+    if not normalized_parts:
+        result = base_dir
+    else:
+        result = posixpath.join(base_dir, *normalized_parts)
+
+    # Final security check on the complete path
+    normalized_result = posixpath.normpath(result)
+    if not normalized_result.startswith(base_dir):
+        return None
+
+    # Final Windows-specific checks on complete path
+    if os.name == "nt":
+        # Check for ADS in final path
+        if _WINDOWS_ADS.search(normalized_result):
+            return None
+        # Check for reserved names in any component
+        path_parts = normalized_result.split("/")
+        if any(_WINDOWS_RESERVED_NAMES.search(part) for part in path_parts):
+            return None
+
+    return normalized_result