deployproof 0.1.0__py3-none-any.whl

deployproof/reporter.py

@@ -0,0 +1,281 @@
+"""Terminal output reporter for DeployProof."""
+
+from pathlib import Path
+from typing import List, Optional
+
+from deployproof.dependencies import DependencyScanSummary
+from deployproof.mutator import MutationResult
+from deployproof.secrets import SecretsScanResult
+from deployproof.symlinks import SymlinkScanResult
+
+LARGE_FILE_LOC_THRESHOLD = 300
+
+
+def format_report(
+    result: MutationResult,
+    target_files: List[Path],
+    secrets_result: Optional[SecretsScanResult] = None,
+    symlink_result: Optional[SymlinkScanResult] = None,
+    dependency_result: Optional[DependencyScanSummary] = None,
+    repo_root: Optional[Path] = None,
+    threshold: float = 80.0,
+) -> str:
+    """Format mutation testing results, secrets scan, symlink escape, and slopsquatting checks as terminal output."""
+    lines: List[str] = []
+    lines.append("DeployProof - LOCAL PRE-CHECK (approximate) - not the verified score")
+    lines.append("=" * 68)
+
+    root = (repo_root or Path.cwd()).resolve()
+
+    # Scope section
+    file_count = len(target_files)
+    lines.append(f"\nTarget Scope ({file_count} file{'s' if file_count != 1 else ''} evaluated):")
+    if target_files:
+        for f in target_files:
+            try:
+                rel = f.relative_to(root)
+            except ValueError:
+                rel = f
+            try:
+                loc = len(f.read_text(encoding="utf-8", errors="replace").splitlines())
+            except Exception:
+                loc = 0
+
+            if loc >= LARGE_FILE_LOC_THRESHOLD:
+                lines.append(
+                    f"  * {rel} ({loc} LOC) - [!] Large file: pre-check may take several minutes."
+                )
+            else:
+                lines.append(f"  * {rel}")
+    else:
+        lines.append("  (No modified Python files in scope)")
+
+    # Symlink & Sandbox Escape Scan section
+    lines.append("\nSymlink & Sandbox Escape Scan (CWE-61/CWE-451):")
+    if symlink_result and symlink_result.escape_findings:
+        escape_count = len(symlink_result.escape_findings)
+        lines.append(
+            f"  [!] {escape_count} sandbox-escape symlink{'s' if escape_count != 1 else ''} detected:"
+        )
+        for idx, finding in enumerate(symlink_result.escape_findings, 1):
+            try:
+                rel_sym = finding.symlink_path.relative_to(root)
+            except ValueError:
+                rel_sym = finding.symlink_path
+            lines.append(f"\n    [{idx}] {rel_sym} -> {finding.link_target_raw}")
+            lines.append(f"        Apparent Path:   {rel_sym}")
+            lines.append(f"        Resolved Target: {finding.resolved_target} (Exists on disk: {finding.target_exists})")
+            lines.append("        Severity:        CRITICAL (Escapes repository sandbox)")
+            lines.append(f"        Note:            {finding.description}")
+    elif symlink_result and symlink_result.safe_symlinks:
+        safe_count = len(symlink_result.safe_symlinks)
+        lines.append(
+            f"  Clean: No sandbox-escape symlinks detected across {symlink_result.files_scanned} session files ({safe_count} safe in-repo symlink{'s' if safe_count != 1 else ''} verified)."
+        )
+    else:
+        scanned_count = symlink_result.files_scanned if symlink_result else file_count
+        lines.append(
+            f"  Clean: No symlinks or sandbox-escape traversal links detected across {scanned_count} session file{'s' if scanned_count != 1 else ''}."
+        )
+
+    # Secrets scan section
+    lines.append("\nSecrets & Credentials Pre-Push Scan:")
+    if secrets_result and secrets_result.findings:
+        findings_count = len(secrets_result.findings)
+        lines.append(
+            f"  [!] {findings_count} potential secret/credential finding{'s' if findings_count != 1 else ''} detected:"
+        )
+        for idx, finding in enumerate(secrets_result.findings, 1):
+            try:
+                rel_path = finding.file_path.relative_to(root)
+            except ValueError:
+                rel_path = finding.file_path
+            lines.append(f"\n    [{idx}] {rel_path}:{finding.line_number} [{finding.rule_name}]")
+            lines.append(f"        Redacted: {finding.redacted_value}")
+            if finding.snippet:
+                lines.append(f"        Snippet:  {finding.snippet}")
+            lines.append(f"        Note:     {finding.description}")
+    else:
+        scanned_count = secrets_result.files_scanned if secrets_result else file_count
+        lines.append(
+            f"  Clean: No hardcoded secrets or tracked .env files detected across {scanned_count} session file{'s' if scanned_count != 1 else ''}."
+        )
+
+    # Dependency & Slopsquatting Scan section
+    lines.append("\nDependency & Slopsquatting Scan (PyPI Registry & Age Analysis):")
+    if dependency_result and (dependency_result.high_risk_count > 0 or dependency_result.medium_risk_count > 0):
+        flagged_count = dependency_result.high_risk_count + dependency_result.medium_risk_count
+        lines.append(
+            f"  [!] {flagged_count} suspicious dependency finding{'s' if flagged_count != 1 else ''} detected:"
+        )
+        idx = 1
+        for finding in dependency_result.findings:
+            if finding.status in ("HIGH_RISK", "MEDIUM_RISK"):
+                try:
+                    rel_src = finding.source_file.relative_to(root)
+                except ValueError:
+                    rel_src = finding.source_file
+                src_str = f"{rel_src}:{finding.lineno}" if finding.lineno else str(rel_src)
+                lines.append(f"\n    [{idx}] {finding.package_name} [{finding.status}]")
+                lines.append(f"        Source:         {src_str} ({finding.source_type})")
+                if finding.status == "HIGH_RISK":
+                    lines.append("        Classification: HIGH RISK (Package does NOT exist on PyPI)")
+                elif finding.status == "MEDIUM_RISK":
+                    lines.append(
+                        f"        Classification: MEDIUM RISK (Registered {finding.age_days} day{'s' if finding.age_days != 1 else ''} ago, first published {finding.first_release_date})"
+                    )
+                lines.append(f"        Note:           {finding.details}")
+                idx += 1
+
+    elif dependency_result and dependency_result.total_scanned > 0:
+        lines.append(
+            f"  Clean: {dependency_result.ok_count} external package{'s' if dependency_result.ok_count != 1 else ''} verified on PyPI (0 hallucinated, 0 recently registered)."
+        )
+    else:
+        scanned_count = secrets_result.files_scanned if secrets_result else file_count
+        lines.append(
+            f"  Clean: No new external packages introduced across {scanned_count} session file{'s' if scanned_count != 1 else ''}."
+        )
+
+    # UNKNOWN findings (network/registry query errors)
+    if dependency_result and dependency_result.unknown_count > 0:
+        lines.append(
+            f"\n  [?] {dependency_result.unknown_count} unverified dependency check{'s' if dependency_result.unknown_count != 1 else ''} (Network / registry query error):"
+        )
+        for finding in dependency_result.findings:
+            if finding.status == "UNKNOWN":
+                try:
+                    rel_src = finding.source_file.relative_to(root)
+                except ValueError:
+                    rel_src = finding.source_file
+                src_str = f"{rel_src}:{finding.lineno}" if finding.lineno else str(rel_src)
+                lines.append(f"    * {finding.package_name} (Source: {src_str}) - {finding.details}")
+
+    # Unscanned dependency sources (seen, not checked)
+    if dependency_result and dependency_result.unscanned_count > 0:
+        lines.append(
+            f"\n  [!] {dependency_result.unscanned_count} unscanned dependency source{'s' if dependency_result.unscanned_count != 1 else ''} (seen, not checked):"
+        )
+        for finding in dependency_result.findings:
+            if finding.status == "UNSCANNED":
+                try:
+                    rel_src = finding.source_file.relative_to(root)
+                except ValueError:
+                    rel_src = finding.source_file
+                src_str = f"{rel_src}:{finding.lineno}" if finding.lineno else str(rel_src)
+                lines.append(f"    * {finding.import_name} (Source: {src_str}) - {finding.details}")
+
+    # Score section
+    lines.append("\nLocal Pre-Check Mutation Verification:")
+    if result.total_mutants == 0:
+        lines.append("  Mutants Generated: 0 (No mutable AST locations found)")
+        lines.append("  Approx Score:      100.0%")
+    else:
+        if result.untested_files:
+            status_tag = f"FAILED (0 tests collected for {len(result.untested_files)} file{'s' if len(result.untested_files) != 1 else ''})"
+        elif result.mutation_score < threshold:
+            status_tag = f"FAILED (score {result.mutation_score:.1f}% below {threshold:.1f}%)"
+        elif result.survived_mutants:
+            status_tag = f"PASSED (with {len(result.survived_mutants)} surviving mutant{'s' if len(result.survived_mutants) != 1 else ''})"
+        elif result.skipped_constructs:
+            status_tag = f"PARTIALLY VERIFIED ({len(result.skipped_constructs)} construct{'s' if len(result.skipped_constructs) != 1 else ''} skipped)"
+        else:
+            status_tag = "PASSED"
+
+        lines.append(
+            f"  Score:  {result.mutation_score:.1f}% ({result.killed_mutants}/{result.total_mutants} mutants killed)"
+        )
+        lines.append(f"  Status: {status_tag} (threshold: {threshold:.1f}%)")
+        lines.append(f"  Time:   {result.duration_seconds:.2f}s")
+
+    # Untested files warning section
+    if result.untested_files:
+        lines.append(
+            f"\n[!] Untested Files ({len(result.untested_files)} file{'s' if len(result.untested_files) != 1 else ''} with 0 tests collected):"
+        )
+        for f in result.untested_files:
+            try:
+                rel_f = f.relative_to(root)
+            except ValueError:
+                rel_f = f
+            lines.append(f"  * {rel_f} (0 tests ran against this file - all mutations survived)")
+
+    # Runner errors section
+    if result.runner_errors:
+        lines.append(
+            f"\nRunner Errors ({len(result.runner_errors)} error{'s' if len(result.runner_errors) != 1 else ''} excluded from score):"
+        )
+        for mutant, err_msg in result.runner_errors:
+            try:
+                rel_f = mutant.file_path.relative_to(root)
+            except ValueError:
+                rel_f = mutant.file_path
+            lines.append(f"  * {rel_f}:{mutant.line_number} [{err_msg}]")
+
+    # Skipped Constructs Section (Always shown alongside score)
+    skipped_count = len(result.skipped_constructs)
+    if result.skipped_constructs:
+        lines.append(
+            f"\nSkipped Constructs ({skipped_count} line{'s' if skipped_count != 1 else ''} skipped - not verified by Tier 1):"
+        )
+        for i, s in enumerate(result.skipped_constructs, 1):
+            try:
+                rel_f = s.file_path.relative_to(root)
+            except ValueError:
+                rel_f = s.file_path
+            lines.append(f"  * {rel_f}:{s.line_number} [{s.construct_name}]")
+            if s.snippet:
+                lines.append(f"    Code: {s.snippet}")
+            lines.append(f"    Note: {s.description}")
+    else:
+        lines.append("\nSkipped Constructs: None (No known unsupported constructs detected)")
+
+    # Surviving mutants section
+    if result.survived_mutants:
+        lines.append(
+            f"\nSurviving Mutants ({len(result.survived_mutants)} unverified change{'s' if len(result.survived_mutants) != 1 else ''}):"
+        )
+        for i, m in enumerate(result.survived_mutants, 1):
+            try:
+                rel_f = m.file_path.relative_to(root)
+            except ValueError:
+                rel_f = m.file_path
+            lines.append(f"\n  [{i}] {rel_f}:{m.line_number}")
+            lines.append(f"      Mutation: {m.description}")
+            if m.original_line:
+                lines.append(f"      Original: {m.original_line}")
+            if m.mutated_line:
+                lines.append(f"      Mutated:  {m.mutated_line}")
+    else:
+        lines.append("\nSurviving Mutants: None (All generated mutants caught by test suite)")
+
+    lines.append("\n" + "=" * 68)
+    lines.append("Notice: Local pre-check only. Full verified score runs in CI on push (via mutmut).")
+    if symlink_result and symlink_result.escape_findings:
+        lines.append(
+            f"SECURITY ALERT: {len(symlink_result.escape_findings)} symlink(s) escape repository sandbox. Do not approve or push."
+        )
+    elif dependency_result and dependency_result.high_risk_count > 0:
+        lines.append(
+            f"SECURITY ALERT: {dependency_result.high_risk_count} non-existent / hallucinated package(s) detected. Fix imports before pushing."
+        )
+    elif result.untested_files:
+        lines.append(
+            f"Pre-check FAILED: {len(result.untested_files)} file(s) have 0 tests. Write tests for these files before pushing."
+        )
+    elif result.mutation_score < threshold:
+        lines.append(
+            f"Pre-check FAILED: Score {result.mutation_score:.1f}% is below threshold {threshold:.1f}% ({len(result.survived_mutants)} surviving mutants)."
+        )
+    elif result.survived_mutants:
+        lines.append(
+            f"Pre-check PASSED ({result.mutation_score:.1f}% >= {threshold:.1f}%), with {len(result.survived_mutants)} surviving mutant(s) flagged."
+        )
+    elif result.skipped_constructs:
+        lines.append(
+            f"Pre-check passed on basic operators, but {skipped_count} unsupported construct(s) were skipped. Run in CI for full verification."
+        )
+    else:
+        lines.append("Pre-check clean: 100% of tested basic mutations caught.")
+
+    return "\n".join(lines)

