mcp-souschef 2.8.0__py3-none-any.whl → 3.2.0__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/validation.py

@@ -586,3 +586,56 @@ class ValidationEngine:
             elif result.level == ValidationLevel.INFO:
                 summary["info"] += 1
         return summary
+
+
+def _format_validation_results_summary(
+    conversion_type: str, summary: dict[str, int]
+) -> str:
+    """
+    Format validation results as a summary.
+
+    Args:
+        conversion_type: Type of conversion.
+        summary: Summary of validation results.
+
+    Returns:
+        Formatted summary output.
+
+    """
+    total_issues = summary["errors"] + summary["warnings"] + summary["info"]
+
+    if total_issues == 0:
+        return f"""# Validation Summary for {conversion_type} Conversion
+
+✅ **All validation checks passed!** No issues found.
+
+Errors: 0
+Warnings: 0
+Info: 0
+"""
+
+    # Determine status icon based on error/warning counts
+    if summary["errors"] > 0:
+        status_icon = "❌"
+    elif summary["warnings"] > 0:
+        status_icon = "⚠️"
+    else:
+        status_icon = "ℹ️"
+
+    # Determine status message based on error/warning counts
+    if summary["errors"] > 0:
+        status = "Failed"
+    elif summary["warnings"] > 0:
+        status = "Warning"
+    else:
+        status = "Passed with info"
+
+    return f"""# Validation Summary for {conversion_type} Conversion
+
+{status_icon} **Validation Results:**
+• Errors: {summary["errors"]}
+• Warnings: {summary["warnings"]}
+• Info: {summary["info"]}
+
+**Status:** {status}
+"""

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,
@@ -21,6 +22,11 @@ from souschef.core.errors import (
     validate_cookbook_structure,
     validate_directory_exists,
 )
+from souschef.core.metrics import (
+    ComplexityLevel,
+    EffortMetrics,
+    categorize_complexity,
+)
 from souschef.core.path_utils import _safe_join
 
 # Maximum length for attribute values in Chef attribute parsing
@@ -253,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)"
             )
 
@@ -978,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:
@@ -1496,13 +1508,56 @@ def _detect_patterns_from_content(content: str) -> list[str]:
     return patterns
 
 
-def _assess_complexity_from_resource_count(resource_count: int) -> tuple[str, str, str]:
-    """Assess complexity, effort, and risk based on resource count."""
+def _assess_complexity_from_resource_count(
+    resource_count: int,
+) -> tuple[ComplexityLevel, str, str]:
+    """
+    Assess complexity, effort estimate, and risk based on resource count.
+
+    Uses centralized metrics for consistent complexity categorization.
+
+    Args:
+        resource_count: Number of resources in cookbook
+
+    Returns:
+        Tuple of (complexity_level, effort_estimate_weeks, risk_level)
+
+    """
+    # Map resource count to complexity score (0-100 scale)
+    # 50+ resources = high complexity (70-100)
+    # 20-50 resources = medium complexity (30-69)
+    # <20 resources = low complexity (0-29)
     if resource_count > 50:
-        return "high", "4-6 weeks", "high"
-    elif resource_count < 20:
-        return "low", "1-2 weeks", "low"
-    return "medium", "2-3 weeks", "medium"
+        complexity_score = 80
+    elif resource_count > 30:
+        complexity_score = 50
+    elif resource_count >= 20:
+        complexity_score = 40
+    else:
+        complexity_score = 15
+
+    # Use centralized categorization
+    complexity_level = categorize_complexity(complexity_score)
+
+    # Estimate effort based on resource count and complexity
+    # Base: 0.2 days per resource (2.5 hours)
+    base_days = resource_count * 0.2
+    complexity_multiplier = 1 + (complexity_score / 100)
+    estimated_days = round(base_days * complexity_multiplier, 1)
+
+    # Create metrics object for consistent week calculation
+    metrics = EffortMetrics(estimated_days=estimated_days)
+    effort_estimate = metrics.estimated_weeks_range
+
+    # Risk mapping based on complexity level
+    if complexity_level == ComplexityLevel.HIGH:
+        risk_level = "high"
+    elif complexity_level == ComplexityLevel.MEDIUM:
+        risk_level = "medium"
+    else:
+        risk_level = "low"
+
+    return complexity_level, effort_estimate, risk_level
 
 
 def _analyse_application_cookbook(cookbook_path: Path, app_type: str) -> dict:
@@ -1536,10 +1591,14 @@ def _analyse_application_cookbook(cookbook_path: Path, app_type: str) -> dict:
                 # Silently skip malformed files
                 pass
 
-    # Assess complexity
+    # Assess complexity using centralized function
     resource_count = len(analysis["resources"])
-    complexity, effort, risk = _assess_complexity_from_resource_count(resource_count)
-    analysis["complexity"] = complexity
+    complexity_level, effort, risk = _assess_complexity_from_resource_count(
+        resource_count
+    )
+
+    # Convert complexity level enum to string for backward compatibility
+    analysis["complexity"] = complexity_level.value
     analysis["effort_estimate"] = effort
     analysis["risk_level"] = risk
 

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",
+]