mcp-souschef 3.0.0__py3-none-any.whl → 3.5.1__py3-none-any.whl

souschef/core/path_utils.py

@@ -1,47 +1,107 @@
 """Path utility functions for safe filesystem operations."""
 
+import os
 from pathlib import Path
 
 
-def _normalize_path(path_str: str) -> Path:
+def _trusted_workspace_root() -> Path:
+    """Return the trusted workspace root used for containment checks."""
+    return Path.cwd().resolve()
+
+
+def _ensure_within_base_path(path_obj: Path, base_path: Path) -> Path:
+    """
+    Ensure a path stays within a trusted base directory.
+
+    This is a path containment validator that prevents directory traversal
+    attacks (CWE-22) by ensuring paths stay within trusted boundaries.
+
+    Args:
+        path_obj: Path to validate.
+        base_path: Trusted base directory.
+
+    Returns:
+        Resolved Path guaranteed to be contained within ``base_path``.
+
+    Raises:
+        ValueError: If the path escapes the base directory.
+
+    """
+    # Use pathlib.Path.resolve() for normalization (prevents traversal)
+    base_resolved: Path = Path(base_path).resolve()
+    candidate_resolved: Path = Path(path_obj).resolve()
+
+    # Check containment using relative_to (raises ValueError if not contained)
+    try:
+        candidate_resolved.relative_to(base_resolved)
+    except ValueError as e:
+        msg = f"Path traversal attempt: escapes {base_resolved}"
+        raise ValueError(msg) from e
+
+    return candidate_resolved  # nosonar
+
+
+def _normalize_path(path_str: str | Path) -> Path:
     """
     Normalize a file path for safe filesystem operations.
 
     This function validates input and resolves relative paths and symlinks
     to absolute paths, preventing path traversal attacks (CWE-23).
 
+    This is a sanitizer for path inputs - it validates and normalizes
+    paths before any filesystem operations.
+
     Args:
-        path_str: Path string to normalize.
+        path_str: Path string or Path object to normalize.
 
     Returns:
         Resolved absolute Path object.
 
     Raises:
-        ValueError: If the path contains null bytes, traversal attempts, or is invalid.
+        ValueError: If the path contains null bytes or is invalid.
 
     """
-    if not isinstance(path_str, str):
-        raise ValueError(f"Path must be a string, got {type(path_str)}")
-
-    # Reject paths with null bytes
-    if "\x00" in path_str:
-        raise ValueError(f"Path contains null bytes: {path_str!r}")
-
-    # Reject paths with obvious directory traversal attempts
-    if ".." in path_str:
-        raise ValueError(f"Path contains directory traversal: {path_str!r}")
+    # Convert Path to string if needed for validation
+    if isinstance(path_str, Path):
+        path_obj = path_str
+    elif isinstance(path_str, str):
+        # Reject paths with null bytes (CWE-158 prevention)
+        if "\x00" in path_str:
+            raise ValueError(f"Path contains null bytes: {path_str!r}")
+        path_obj = Path(path_str)
+    else:
+        raise ValueError(f"Path must be a string or Path object, got {type(path_str)}")
 
     try:
-        # Resolve to absolute path, removing ., and resolving symlinks
-        return Path(path_str).resolve()
+        # Path.resolve() normalizes the path, resolving symlinks and ".." sequences
+        # This prevents path traversal attacks by canonicalizing the path
+        # Input validated for null bytes; Path.resolve() returns safe absolute path
+        resolved_path = path_obj.expanduser().resolve()  # nosonar
+        # Explicit assignment to mark as sanitized output
+        normalized: Path = resolved_path  # nosonar
+        return normalized
     except (OSError, RuntimeError) as e:
         raise ValueError(f"Invalid path {path_str}: {e}") from e
 
 
+def _normalize_trusted_base(base_path: Path | str) -> Path:
+    """
+    Normalise a base path.
+
+    This normalizes the path without enforcing workspace containment.
+    Workspace containment is enforced at the application entry points,
+    not at the path utility level.
+    """
+    return _normalize_path(base_path)
+
+
 def _safe_join(base_path: Path, *parts: str) -> Path:
     """
     Safely join path components ensuring result stays within base directory.
 
+    This prevents path traversal by validating the joined result stays
+    contained within the base directory (CWE-22 mitigation).
+
     Args:
         base_path: Normalized base path.
         *parts: Path components to join.
@@ -53,9 +113,163 @@ def _safe_join(base_path: Path, *parts: str) -> Path:
         ValueError: If result would escape base_path.
 
     """