deployproof/secrets.py

@@ -0,0 +1,221 @@
+"""Secrets and hardcoded credentials scanner for DeployProof."""
+
+import math
+import re
+import time
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Pattern, Tuple
+
+ENV_FILE_NAMES = {
+    ".env",
+    ".env.local",
+    ".env.production",
+    ".env.staging",
+    ".env.development",
+    ".env.secret",
+    ".env.prod",
+}
+
+# Regex patterns for well-known API keys and credentials
+KNOWN_PATTERNS: List[Tuple[str, Pattern[str], str]] = [
+    (
+        "OpenAI / Anthropic API Key",
+        re.compile(r"\b(sk-[a-zA-Z0-9_-]{20,})\b"),
+        "Likely hardcoded OpenAI / Anthropic API key",
+    ),
+    (
+        "AWS Access Key ID",
+        re.compile(r"\b(AKIA[0-9A-Z]{16})\b"),
+        "Likely hardcoded AWS Access Key ID",
+    ),
+    (
+        "AWS Secret Access Key",
+        re.compile(r"(?i)\b(?:aws_secret_access_key|aws_secret_key)\s*[:=]\s*[\"']?([A-Za-z0-9/+=]{40})[\"']?"),
+        "Likely hardcoded AWS Secret Access Key",
+    ),
+    (
+        "GitHub Token",
+        re.compile(r"\b(gh[pousr]_[A-Za-z0-9_]{36,255}|github_pat_[A-Za-z0-9_]{50,})\b"),
+        "Likely hardcoded GitHub Personal Access Token",
+    ),
+    (
+        "Google API Key",
+        re.compile(r"\b(AIza[0-9A-Za-z-_]{35})\b"),
+        "Likely hardcoded Google / AI Studio API key",
+    ),
+    (
+        "Slack Token",
+        re.compile(r"\b(xox[baprs]-[0-9a-zA-Z-]{10,48})\b"),
+        "Likely hardcoded Slack OAuth / Bot token",
+    ),
+    (
+        "Stripe Secret Key",
+        re.compile(r"\b([sr]k_(?:live|test)_[0-9a-zA-Z]{24,})\b"),
+        "Likely hardcoded Stripe API Key",
+    ),
+    (
+        "HuggingFace Token",
+        re.compile(r"\b(hf_[a-zA-Z0-9]{34,})\b"),
+        "Likely hardcoded HuggingFace API Token",
+    ),
+    (
+        "Private Key Header",
+        re.compile(r"(-----BEGIN [A-Z ]*PRIVATE KEY-----)"),
+        "Unencrypted Private Key Block",
+    ),
+]
+
+GENERIC_ASSIGNMENT_PATTERN = re.compile(
+    r"(?i)\b([a-z0-9_]*(?:api_?key|secret|token|pass(?:word|wd)?|auth_?token|access_?token|private_?key|client_?secret)[a-z0-9_]*)\s*[:=]\s*(?:[\"']([^\"'\r\n]{16,})[\"']|([^\s\"'#]{16,}))"
+)
+
+PLACEHOLDER_EXACT_OR_PREFIX = {
+    "your-api-key", "your_api_key", "your-api-token", "your_token",
+    "placeholder", "my-secret-key", "changeme", "change_me",
+    "sample_key", "dummy_token", "fake_key", "mock_key", "test_secret", "test_token",
+}
+
+
+@dataclass
+class SecretFinding:
+    """Represents a detected secret or credential finding."""
+    file_path: Path
+    line_number: int
+    rule_name: str
+    description: str
+    redacted_value: str
+    snippet: str
+    is_env_file: bool = False
+
+
+@dataclass
+class SecretsScanResult:
+    """Aggregated results of a secrets scan across session files."""
+    files_scanned: int
+    findings: List[SecretFinding] = field(default_factory=list)
+    duration_seconds: float = 0.0
+
+
+def calculate_shannon_entropy(text: str) -> float:
+    """Calculate the Shannon entropy of a string."""
+    if not text:
+        return 0.0
+    counts = Counter(text)
+    length = len(text)
+    return -sum((c / length) * math.log2(c / length) for c in counts.values())
+
+
+def redact_secret(raw: str) -> str:
+    """
+    Safely redact a secret string, displaying only the first and last 2 characters.
+    
+    Example: 'sk-proj-abc1234xyz' -> 'sk****************yz'
+    """
+    raw = raw.strip()
+    if len(raw) <= 4:
+        return "****"
+    prefix = raw[:2]
+    suffix = raw[-2:]
+    return f"{prefix}****************{suffix}"
+
+
+def is_placeholder(value: str) -> bool:
+    """Check if a string is an obvious placeholder rather than a real credential."""
+    lowered = value.lower()
+    for kw in PLACEHOLDER_EXACT_OR_PREFIX:
+        if kw in lowered:
+            return True
+    return False
+
+
+def scan_file_for_secrets(file_path: Path) -> List[SecretFinding]:
+    """Scan a single file for credentials, keys, or .env tracking."""
+    findings: List[SecretFinding] = []
+
+    # 1. Tracked .env file check
+    file_name = file_path.name.lower()
+    if file_name in ENV_FILE_NAMES or file_name.startswith(".env."):
+        findings.append(
+            SecretFinding(
+                file_path=file_path,
+                line_number=1,
+                rule_name="Tracked Environment File",
+                description="Environment configuration file is tracked in git. This risks leaking private environment variables.",
+                redacted_value=file_path.name,
+                snippet=f"Tracked file: {file_path.name}",
+                is_env_file=True,
+            )
+        )
+
+    try:
+        content = file_path.read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        return findings
+
+    lines = content.splitlines()
+    for line_idx, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or stripped.startswith("//"):
+            # Skip empty lines and full line comments
+            continue
+
+        # Check known regex patterns
+        matched_known = False
+        for rule_name, pattern, desc in KNOWN_PATTERNS:
+            match = pattern.search(line)
+            if match:
+                matched_str = match.group(1)
+                if not is_placeholder(matched_str):
+                    findings.append(
+                        SecretFinding(
+                            file_path=file_path,
+                            line_number=line_idx,
+                            rule_name=rule_name,
+                            description=desc,
+                            redacted_value=redact_secret(matched_str),
+                            snippet=stripped,
+                        )
+                    )
+                    matched_known = True
+
+        # Check generic high-entropy secret assignments
+        if not matched_known:
+            assignment_match = GENERIC_ASSIGNMENT_PATTERN.search(line)
+            if assignment_match:
+                var_name = assignment_match.group(1)
+                secret_val = assignment_match.group(2) or assignment_match.group(3)
+                if secret_val and not is_placeholder(secret_val):
+                    entropy = calculate_shannon_entropy(secret_val)
+                    # Strings with length >= 16 and entropy >= 3.8 indicate high-entropy random credentials
+                    if entropy >= 3.8:
+                        findings.append(
+                            SecretFinding(
+                                file_path=file_path,
+                                line_number=line_idx,
+                                rule_name="High-Entropy Credential Assignment",
+                                description=f"High-entropy credential assigned to '{var_name}' (entropy: {entropy:.2f})",
+                                redacted_value=redact_secret(secret_val),
+                                snippet=stripped,
+                            )
+                        )
+
+    return findings
+
+
+def scan_session_files_for_secrets(files: List[Path]) -> SecretsScanResult:
+    """Scan all session files for secrets and credentials."""
+    start_time = time.time()
+    all_findings: List[SecretFinding] = []
+
+    for f in files:
+        if f.is_file():
+            findings = scan_file_for_secrets(f)
+            all_findings.extend(findings)
+
+    return SecretsScanResult(
+        files_scanned=len(files),
+        findings=all_findings,
+        duration_seconds=round(time.time() - start_time, 2),
+    )

