ostruct-cli 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

ostruct/cli/security/base.py

@@ -0,0 +1,46 @@
+"""Base class for security-related errors."""
+
+from typing import Any, Dict, Optional
+
+from ostruct.cli.base_errors import CLIError
+from ostruct.cli.exit_codes import ExitCode
+
+
+class SecurityErrorBase(CLIError):
+    """Base class for security-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+        details: Optional[str] = None,
+        has_been_logged: bool = False,
+    ) -> None:
+        """Initialize security error.
+
+        Args:
+            message: The error message.
+            context: Additional context for the error.
+            details: Detailed explanation of the error.
+            has_been_logged: Whether the error has been logged.
+        """
+        if context is None:
+            context = {}
+        context["category"] = "security"
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.SECURITY_ERROR,
+            details=details,
+        )
+        self._has_been_logged = has_been_logged
+
+    @property
+    def has_been_logged(self) -> bool:
+        """Whether this error has been logged."""
+        return self._has_been_logged
+
+    @has_been_logged.setter
+    def has_been_logged(self, value: bool) -> None:
+        """Set whether this error has been logged."""
+        self._has_been_logged = value

ostruct/cli/security/case_manager.py

@@ -0,0 +1,75 @@
+"""Case management module.
+
+This module provides a class for tracking and preserving the original case
+of file paths on case-insensitive systems.
+"""
+
+from pathlib import Path
+from threading import Lock
+from typing import Dict
+
+
+class CaseManager:
+    """Manages original case preservation for paths.
+
+    This class provides a thread-safe way to track original case preservation
+    without modifying Path objects. This is particularly important on
+    case-insensitive systems (macOS, Windows) where we normalize paths
+    to lowercase but want to preserve the original case for display.
+
+    Example:
+        >>> CaseManager.set_original_case(Path("/tmp/file.txt"), "/TMP/File.txt")
+        >>> CaseManager.get_original_case(Path("/tmp/file.txt"))
+        '/TMP/File.txt'
+    """
+
+    _case_mapping: Dict[str, str] = {}
+    _lock = Lock()
+
+    @classmethod
+    def set_original_case(
+        cls, normalized_path: Path, original_case: str
+    ) -> None:
+        """Store the original case for a normalized path.
+
+        Args:
+            normalized_path: The normalized (potentially lowercased) Path.
+            original_case: The original path string with its original case.
+
+        Raises:
+            TypeError: If normalized_path or original_case is None.
+        """
+        if normalized_path is None:
+            raise TypeError("normalized_path cannot be None")
+        if original_case is None:
+            raise TypeError("original_case cannot be None")
+
+        with cls._lock:
+            cls._case_mapping[str(normalized_path)] = original_case
+
+    @classmethod
+    def get_original_case(cls, normalized_path: Path) -> str:
+        """Retrieve the original case for a normalized path.
+
+        Args:
+            normalized_path: The normalized Path.
+
+        Returns:
+            The original case string if stored; otherwise the normalized path string.
+
+        Raises:
+            TypeError: If normalized_path is None.
+        """
+        if normalized_path is None:
+            raise TypeError("normalized_path cannot be None")
+
+        with cls._lock:
+            return cls._case_mapping.get(
+                str(normalized_path), str(normalized_path)
+            )
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear all stored case mappings."""
+        with cls._lock:
+            cls._case_mapping.clear()

ostruct/cli/security/errors.py

@@ -0,0 +1,164 @@
+"""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
+
+from .base import SecurityErrorBase
+
+
+class PathSecurityError(SecurityErrorBase):
+    """Security error for path-related issues."""
+
+    def __init__(
+        self,
+        message: str,
+        path: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
+        details: Optional[str] = None,
+        error_logged: bool = False,
+        wrapped: bool = False,
+    ) -> None:
+        """Initialize the error.
+
+        Args:
+            message: The error message.
+            path: The path that caused the error.
+            context: Additional context for the error.
+            details: Detailed explanation of the error.
+            error_logged: Whether the error has been logged.
+            wrapped: Whether this is a wrapped error.
+        """
+        if context is None:
+            context = {}
+        if path is not None:
+            context["path"] = path
+        if details is None:
+            details = "The specified path violates security constraints"
+            context["troubleshooting"] = [
+                "Check if the path is within allowed directories",
+                "Use --allowed-dir to specify additional allowed directories",
+                "Verify path permissions",
+            ]
+        self._wrapped = wrapped
+        super().__init__(
+            message,
+            context=context,
+            details=details,
+            has_been_logged=error_logged,
+        )
+
+    @property
+    def error_logged(self) -> bool:
+        """Alias for has_been_logged for backward compatibility."""
+        return self.has_been_logged
+
+    @property
+    def wrapped(self) -> bool:
+        """Whether this is a wrapped error."""
+        return self._wrapped
+
+    @property
+    def details(self) -> str:
+        """Get the detailed explanation of the error."""
+        return self.details
+
+    @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 from expanded paths.
+
+        Args:
+            original_path: The original path.
+            expanded_path: The expanded path.
+            base_dir: The base directory.
+            allowed_dirs: List of allowed directories.
+            error_logged: Whether the error has been logged.
+
+        Returns:
+            A new PathSecurityError instance.
+        """
+        context = {
+            "original_path": original_path,
+            "expanded_path": expanded_path,
+            "base_dir": base_dir,
+            "allowed_dirs": allowed_dirs,
+            "reason": SecurityErrorReasons.PATH_OUTSIDE_ALLOWED,
+            "troubleshooting": [
+                "Check if the path is within allowed directories",
+                f"Ensure the path is within base directory: {base_dir}",
+                f"Current allowed directories: {', '.join(allowed_dirs)}",
+            ],
+        }
+        return cls(
+            "Access denied",
+            context=context,
+            details="Path is outside allowed directories",
+            error_logged=error_logged,
+        )
+
+    @classmethod
+    def wrap_error(
+        cls, message: str, original_error: Exception
+    ) -> "PathSecurityError":
+        """Wrap another error with a security error.
+
+        Args:
+            message: The security error message.
+            original_error: The original error to wrap.
+
+        Returns:
+            A new PathSecurityError instance.
+        """
+        context = {
+            "wrapped_error": original_error.__class__.__name__,
+            "original_message": str(original_error),
+            "wrapped": True,
+            "troubleshooting": [
+                "Check if the path is within allowed directories",
+                "Verify path permissions",
+                "Check if the original error has been resolved",
+            ],
+        }
+        if hasattr(original_error, "context"):
+            context.update(original_error.context)
+        return cls(
+            message,
+            context=context,
+            wrapped=True,
+            error_logged=getattr(original_error, "error_logged", False),
+        )
+
+
+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