scc-cli 1.4.0__py3-none-any.whl

scc_cli/evaluation/__init__.py

@@ -0,0 +1,27 @@
+"""Evaluation layer for SCC exception system.
+
+Provide pure functions for evaluating configs and applying exceptions.
+All IO is isolated to the stores layer.
+"""
+
+from scc_cli.evaluation.apply_exceptions import (
+    apply_local_overrides,
+    apply_policy_exceptions,
+)
+from scc_cli.evaluation.evaluate import evaluate
+from scc_cli.evaluation.models import (
+    BlockedItem,
+    Decision,
+    DeniedAddition,
+    EvaluationResult,
+)
+
+__all__ = [
+    "BlockedItem",
+    "Decision",
+    "DeniedAddition",
+    "EvaluationResult",
+    "apply_local_overrides",
+    "apply_policy_exceptions",
+    "evaluate",
+]

scc_cli/evaluation/apply_exceptions.py

@@ -0,0 +1,207 @@
+"""Apply exceptions to evaluation results.
+
+Contain the core exception application logic. All functions are pure (no IO)
+and operate on immutable data structures.
+
+Key rules:
+- apply_policy_exceptions() can override ANY block (security or delegation)
+- apply_local_overrides() can ONLY override DELEGATION blocks
+- Expired exceptions have no effect
+- Wildcard patterns (e.g., "jira-*") are supported
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from datetime import datetime, timezone
+from typing import Literal
+
+from scc_cli.evaluation.models import (
+    Decision,
+    EvaluationResult,
+)
+from scc_cli.models.exceptions import AllowTargets, BlockReason
+from scc_cli.models.exceptions import Exception as SccException
+from scc_cli.utils.ttl import format_relative
+
+
+def _is_expired(exception: SccException) -> bool:
+    """Check if an exception has expired."""
+    try:
+        expires = datetime.fromisoformat(exception.expires_at.replace("Z", "+00:00"))
+        return expires <= datetime.now(timezone.utc)
+    except (ValueError, AttributeError):
+        return True  # Invalid expiration = expired
+
+
+def _matches_target(pattern: str, target: str) -> bool:
+    """Check if a pattern matches a target, supporting wildcards."""
+    # Exact match first
+    if pattern == target:
+        return True
+    # Wildcard match (fnmatch supports * and ?)
+    return fnmatch.fnmatch(target, pattern)
+
+
+def _get_allowed_targets(
+    allow: AllowTargets, target_type: Literal["plugin", "mcp_server", "base_image"]
+) -> list[str]:
+    """Get the list of allowed targets for a specific type."""
+    if target_type == "plugin":
+        return allow.plugins or []
+    elif target_type == "mcp_server":
+        return allow.mcp_servers or []
+    elif target_type == "base_image":
+        return allow.base_images or []
+    return []
+
+
+def _find_matching_exception(
+    target: str,
+    target_type: Literal["plugin", "mcp_server", "base_image"],
+    exceptions: list[SccException],
+) -> SccException | None:
+    """Find the first non-expired exception that matches the target.
+
+    Prefers exact matches over wildcard matches.
+    """
+    exact_match = None
+    wildcard_match = None
+
+    for exc in exceptions:
+        if _is_expired(exc):
+            continue
+
+        allowed = _get_allowed_targets(exc.allow, target_type)
+        for pattern in allowed:
+            if pattern == target:
+                exact_match = exc
+                break  # Exact match found, use it
+            elif _matches_target(pattern, target) and wildcard_match is None:
+                wildcard_match = exc
+
+        if exact_match:
+            break
+
+    return exact_match or wildcard_match
+
+
+def _calculate_expires_in(exception: SccException) -> str | None:
+    """Calculate the relative time until expiration."""
+    try:
+        expires = datetime.fromisoformat(exception.expires_at.replace("Z", "+00:00"))
+        return format_relative(expires)
+    except (ValueError, AttributeError):
+        return None
+
+
+def apply_policy_exceptions(
+    result: EvaluationResult,
+    exceptions: list[SccException],
+) -> EvaluationResult:
+    """Apply policy exceptions to an evaluation result.
+
+    Policy exceptions can override ANY block - both security blocks and
+    delegation denials. This is the first layer of exception application.
+
+    Args:
+        result: The current evaluation result
+        exceptions: List of policy exceptions to apply
+
+    Returns:
+        New EvaluationResult with matching items removed and decisions added
+    """
+    new_result = result.copy()
+
+    # Process blocked items (security blocks)
+    remaining_blocked = []
+    for blocked in result.blocked_items:
+        matching_exc = _find_matching_exception(blocked.target, blocked.target_type, exceptions)
+        if matching_exc:
+            # Create decision record
+            decision = Decision(
+                item=blocked.target,
+                item_type=blocked.target_type,
+                result="allowed",
+                reason="Policy exception applied",
+                source="policy",
+                exception_id=matching_exc.id,
+                expires_in=_calculate_expires_in(matching_exc),
+            )
+            new_result.decisions.append(decision)
+        else:
+            remaining_blocked.append(blocked)
+
+    new_result.blocked_items = remaining_blocked
+
+    # Process denied additions (delegation blocks)
+    remaining_denied = []
+    for denied in result.denied_additions:
+        matching_exc = _find_matching_exception(denied.target, denied.target_type, exceptions)
+        if matching_exc:
+            decision = Decision(
+                item=denied.target,
+                item_type=denied.target_type,
+                result="allowed",
+                reason="Policy exception applied",
+                source="policy",
+                exception_id=matching_exc.id,
+                expires_in=_calculate_expires_in(matching_exc),
+            )
+            new_result.decisions.append(decision)
+        else:
+            remaining_denied.append(denied)
+
+    new_result.denied_additions = remaining_denied
+
+    return new_result
+
+
+def apply_local_overrides(
+    result: EvaluationResult,
+    overrides: list[SccException],
+    source: Literal["repo", "user"],
+) -> EvaluationResult:
+    """Apply local overrides to an evaluation result.
+
+    Local overrides can ONLY override DELEGATION blocks (denied additions).
+    Security blocks are immutable to local overrides - this is a critical
+    security boundary.
+
+    Args:
+        result: The current evaluation result
+        overrides: List of local overrides to apply
+        source: Where the overrides came from ("repo" or "user")
+
+    Returns:
+        New EvaluationResult with matching denied additions removed and decisions added
+    """
+    new_result = result.copy()
+
+    # ONLY process denied additions (delegation blocks)
+    # Security blocks (blocked_items) are NEVER affected by local overrides
+    remaining_denied = []
+    for denied in result.denied_additions:
+        # Only delegation blocks can be overridden locally
+        if denied.reason != BlockReason.DELEGATION:
+            remaining_denied.append(denied)
+            continue
+
+        matching_exc = _find_matching_exception(denied.target, denied.target_type, overrides)
+        if matching_exc:
+            decision = Decision(
+                item=denied.target,
+                item_type=denied.target_type,
+                result="allowed",
+                reason="Local override applied",
+                source=source,
+                exception_id=matching_exc.id,
+                expires_in=_calculate_expires_in(matching_exc),
+            )
+            new_result.decisions.append(decision)
+        else:
+            remaining_denied.append(denied)
+
+    new_result.denied_additions = remaining_denied
+
+    return new_result

scc_cli/evaluation/evaluate.py

@@ -0,0 +1,97 @@
+"""Bridge function to convert EffectiveConfig to EvaluationResult.
+
+Provide the evaluate() function that converts the governance layer models
+(profiles.py) to the exception system models (evaluation/models.py) with
+proper BlockReason annotations.
+
+This is a pure function with no IO - all input comes from the EffectiveConfig
+parameter and output is a new EvaluationResult.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from scc_cli.evaluation.models import (
+    BlockedItem,
+    DeniedAddition,
+    EvaluationResult,
+)
+from scc_cli.models.exceptions import BlockReason
+
+if TYPE_CHECKING:
+    from scc_cli.profiles import EffectiveConfig
+
+
+def evaluate(config: EffectiveConfig) -> EvaluationResult:
+    """Convert EffectiveConfig to EvaluationResult with BlockReason annotations.
+
+    This function bridges the governance layer (profiles.py models) to the
+    exception system (evaluation/models.py) by converting:
+
+    - profiles.BlockedItem -> evaluation.BlockedItem with BlockReason.SECURITY
+    - profiles.DelegationDenied -> evaluation.DeniedAddition with BlockReason.DELEGATION
+
+    Args:
+        config: The EffectiveConfig from the profile merge process
+
+    Returns:
+        EvaluationResult with properly annotated blocked items and denied additions
+    """
+    blocked_items: list[BlockedItem] = []
+    denied_additions: list[DeniedAddition] = []
+
+    # Convert blocked items (security blocks)
+    for blocked in config.blocked_items:
+        target_type = _normalize_target_type(blocked.target_type)
+        message = f"Blocked by security pattern '{blocked.blocked_by}'"
+
+        blocked_items.append(
+            BlockedItem(
+                target=blocked.item,
+                target_type=target_type,
+                reason=BlockReason.SECURITY,
+                message=message,
+            )
+        )
+
+    # Convert denied additions (delegation denials)
+    for denied in config.denied_additions:
+        target_type = _normalize_target_type(denied.target_type)
+        # Use the original reason which contains useful context
+        message = denied.reason
+
+        denied_additions.append(
+            DeniedAddition(
+                target=denied.item,
+                target_type=target_type,
+                reason=BlockReason.DELEGATION,
+                message=message,
+            )
+        )
+
+    return EvaluationResult(
+        blocked_items=blocked_items,
+        denied_additions=denied_additions,
+        decisions=[],  # Decisions are populated by apply_*_exceptions functions
+        warnings=[],
+    )
+
+
+def _normalize_target_type(
+    target_type: str,
+) -> Literal["plugin", "mcp_server", "base_image"]:
+    """Normalize target_type to valid literal values.
+
+    Args:
+        target_type: The target type from profiles.py models
+
+    Returns:
+        Normalized target type literal
+    """
+    if target_type == "mcp_server":
+        return "mcp_server"
+    elif target_type == "base_image":
+        return "base_image"
+    else:
+        return "plugin"  # Default to plugin for unknown types