deployproof/symlinks.py

@@ -0,0 +1,156 @@
+"""Symlink and sandbox-escape scanner for DeployProof (CWE-61 + CWE-451)."""
+
+import os
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Set, Tuple
+
+
+@dataclass
+class SymlinkFinding:
+    """Represents a detected symlink and its sandbox-escape analysis."""
+    symlink_path: Path
+    link_target_raw: str
+    resolved_target: Path
+    is_escape: bool
+    description: str
+    target_exists: bool = False
+
+
+@dataclass
+class SymlinkScanResult:
+    """Aggregated symlink and sandbox-escape results across session files."""
+    files_scanned: int
+    symlinks_found: int
+    escape_findings: List[SymlinkFinding] = field(default_factory=list)
+    safe_symlinks: List[SymlinkFinding] = field(default_factory=list)
+    duration_seconds: float = 0.0
+
+
+def get_git_symlink_paths(repo_root: Path) -> Set[Path]:
+    """Retrieve all files tracked with git symlink mode 120000."""
+    symlinks: Set[Path] = set()
+    try:
+        res = subprocess.run(
+            ["git", "ls-files", "-s"],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+        if res.returncode == 0:
+            for line in res.stdout.splitlines():
+                if line.startswith("120000"):
+                    parts = line.split(maxsplit=3)
+                    if len(parts) >= 4:
+                        rel_path = parts[3]
+                        symlinks.add((repo_root / rel_path).resolve())
+    except Exception:
+        pass
+    return symlinks
+
+
+def is_symlink_path(file_path: Path, git_symlinks: Optional[Set[Path]] = None) -> Tuple[bool, str]:
+    """
+    Check if a path is a symbolic link via filesystem or git mode 120000.
+    
+    Returns (is_symlink: bool, raw_target_string: str).
+    """
+    # 1. Native filesystem symlink check
+    if file_path.is_symlink() or os.path.islink(file_path):
+        try:
+            raw_target = os.readlink(file_path)
+            return True, str(raw_target)
+        except Exception:
+            return True, ""
+
+    # 2. Git-tracked mode 120000 check (for Windows environments where git checkouts store pointer text)
+    if git_symlinks and file_path.resolve() in git_symlinks:
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="replace").strip()
+            # If the file is small and contains a relative or absolute path pointer
+            if content and "\n" not in content and len(content) < 1024:
+                return True, content
+        except Exception:
+            pass
+
+    return False, ""
+
+
+def inspect_symlink(
+    symlink_path: Path,
+    raw_target: str,
+    repo_root: Path,
+) -> SymlinkFinding:
+    """Analyze a symlink to verify whether its resolved target escapes repo root."""
+    resolved_root = repo_root.resolve()
+
+    # Determine resolved absolute target
+    if symlink_path.is_symlink() or os.path.islink(symlink_path):
+        try:
+            resolved_target = symlink_path.resolve()
+        except Exception:
+            resolved_target = (symlink_path.parent / raw_target).resolve()
+    else:
+        resolved_target = (symlink_path.parent / raw_target).resolve()
+
+    # Check if target escapes repository root
+    try:
+        resolved_target.relative_to(resolved_root)
+        is_escape = False
+    except ValueError:
+        is_escape = True
+
+    target_exists = resolved_target.exists()
+
+    if is_escape:
+        desc = (
+            "CRITICAL: Symlink resolves outside the repository root directory (CWE-61/CWE-451). "
+            "Apparent path differs from external destination, representing a potential GhostApproval / sandbox escape."
+        )
+    else:
+        desc = "Safe in-repo symbolic link pointing to internal repository target."
+
+    return SymlinkFinding(
+        symlink_path=symlink_path,
+        link_target_raw=raw_target,
+        resolved_target=resolved_target,
+        is_escape=is_escape,
+        description=desc,
+        target_exists=target_exists,
+    )
+
+
+def scan_session_files_for_symlinks(
+    files: List[Path],
+    repo_root: Optional[Path] = None,
+) -> SymlinkScanResult:
+    """Scan all session files for symlinks and sandbox-escape vulnerabilities."""
+    start_time = time.time()
+    root = (repo_root or Path.cwd()).resolve()
+
+    git_symlinks = get_git_symlink_paths(root)
+
+    escapes: List[SymlinkFinding] = []
+    safe_links: List[SymlinkFinding] = []
+
+    for f in files:
+        is_link, raw_target = is_symlink_path(f, git_symlinks)
+        if is_link:
+            finding = inspect_symlink(f, raw_target, root)
+            if finding.is_escape:
+                escapes.append(finding)
+            else:
+                safe_links.append(finding)
+
+    return SymlinkScanResult(
+        files_scanned=len(files),
+        symlinks_found=len(escapes) + len(safe_links),
+        escape_findings=escapes,
+        safe_symlinks=safe_links,
+        duration_seconds=round(time.time() - start_time, 2),
+    )