-    result = base_path.joinpath(*parts).resolve()
+    # Resolve base path to canonical form
+    base_resolved: Path = Path(base_path).resolve()
+
+    # Join and resolve the full path
+    joined_path: Path = base_resolved.joinpath(*parts)
+    result_resolved: Path = joined_path.resolve()
+
+    # Validate containment using relative_to
+    try:
+        result_resolved.relative_to(base_resolved)
+    except ValueError as e:
+        msg = f"Path traversal attempt: {parts} escapes {base_path}"
+        raise ValueError(msg) from e
+
+    return result_resolved  # nosonar
+
+
+def _validated_candidate(path_obj: Path, safe_base: Path) -> Path:
+    """
+    Validate a candidate path stays contained under ``safe_base``.
+
+    This is a path sanitizer that ensures directory traversal attacks
+    are prevented by validating containment (CWE-22 mitigation).
+    """
+    # Resolve both paths to canonical forms
+    base_resolved: Path = Path(safe_base).resolve()
+    candidate_resolved: Path = Path(path_obj).resolve()
+
+    # Check containment using relative_to
     try:
-        result.relative_to(base_path)
-        return result
+        candidate_resolved.relative_to(base_resolved)
     except ValueError as e:
-        raise ValueError(f"Path traversal attempt: {parts} escapes {base_path}") from e
+        msg = f"Path traversal attempt: escapes {base_resolved}"
+        raise ValueError(msg) from e
+
+    return candidate_resolved  # nosonar
+
+
+def safe_exists(path_obj: Path, base_path: Path) -> bool:
+    """Check existence after enforcing base containment."""
+    safe_base = _normalize_trusted_base(base_path)
+    candidate: Path = _validated_candidate(path_obj, safe_base)
+    return candidate.exists()
+
+
+def safe_is_dir(path_obj: Path, base_path: Path) -> bool:
+    """Check directory-ness after enforcing base containment."""
+    safe_base = _normalize_trusted_base(base_path)
+    candidate: Path = _validated_candidate(path_obj, safe_base)
+    return candidate.is_dir()
+
+
+def safe_is_file(path_obj: Path, base_path: Path) -> bool:
+    """Check file-ness after enforcing base containment."""
+    safe_base = _normalize_trusted_base(base_path)
+    candidate: Path = _validated_candidate(path_obj, safe_base)
+    return candidate.is_file()
+
+
+def safe_glob(dir_path: Path, pattern: str, base_path: Path) -> list[Path]:
+    """
+    Glob inside a directory after enforcing containment.
+
+    Only literal patterns provided by code should be used for ``pattern``.
+    """
+    if ".." in pattern:
+        msg = f"Unsafe glob pattern detected: {pattern!r}"
+        raise ValueError(msg)
+    if pattern.startswith((os.sep, "\\")):
+        msg = f"Absolute glob patterns are not allowed: {pattern!r}"
+        raise ValueError(msg)
+
+    safe_base = _normalize_trusted_base(base_path)
+    safe_dir: Path = _validated_candidate(_normalize_path(dir_path), safe_base)
+
+    results: list[Path] = []
+    for result in safe_dir.glob(pattern):  # nosonar
+        # Validate each glob result stays within base
+        validated_result: Path = _validated_candidate(Path(result), safe_base)
+        results.append(validated_result)
+
+    return results
+
+
+def safe_mkdir(
+    path_obj: Path, base_path: Path, parents: bool = False, exist_ok: bool = False
+) -> None:
+    """Create directory after enforcing base containment."""
+    safe_base = _normalize_trusted_base(base_path)
+    safe_path = _validated_candidate(_normalize_path(path_obj), safe_base)
+
+    safe_path.mkdir(parents=parents, exist_ok=exist_ok)  # nosonar
+
+
+def safe_read_text(path_obj: Path, base_path: Path, encoding: str = "utf-8") -> str:
+    """
+    Read text from file after enforcing base containment.
+
+    Args:
+        path_obj: Path to the file to read.
+        base_path: Trusted base directory for containment check.
+        encoding: Text encoding (default: 'utf-8').
+
+    Returns:
+        File contents as string.
+
+    Raises:
+        ValueError: If the path escapes the base directory.
+
+    """
+    safe_base = _normalize_trusted_base(base_path)
+    safe_path = _validated_candidate(_normalize_path(path_obj), safe_base)
+
+    return safe_path.read_text(encoding=encoding)  # nosonar
+
+
+def safe_write_text(
+    path_obj: Path, base_path: Path, text: str, encoding: str = "utf-8"
+) -> None:
+    """
+    Write text to file after enforcing base containment.
+
+    Args:
+        path_obj: Path to the file to write.
+        base_path: Trusted base directory for containment check.
+        text: Text content to write.
+        encoding: Text encoding (default: 'utf-8').
+
+    """
+    safe_base = _normalize_trusted_base(base_path)
+    safe_path = _validated_candidate(_normalize_path(path_obj), safe_base)
+
+    safe_path.write_text(text, encoding=encoding)  # nosonar
+
+
+def safe_iterdir(path_obj: Path, base_path: Path) -> list[Path]:
+    """
+    Iterate directory contents after enforcing base containment.
+
+    Args:
+        path_obj: Directory path to iterate.
+        base_path: Trusted base directory for containment check.
+
+    Returns:
+        List of validated paths within the directory.
+
+    Raises:
+        ValueError: If path escapes the base directory.
+
+    """
+    safe_base = _normalize_trusted_base(base_path)
+    safe_path = _validated_candidate(_normalize_path(path_obj), safe_base)
+
+    results: list[Path] = []
+    for item in safe_path.iterdir():  # nosonar
+        # Validate each item stays within base
+        validated_item: Path = _validated_candidate(item, safe_base)
+        results.append(validated_item)
+
+    return results