scc_cli/evaluation/models.py

@@ -0,0 +1,80 @@
+"""Define data models for the evaluation layer.
+
+Represent the results of evaluating configs and applying exceptions.
+All models are immutable and support the pure functional evaluation approach.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from scc_cli.models.exceptions import BlockReason
+
+
+@dataclass(frozen=True)
+class BlockedItem:
+    """Represents an item blocked by security policy.
+
+    Security blocks can only be overridden by policy exceptions.
+    Local overrides have no effect on these.
+    """
+
+    target: str  # The blocked item (plugin name, MCP server, image ref)
+    target_type: Literal["plugin", "mcp_server", "base_image"]
+    reason: BlockReason  # Always SECURITY for blocked items
+    message: str  # Human-readable explanation
+
+
+@dataclass(frozen=True)
+class DeniedAddition:
+    """Represents an addition denied by delegation policy.
+
+    Delegation denials can be overridden by either policy exceptions
+    or local overrides (from repo or user stores).
+    """
+
+    target: str  # The denied item
+    target_type: Literal["plugin", "mcp_server", "base_image"]
+    reason: BlockReason  # Always DELEGATION for denied additions
+    message: str  # Human-readable explanation
+
+
+@dataclass(frozen=True)
+class Decision:
+    """Records a decision made when applying an exception.
+
+    Captures the full context of why an item was allowed or blocked,
+    including the exception that allowed it and when it expires.
+    """
+
+    item: str  # The item being decided on
+    item_type: Literal["plugin", "mcp_server", "base_image"]
+    result: Literal["allowed", "blocked", "denied"]
+    reason: str  # Human-readable explanation
+    source: Literal["policy", "org", "team", "project", "repo", "user"] | None
+    exception_id: str | None  # ID of the exception that allowed it
+    expires_in: str | None  # Relative time like "7h45m"
+
+
+@dataclass
+class EvaluationResult:
+    """The complete result of evaluating a config with exceptions applied.
+
+    Maintains lists of blocked items, denied additions, and decisions.
+    This is the primary data structure passed through the evaluation pipeline.
+    """
+
+    blocked_items: list[BlockedItem] = field(default_factory=list)
+    denied_additions: list[DeniedAddition] = field(default_factory=list)
+    decisions: list[Decision] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def copy(self) -> EvaluationResult:
+        """Create a shallow copy for immutable-style updates."""
+        return EvaluationResult(
+            blocked_items=list(self.blocked_items),
+            denied_additions=list(self.denied_additions),
+            decisions=list(self.decisions),
+            warnings=list(self.warnings),
+        )

scc_cli/exit_codes.py

@@ -0,0 +1,55 @@
+"""
+Exit codes for SCC CLI.
+
+Standardized exit codes following Unix conventions with semantic meaning.
+All commands MUST use these constants for consistency.
+
+Note: Click/Typer argument parsing errors (EXIT_USAGE) occur before
+commands run, so they emit to stderr without JSON envelope.
+"""
+
+# Success
+EXIT_SUCCESS = 0  # Command completed successfully
+
+# Errors (1-6)
+EXIT_ERROR = 1  # General/unexpected error
+EXIT_USAGE = 2  # Invalid usage/arguments (Click default)
+EXIT_CONFIG = 3  # Config or network error
+EXIT_VALIDATION = 4  # Validation failed (schema, semantic checks)
+EXIT_PREREQ = 5  # Prerequisites not met (Docker, Git)
+EXIT_GOVERNANCE = 6  # Blocked by governance policy
+
+# Cancellation (SIGINT convention)
+EXIT_CANCELLED = 130  # User cancelled operation (SIGINT)
+
+# Map exception types to exit codes (for json_command decorator)
+# Note: Import from errors module only when needed to avoid circular imports
+EXIT_CODE_MAP = {
+    "ConfigError": EXIT_CONFIG,
+    "ProfileNotFoundError": EXIT_CONFIG,
+    "ValidationError": EXIT_VALIDATION,
+    "PolicyViolationError": EXIT_GOVERNANCE,
+    "PrerequisiteError": EXIT_PREREQ,
+    "DockerNotFoundError": EXIT_PREREQ,
+    "GitNotFoundError": EXIT_PREREQ,
+    "UsageError": EXIT_USAGE,
+}
+
+
+def get_exit_code_for_exception(exc: Exception) -> int:
+    """Return the appropriate exit code for an exception type.
+
+    Walk up the exception's MRO to find a matching type in EXIT_CODE_MAP.
+    Fall back to EXIT_ERROR if no specific mapping exists.
+
+    Args:
+        exc: The exception instance to map.
+
+    Returns:
+        The standardized exit code for the exception type.
+    """
+    for cls in type(exc).__mro__:
+        if cls.__name__ in EXIT_CODE_MAP:
+            return EXIT_CODE_MAP[cls.__name__]
+
+    return EXIT_ERROR