contextual-engine 0.1.0__py3-none-any.whl

contextual/security/paths.py

@@ -0,0 +1,347 @@
+"""Path safety utilities for preventing traversal and injection attacks.
+
+This module provides bulletproof path validation to prevent:
+- Path traversal attacks (../../../etc/passwd)
+- Symlink attacks (links outside project root)
+- Windows reserved name attacks (CON, PRN, AUX, NUL)
+- Excessive path depth attacks
+- Invalid path characters
+
+All file operations in Contextual must use safe_path() before accessing the filesystem.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from contextual.core.errors import ErrorCode, SecurityError, security_context
+
+
+# Windows reserved device names that must be rejected
+WINDOWS_RESERVED_NAMES = frozenset({
+    "CON", "PRN", "AUX", "NUL",
+    "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
+    "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
+})
+
+
+def safe_path(root: Path, candidate: Path | str, *, allow_create: bool = False) -> Path:
+    """Validate and resolve a path safely within a root directory.
+    
+    This is the primary path safety function. ALL file operations in Contextual
+    must call this before touching the filesystem.
+    
+    Security guarantees:
+    1. Path is resolved to absolute form
+    2. Symlinks are resolved (no following links outside root)
+    3. Result is strictly within root directory
+    4. No path traversal sequences (../) can escape
+    5. No Windows reserved device names
+    6. Path depth is within limits
+    
+    Args:
+        root: Root directory that must contain the result.
+        candidate: Path to validate (relative or absolute).
+        allow_create: If True, don't require path to exist (for file creation).
+        
+    Returns:
+        Validated absolute path guaranteed to be within root.
+        
+    Raises:
+        SecurityError: If path validation fails for any reason.
+        
+    Examples:
+        >>> root = Path("/home/user/project")
+        >>> safe_path(root, "src/main.py")  # OK
+        Path('/home/user/project/src/main.py')
+        
+        >>> safe_path(root, "../../../etc/passwd")  # BLOCKED
+        SecurityError: Path traversal attempt
+        
+        >>> safe_path(root, "/tmp/evil.txt")  # BLOCKED
+        SecurityError: Path outside root
+    """
+    # Ensure root is absolute
+    if not root.is_absolute():
+        msg = "Root path must be absolute"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_PATH_INVALID,
+            message=msg,
+            context=security_context(path=str(root)),
+        )
+
+    # Convert candidate to Path if string
+    if isinstance(candidate, str):
+        candidate = Path(candidate)
+
+    # Resolve root (follows symlinks, gets absolute path)
+    try:
+        resolved_root = root.resolve(strict=True)
+    except (OSError, RuntimeError) as e:
+        # OSError: path doesn't exist or permission denied
+        # RuntimeError: symlink loop (Python <3.13)
+        msg = f"Failed to resolve root path: {e}"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_PATH_SYMLINK_LOOP,
+            message=msg,
+            context=security_context(path=str(root)),
+        ) from e
+
+    # Build full candidate path
+    if candidate.is_absolute():
+        full_path = candidate
+    else:
+        full_path = resolved_root / candidate
+
+    # Resolve candidate path
+    try:
+        if allow_create:
+            # For file creation, resolve parent and append filename
+            if full_path.parent.exists():
+                resolved_parent = full_path.parent.resolve(strict=True)
+                resolved_path = resolved_parent / full_path.name
+            else:
+                # Parent doesn't exist - resolve as much as possible
+                # Walk up until we find an existing parent
+                parts = list(full_path.parts)
+                for i in range(len(parts), 0, -1):
+                    test_path = Path(*parts[:i])
+                    if test_path.exists():
+                        resolved_existing = test_path.resolve(strict=True)
+                        remaining = Path(*parts[i:])
+                        resolved_path = resolved_existing / remaining
+                        break
+                else:
+                    # No existing ancestor found
+                    msg = "No existing ancestor directory found"
+                    raise SecurityError(
+                        code=ErrorCode.SECURITY_PATH_INVALID,
+                        message=msg,
+                        context=security_context(path=str(full_path), root=str(resolved_root)),
+                    )
+        else:
+            # For reading, path must exist
+            resolved_path = full_path.resolve(strict=True)
+    except (OSError, RuntimeError) as e:
+        # OSError: path doesn't exist, permission denied
+        # RuntimeError: symlink loop (Python <3.13)
+        msg = f"Failed to resolve path: {e}"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_PATH_SYMLINK_LOOP,
+            message=msg,
+            context=security_context(path=str(full_path), root=str(resolved_root)),
+        ) from e
+
+    # Critical security check: ensure resolved path is within root
+    try:
+        resolved_path.relative_to(resolved_root)
+    except ValueError as e:
+        # relative_to raises ValueError if path is not relative to root
+        msg = "Path is outside allowed root directory"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_PATH_OUTSIDE_ROOT,
+            message=msg,
+            context=security_context(path=str(resolved_path), root=str(resolved_root)),
+        ) from e
+
+    # Check for Windows reserved names in any path component
+    _check_windows_reserved_names(resolved_path)
+
+    # Check path depth
+    _check_path_depth(resolved_path, resolved_root)
+
+    return resolved_path
+
+
+def _check_windows_reserved_names(path: Path) -> None:
+    """Check if path contains Windows reserved device names.
+    
+    Windows reserves certain names (CON, PRN, AUX, NUL, COM1-9, LPT1-9) that
+    cannot be used as filenames. This applies even on Unix systems if files
+    will be synced to Windows.
+    
+    Args:
+        path: Path to check.
+        
+    Raises:
+        SecurityError: If path contains a reserved name.
+    """
+    for part in path.parts:
+        # Strip extension and check base name
+        name_upper = part.upper()
+        if "." in name_upper:
+            base_name = name_upper.split(".")[0]
+        else:
+            base_name = name_upper
+
+        if base_name in WINDOWS_RESERVED_NAMES:
+            msg = f"Path contains Windows reserved name: {part}"
+            raise SecurityError(
+                code=ErrorCode.SECURITY_PATH_RESERVED_NAME,
+                message=msg,
+                context=security_context(path=str(path), attack_type="windows_reserved_name"),
+            )
+
+
+def _check_path_depth(path: Path, root: Path, max_depth: int = 20) -> None:
+    """Check if path depth exceeds maximum allowed.
+    
+    Prevents DoS attacks via extremely deep directory structures.
+    
+    Args:
+        path: Path to check.
+        root: Root directory (depth is measured from here).
+        max_depth: Maximum allowed depth (default 20).
+        
+    Raises:
+        SecurityError: If path depth exceeds limit.
+    """
+    try:
+        relative = path.relative_to(root)
+        depth = len(relative.parts)
+        if depth > max_depth:
+            msg = f"Path depth {depth} exceeds maximum {max_depth}"
+            raise SecurityError(
+                code=ErrorCode.SECURITY_PATH_INVALID,
+                message=msg,
+                context=security_context(path=str(path), root=str(root)),
+            )
+    except ValueError:
+        # Path is not relative to root - already caught by safe_path
+        pass
+
+
+def is_safe_path(root: Path, candidate: Path | str) -> bool:
+    """Check if a path is safe without raising an exception.
+    
+    Convenience wrapper around safe_path() for cases where you want to check
+    validity without exception handling.
+    
+    Args:
+        root: Root directory.
+        candidate: Path to check.
+        
+    Returns:
+        True if path is safe, False otherwise.
+    """
+    try:
+        safe_path(root, candidate)
+        return True
+    except SecurityError:
+        return False
+
+
+def safe_join(root: Path, *parts: str) -> Path:
+    """Join path components safely within a root directory.
+    
+    Equivalent to root / part1 / part2 / ... but with safety validation.
+    
+    Args:
+        root: Root directory.
+        *parts: Path components to join.
+        
+    Returns:
+        Validated path within root.
+        
+    Raises:
+        SecurityError: If resulting path would be outside root.
+    """
+    if not parts:
+        return root
+
+    # Join all parts
+    candidate = Path(os.path.join(*parts))
+
+    # Validate
+    return safe_path(root, candidate, allow_create=True)
+
+
+def validate_filename(filename: str) -> str:
+    """Validate a filename for safety.
+    
+    Checks that filename:
+    - Contains no path separators (/ or \\)
+    - Contains no null bytes
+    - Is not empty
+    - Is not a reserved name
+    - Contains only valid characters
+    
+    Args:
+        filename: Filename to validate.
+        
+    Returns:
+        Validated filename.
+        
+    Raises:
+        SecurityError: If filename is invalid.
+    """
+    if not filename:
+        msg = "Filename cannot be empty"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_PATH_INVALID,
+            message=msg,
+            context={"filename": filename},
+        )
+
+    # Check for path separators
+    if "/" in filename or "\\" in filename:
+        msg = "Filename cannot contain path separators"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_PATH_INVALID,
+            message=msg,
+            context={"filename": filename},
+        )
+
+    # Check for null bytes
+    if "\x00" in filename:
+        msg = "Filename cannot contain null bytes"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_PATH_INVALID,
+            message=msg,
+            context={"filename": filename},
+        )
+
+    # Check for Windows reserved names
+    name_upper = filename.upper()
+    if "." in name_upper:
+        base_name = name_upper.split(".")[0]
+    else:
+        base_name = name_upper
+
+    if base_name in WINDOWS_RESERVED_NAMES:
+        msg = f"Filename is a Windows reserved name: {filename}"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_PATH_RESERVED_NAME,
+            message=msg,
+            context={"filename": filename},
+        )
+
+    return filename
+
+
+def ensure_parent_exists(path: Path, *, permissions: int = 0o755) -> None:
+    """Ensure parent directory of a path exists.
+    
+    Creates parent directories if they don't exist, with proper permissions.
+    
+    Args:
+        path: File path whose parent should exist.
+        permissions: Permissions for created directories (default 0o755).
+        
+    Raises:
+        SecurityError: If directory creation fails.
+    """
+    parent = path.parent
+    if parent.exists():
+        return
+
+    try:
+        parent.mkdir(parents=True, exist_ok=True, mode=permissions)
+    except OSError as e:
+        msg = f"Failed to create parent directory: {e}"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_WORKSPACE_INIT_FAILED,
+            message=msg,
+            context=security_context(path=str(parent)),
+        ) from e

contextual/security/sanitize.py

@@ -0,0 +1,349 @@
+"""Input sanitization utilities for preventing injection attacks.
+
+This module provides sanitization functions to prevent:
+- Unicode-based attacks (invisible characters, bidi overrides)
+- SQL injection (via identifier validation)
+- FTS5 injection (via query escaping)
+- Prompt injection (via content wrapping)
+
+All user-provided text inputs should be sanitized before use.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from re import Pattern
+
+from contextual.core.errors import ErrorCode, SecurityError
+
+
+# Compiled regex patterns for performance
+_SQL_IDENTIFIER_PATTERN: Pattern[str] = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+_FTS5_SPECIAL_CHARS: Pattern[str] = re.compile(r'["@:()-]')
+
+
+def strip_unicode_control_chars(text: str) -> str:
+    """Remove Unicode control characters from text.
+    
+    Strips characters in Unicode category Cf (Format, Other), which includes:
+    - Zero-width characters (ZWSP, ZWNJ, ZWJ)
+    - Bidirectional overrides (RLO, LRO, PDF)
+    - Other invisible formatting characters
+    
+    This prevents attacks like:
+    - Rules-File-Backdoor (hidden instructions visible only to LLMs)
+    - Visual spoofing via bidi overrides
+    - Zero-width character obfuscation
+    
+    Args:
+        text: Text to sanitize.
+        
+    Returns:
+        Text with control characters removed.
+        
+    Examples:
+        >>> text_with_zwsp = "Hello\\u200bWorld"
+        >>> strip_unicode_control_chars(text_with_zwsp)
+        'HelloWorld'
+        
+        >>> text_with_bidi = "normal\\u202eesreveR"  # RLO override
+        >>> strip_unicode_control_chars(text_with_bidi)
+        'normalesreveR'
+    """
+    # Filter out Unicode category Cf (Format, Other)
+    # This is fast because we're iterating in Python and unicodedata.category
+    # is a C function call
+    return "".join(char for char in text if unicodedata.category(char) != "Cf")
+
+
+def escape_fts5_match_query(query: str) -> str:
+    """Escape a query string for SQLite FTS5 MATCH operator.
+    
+    FTS5 has special syntax for queries (boolean AND/OR, phrase matching, etc.).
+    User input must be escaped to prevent injection and syntax errors.
+    
+    Strategy: Phrase-quote the entire query, and escape internal quotes.
+    This treats the query as a literal phrase search, which is safe and
+    matches user expectations for a "search box" input.
+    
+    FTS5 special characters that need escaping:
+    - " (phrase delimiter)
+    - @ (column filter)
+    - : (column filter)
+    - ( ) (grouping)
+    - - (exclusion)
+    
+    Args:
+        query: User-provided search query.
+        
+    Returns:
+        Escaped query safe for FTS5 MATCH.
+        
+    Examples:
+        >>> escape_fts5_match_query('normal query')
+        '"normal query"'
+        
+        >>> escape_fts5_match_query('query with "quotes"')
+        "\"query with \"\"quotes\"\"\""
+        
+        >>> escape_fts5_match_query('special:chars@here')
+        '"special:chars@here"'
+    """
+    # Escape internal quotes by doubling them
+    escaped = query.replace('"', '""')
+
+    # Wrap in phrase quotes
+    return f'"{escaped}"'
+
+
+def validate_sql_identifier(identifier: str) -> str:
+    """Validate a SQL identifier (table name, column name, etc.).
+    
+    Ensures identifier:
+    - Starts with letter or underscore
+    - Contains only letters, numbers, underscores
+    - Is not empty
+    - Is not too long (64 chars max for portability)
+    
+    This prevents SQL injection via identifier names.
+    
+    Args:
+        identifier: SQL identifier to validate.
+        
+    Returns:
+        Validated identifier.
+        
+    Raises:
+        SecurityError: If identifier is invalid.
+        
+    Examples:
+        >>> validate_sql_identifier('valid_name')
+        'valid_name'
+        
+        >>> validate_sql_identifier('also123valid')
+        'also123valid'
+        
+        >>> validate_sql_identifier('invalid-name')  # Contains hyphen
+        SecurityError: Invalid SQL identifier
+        
+        >>> validate_sql_identifier('123invalid')  # Starts with number
+        SecurityError: Invalid SQL identifier
+    """
+    if not identifier:
+        msg = "SQL identifier cannot be empty"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_SQL_INJECTION_ATTEMPT,
+            message=msg,
+            context={"identifier": identifier},
+        )
+
+    if len(identifier) > 64:
+        msg = "SQL identifier too long (max 64 chars)"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_SQL_INJECTION_ATTEMPT,
+            message=msg,
+            context={"identifier": identifier[:100]},
+        )
+
+    if not _SQL_IDENTIFIER_PATTERN.match(identifier):
+        msg = "Invalid SQL identifier (must start with letter/underscore, contain only alphanumeric/underscore)"
+        raise SecurityError(
+            code=ErrorCode.SECURITY_SQL_INJECTION_ATTEMPT,
+            message=msg,
+            context={"identifier": identifier},
+        )
+
+    return identifier
+
+
+def sanitize_user_input(text: str, *, max_length: int | None = None) -> str:
+    """Comprehensive sanitization of user-provided text.
+    
+    Applies multiple sanitization steps:
+    1. Strip Unicode control characters
+    2. Normalize whitespace
+    3. Trim to max length if specified
+    
+    Args:
+        text: User input to sanitize.
+        max_length: Optional maximum length (truncates if exceeded).
+        
+    Returns:
+        Sanitized text.
+    """
+    # Strip control characters
+    sanitized = strip_unicode_control_chars(text)
+
+    # Normalize whitespace (collapse multiple spaces, trim)
+    sanitized = " ".join(sanitized.split())
+
+    # Truncate if needed
+    if max_length is not None and len(sanitized) > max_length:
+        sanitized = sanitized[:max_length]
+
+    return sanitized
+
+
+def wrap_untrusted_content(content: str) -> str:
+    """Wrap potentially untrusted content in safety markers.
+    
+    When passing indexed code/content to LLMs via MCP tools, we wrap it
+    in markers to indicate it should be treated as data, not instructions.
+    
+    This mitigates indirect prompt injection where malicious code files
+    contain hidden instructions that the LLM might follow.
+    
+    Args:
+        content: Content to wrap.
+        
+    Returns:
+        Content wrapped in safety markers.
+        
+    Examples:
+        >>> wrap_untrusted_content('code snippet')
+        '<untrusted_content>\\ncode snippet\\n</untrusted_content>'
+    """
+    return f"<untrusted_content>\n{content}\n</untrusted_content>"
+
+
+def detect_prompt_injection_patterns(text: str) -> list[str]:
+    """Detect common prompt injection patterns in text.
+    
+    This is a heuristic check for known prompt injection techniques.
+    Not foolproof, but catches obvious attempts.
+    
+    Patterns checked:
+    - "Ignore previous instructions"
+    - "You are now in [X] mode"
+    - "Disregard your rules"
+    - "New instructions:"
+    - Excessive repetition (token flooding)
+    
+    Args:
+        text: Text to check.
+        
+    Returns:
+        List of detected pattern descriptions (empty if none found).
+    """
+    patterns_found: list[str] = []
+
+    text_lower = text.lower()
+
+    # Check for instruction override phrases
+    override_phrases = [
+        "ignore previous instructions",
+        "ignore all previous",
+        "disregard your rules",
+        "disregard all rules",
+        "new instructions:",
+        "you are now",
+        "enter god mode",
+        "enter admin mode",
+        "system: ",
+        "<system>",
+    ]
+
+    for phrase in override_phrases:
+        if phrase in text_lower:
+            patterns_found.append(f"Instruction override phrase: {phrase}")
+
+    # Check for excessive repetition (token flooding)
+    words = text.split()
+    if len(words) > 50:
+        # Check if any word is repeated excessively
+        word_counts: dict[str, int] = {}
+        for word in words:
+            word_lower = word.lower()
+            word_counts[word_lower] = word_counts.get(word_lower, 0) + 1
+
+        for word, count in word_counts.items():
+            if count > 10 and len(word) > 3:  # Word repeated >10 times
+                patterns_found.append(f"Excessive repetition: '{word}' repeated {count} times")
+
+    # Check for XML/HTML-like tags that might interfere with parsing
+    suspicious_tags = [
+        "<system", "<instruction", "<prompt", "<rule", "<command",
+        "</system", "</instruction", "</prompt", "</rule", "</command",
+    ]
+
+    for tag in suspicious_tags:
+        if tag in text_lower:
+            patterns_found.append(f"Suspicious tag: {tag}")
+
+    return patterns_found
+
+
+def sanitize_file_content(
+    content: str,
+    *,
+    strip_control: bool = True,
+    detect_injection: bool = True,
+    max_length: int | None = None,
+) -> tuple[str, list[str]]:
+    """Sanitize file content before indexing or display.
+    
+    Applies sanitization and optionally checks for injection patterns.
+    
+    Args:
+        content: File content to sanitize.
+        strip_control: Whether to strip Unicode control characters.
+        detect_injection: Whether to detect prompt injection patterns.
+        max_length: Optional maximum length.
+        
+    Returns:
+        Tuple of (sanitized_content, warnings).
+        Warnings list contains descriptions of detected issues.
+    """
+    warnings: list[str] = []
+
+    # Strip control characters if requested
+    if strip_control:
+        original_length = len(content)
+        content = strip_unicode_control_chars(content)
+        removed = original_length - len(content)
+        if removed > 0:
+            warnings.append(f"Removed {removed} Unicode control characters")
+
+    # Detect injection patterns if requested
+    if detect_injection:
+        patterns = detect_prompt_injection_patterns(content)
+        warnings.extend(patterns)
+
+    # Truncate if needed
+    if max_length is not None and len(content) > max_length:
+        content = content[:max_length]
+        warnings.append(f"Content truncated to {max_length} characters")
+
+    return content, warnings
+
+
+def escape_for_logging(text: str, max_length: int = 200) -> str:
+    """Escape text for safe inclusion in logs.
+    
+    Ensures logged text:
+    - Has no control characters
+    - Is truncated to reasonable length
+    - Has no newlines (prevents log injection)
+    
+    Args:
+        text: Text to escape.
+        max_length: Maximum length (default 200).
+        
+    Returns:
+        Escaped text safe for logging.
+    """
+    # Strip control characters
+    escaped = strip_unicode_control_chars(text)
+
+    # Replace newlines with spaces
+    escaped = escaped.replace("\n", " ").replace("\r", " ")
+
+    # Collapse multiple spaces
+    escaped = " ".join(escaped.split())
+
+    # Truncate
+    if len(escaped) > max_length:
+        escaped = escaped[:max_length] + "..."
+
+    return escaped