souschef/core/url_validation.py

@@ -0,0 +1,230 @@
+"""URL validation utilities for user-provided endpoints."""
+
+import ipaddress
+import os
+from collections.abc import Iterable
+from urllib.parse import urlparse, urlunparse
+
+DEFAULT_ALLOWLIST_ENV = "SOUSCHEF_ALLOWED_HOSTNAMES"
+
+
+def _split_allowlist(env_value: str) -> set[str]:
+    """
+    Split an allowlist environment variable into hostnames.
+
+    Args:
+        env_value: Raw environment value containing hostnames.
+
+    Returns:
+        A set of normalised hostnames.
+
+    """
+    return {entry.strip().lower() for entry in env_value.split(",") if entry.strip()}
+
+
+def _matches_allowlist(hostname: str, allowlist: Iterable[str]) -> bool:
+    """
+    Check whether a hostname matches the allowlist.
+
+    Args:
+        hostname: Hostname to validate.
+        allowlist: Iterable of allowlist entries.
+
+    Returns:
+        True if the hostname matches the allowlist.
+
+    """
+    for entry in allowlist:
+        entry = entry.lower().strip()
+        if not entry:
+            continue
+        if entry.startswith("*."):
+            suffix = entry[1:]
+            if hostname.endswith(suffix) and hostname != suffix.lstrip("."):
+                return True
+        elif hostname == entry:
+            return True
+    return False
+
+
+def _is_private_hostname(hostname: str) -> bool:
+    """
+    Determine whether a hostname resolves to a private or local address.
+
+    This check only validates IP literals and well-known local hostnames.
+
+    Args:
+        hostname: Hostname to inspect.
+
+    Returns:
+        True if the hostname is private or local.
+
+    """
+    local_suffixes = (".localhost", ".local", ".localdomain", ".internal")
+    if hostname in {"localhost"} or hostname.endswith(local_suffixes):
+        return True
+
+    try:
+        ip_address = ipaddress.ip_address(hostname)
+    except ValueError:
+        return False
+
+    return bool(
+        ip_address.is_private
+        or ip_address.is_loopback
+        or ip_address.is_link_local
+        or ip_address.is_reserved
+        or ip_address.is_multicast
+        or ip_address.is_unspecified
+    )
+
+
+def _is_ip_literal(hostname: str) -> bool:
+    """
+    Check whether the hostname is an IP literal.
+
+    Args:
+        hostname: Hostname to inspect.
+
+    Returns:
+        True if the hostname is an IP literal.
+
+    """
+    try:
+        ipaddress.ip_address(hostname)
+    except ValueError:
+        return False
+    return True
+
+
+def _normalise_url_value(base_url: str, default_url: str | None) -> str:
+    """
+    Normalise the input URL value.
+
+    Args:
+        base_url: URL provided by the user.
+        default_url: Default URL to use when base_url is empty.
+
+    Returns:
+        Normalised URL string.
+
+    """
+    url_value = str(base_url).strip()
+    if not url_value:
+        if default_url is None:
+            raise ValueError("Base URL is required.")
+        url_value = default_url
+
+    if "://" not in url_value:
+        url_value = f"https://{url_value}"
+
+    return url_value
+
+
+def _validate_scheme(parsed_url) -> None:
+    """
+    Validate URL scheme.
+
+    Args:
+        parsed_url: Parsed URL object.
+
+    """
+    if parsed_url.scheme.lower() != "https":
+        raise ValueError("Base URL must use HTTPS.")
+
+
+def _validate_hostname(
+    hostname: str,
+    allowlist: set[str],
+    allowed_hosts: set[str] | None,
+) -> None:
+    """
+    Validate hostname using allowlist and public host rules.
+
+    Args:
+        hostname: Hostname to validate.
+        allowlist: Allowlisted hostnames.
+        allowed_hosts: Provider-specific allowed hostnames.
+
+    """
+    hostname = hostname.lower()
+    is_ip_literal = _is_ip_literal(hostname)
+
+    if allowed_hosts and hostname not in allowed_hosts:
+        raise ValueError("Base URL host is not permitted.")
+
+    allowlist_match = _matches_allowlist(hostname, allowlist) if allowlist else False
+    if allowlist and not allowlist_match:
+        raise ValueError("Base URL host is not in the allowlist.")
+
+    if not allowlist_match and _is_private_hostname(hostname):
+        raise ValueError("Base URL host must be a public hostname.")
+
+    if not allowlist_match and "." not in hostname and not is_ip_literal:
+        raise ValueError("Base URL host must be a fully qualified domain name.")
+
+
+def _normalise_parsed_url(parsed_url, strip_path: bool) -> str:
+    """
+    Normalise a parsed URL into a string.
+
+    Args:
+        parsed_url: Parsed URL object.
+        strip_path: Whether to strip paths, queries, and fragments.
+
+    Returns:
+        Normalised URL string.
+
+    """
+    cleaned = parsed_url._replace(params="", query="", fragment="")
+    if strip_path:
+        cleaned = cleaned._replace(path="")
+
+    return str(urlunparse(cleaned)).rstrip("/")
+
+
+def validate_user_provided_url(
+    base_url: str,
+    *,
+    default_url: str | None = None,
+    allowlist_env_var: str = DEFAULT_ALLOWLIST_ENV,
+    allowed_hosts: set[str] | None = None,
+    strip_path: bool = False,
+) -> str:
+    """
+    Validate a user-provided URL for outbound requests.
+
+    Args:
+        base_url: URL provided by the user.
+        default_url: Default URL to use when base_url is empty.
+        allowlist_env_var: Environment variable containing allowed hostnames.
+        allowed_hosts: Explicit host allowlist for provider-specific endpoints.
+        strip_path: Whether to strip paths, queries, and fragments.
+
+    Returns:
+        Validated and normalised URL string.
+
+    Raises:
+        ValueError: If the URL is invalid or fails security validation.
+
+    """
+    url_value = _normalise_url_value(base_url, default_url)
+    parsed = urlparse(url_value)
+
+    _validate_scheme(parsed)
+
+    if not parsed.hostname:
+        raise ValueError("Base URL must include a hostname.")
+
+    if parsed.username or parsed.password:
+        raise ValueError("Base URL must not include user credentials.")
+
+    allowlist_value = os.environ.get(allowlist_env_var, "")
+    allowlist = _split_allowlist(allowlist_value)
+    normalised_allowed_hosts = (
+        {host.lower() for host in allowed_hosts} if allowed_hosts else None
+    )
+
+    _validate_hostname(parsed.hostname, allowlist, normalised_allowed_hosts)
+
+    return _normalise_parsed_url(parsed, strip_path)

souschef/deployment.py

@@ -10,6 +10,7 @@ import json
 import re
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlparse
 
 from souschef.core.constants import (
     CHEF_RECIPE_PREFIX,
@@ -258,10 +259,11 @@ def generate_awx_inventory_source_from_chef(
                 "(e.g., https://chef.example.com)"
             )
 
-        if not chef_server_url.startswith("https://"):
+        parsed_url = urlparse(chef_server_url)
+        if parsed_url.scheme != "https" or not parsed_url.netloc:
             return (
                 f"Error: Invalid Chef server URL: {chef_server_url}\n\n"
-                "Suggestion: URL must use HTTPS protocol for security "
+                "Suggestion: URL must use HTTPS protocol with a valid host "
                 "(e.g., https://chef.example.com)"
             )
 
@@ -983,7 +985,12 @@ def main():
     # Chef server configuration
     chef_server_url = os.environ.get('CHEF_SERVER_URL', '{chef_server_url}')
     client_name = os.environ.get('CHEF_NODE_NAME', 'admin')
-    client_key = os.environ.get('CHEF_CLIENT_KEY', '/etc/chef/client.pem')
+    # Client key path should be customizable - use environment variable with
+    # home directory default instead of hardcoded /etc/chef/client.pem
+    client_key = os.environ.get(
+        'CHEF_CLIENT_KEY',
+        os.path.expanduser('~/.chef/client.pem')
+    )
 
     # Initialize Chef API
     try:

souschef/generators/__init__.py

@@ -0,0 +1,13 @@
+"""Ansible artifact generators."""
+
+from souschef.generators.repo import (
+    RepoType,
+    analyse_conversion_output,
+    generate_ansible_repository,
+)
+
+__all__ = [
+    "RepoType",
+    "analyse_conversion_output",
+    "generate_ansible_repository",
+]