scan-skill 0.3.1__py3-none-any.whl

scan_core/__init__.py

@@ -0,0 +1,101 @@
+"""Public Scan Core API.
+
+The v0.2 line established deterministic inventory, canonical state, privacy,
+self-contained rendering and ScanBench. The v0.3 line adds repeat-scan state
+comparison, local baselines, strict evidence freshness/reuse semantics and local Git change context.
+"""
+
+from .builder import (
+    ActionRecord,
+    BuilderError,
+    CheckRecord,
+    ComponentRecord,
+    ControlRecord,
+    EvidenceRecord,
+    FindingRecord,
+    RelationshipRecord,
+    SemanticStateBuilder,
+    UnknownRecord,
+    upgrade_semantic_state,
+)
+from .compare import Comparison, compare_states
+from .config import ScanConfig, ScanResult
+from .core import scan_project
+from .doctor import DoctorCheck, DoctorResult, run_doctor
+from .inventory import InventoryArtifact, InventoryResult, build_inventory
+from .privacy import (
+    EgressPreview,
+    PrivacyAssessment,
+    RedactionPolicy,
+    RedactionResult,
+    assess_privacy,
+    build_egress_preview,
+    prepare_text_for_egress,
+    redact_value,
+)
+from .render import render_html, render_report
+from .reuse import ReuseDecision, ReusePolicy, SemanticCheckDefinition, SemanticRegistration, evaluate_reuse
+from .scanbench import BenchResult, run_bench
+from .schema import schema_object, schema_text
+from .settings import ProjectSettings, load_project_settings
+from .snapshot import Snapshot, build_snapshot, canonical_manifest
+from .state import build_state, canonical_state_json, configuration_digest, state_digest
+from .validate import validate_path, validate_report, validate_state
+from .version import __version__
+
+__all__ = [
+    "ActionRecord",
+    "BenchResult",
+    "BuilderError",
+    "CheckRecord",
+    "ComponentRecord",
+    "ControlRecord",
+    "DoctorCheck",
+    "DoctorResult",
+    "Comparison",
+    "EgressPreview",
+    "EvidenceRecord",
+    "FindingRecord",
+    "InventoryArtifact",
+    "InventoryResult",
+    "PrivacyAssessment",
+    "ProjectSettings",
+    "ReuseDecision",
+    "ReusePolicy",
+    "RedactionPolicy",
+    "RedactionResult",
+    "ScanConfig",
+    "ScanResult",
+    "SemanticStateBuilder",
+    "SemanticCheckDefinition",
+    "SemanticRegistration",
+    "Snapshot",
+    "RelationshipRecord",
+    "UnknownRecord",
+    "assess_privacy",
+    "build_egress_preview",
+    "build_inventory",
+    "build_snapshot",
+    "build_state",
+    "canonical_manifest",
+    "canonical_state_json",
+    "compare_states",
+    "configuration_digest",
+    "evaluate_reuse",
+    "load_project_settings",
+    "prepare_text_for_egress",
+    "redact_value",
+    "render_html",
+    "render_report",
+    "run_bench",
+    "run_doctor",
+    "scan_project",
+    "schema_object",
+    "schema_text",
+    "state_digest",
+    "upgrade_semantic_state",
+    "validate_path",
+    "validate_report",
+    "validate_state",
+    "__version__",
+]

scan_core/__main__.py

@@ -0,0 +1,7 @@
+"""Allow `python -m scan_core` during development and troubleshooting."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scan_core/auxiliary.py

@@ -0,0 +1,139 @@
+"""Bounded auxiliary reads within an explicitly authorized directory.
+
+Metadata links/reparse points are rejected, including internal links. Git worktree
+indirection is resolved separately and never grants access to arbitrary parents.
+"""
+from __future__ import annotations
+
+import os
+import ntpath
+from pathlib import Path, PureWindowsPath
+import stat
+from contextlib import contextmanager
+from typing import Iterator
+
+
+class AuxiliaryReadError(ValueError):
+    """Metadata was missing, oversized, or outside the authorized boundary."""
+
+
+def _windows_path_key(value: str | Path) -> str:
+    """Compare canonical Win32 paths using the same namespace and separators."""
+    value = str(value).replace("/", "\\")
+    if value[:8].lower() == "\\\\?\\unc\\":
+        value = "\\\\" + value[8:]
+    elif value.startswith("\\\\?\\"):
+        value = value[4:]
+    return ntpath.normcase(ntpath.normpath(value))
+
+
+def is_link_or_reparse(metadata: os.stat_result) -> bool:
+    return stat.S_ISLNK(metadata.st_mode) or bool(
+        getattr(metadata, "st_file_attributes", 0) & 0x400
+    )
+
+
+def auxiliary_path(root: Path, relative: str | Path) -> Path:
+    """Validate lexical scope and every component before a metadata operation."""
+    raw = str(relative).replace("\\", "/")
+    windows = PureWindowsPath(raw)
+    if not raw or Path(raw).is_absolute() or windows.drive or windows.root or ".." in raw.split("/"):
+        raise AuxiliaryReadError("absolute or parent metadata traversal rejected")
+    # Colons can name Windows alternate data streams even in a relative path.
+    if ":" in raw or "\x00" in raw:
+        raise AuxiliaryReadError("invalid metadata path")
+    try:
+        boundary = root.absolute()
+        if is_link_or_reparse(boundary.lstat()):
+            raise AuxiliaryReadError("metadata root is a link/reparse point")
+        candidate = boundary
+        for part in Path(raw).parts:
+            candidate /= part
+            if is_link_or_reparse(candidate.lstat()):
+                raise AuxiliaryReadError("metadata link/reparse point rejected")
+        candidate.resolve(strict=True).relative_to(boundary.resolve(strict=True))
+        return candidate
+    except (OSError, ValueError, RuntimeError) as error:
+        if isinstance(error, AuxiliaryReadError):
+            raise
+        raise AuxiliaryReadError("metadata missing or outside authorized root") from error
+
+
+@contextmanager
+def _open_metadata(root: Path, path: Path, flags: int) -> Iterator[int]:
+    if os.name == 'nt':
+        # Validate the opened handle's actual path BEFORE reading bytes. Checking
+        # path.resolve() alone leaves a parent-junction replacement race.
+        import ctypes
+        import msvcrt
+        # Pin the intended canonical boundary/target BEFORE os.open can follow
+        # a replaced parent. resolve() also expands native short-name aliases.
+        boundary = root.resolve(strict=True)
+        expected = path.resolve(strict=True)
+        if not expected.is_relative_to(boundary):
+            raise AuxiliaryReadError('metadata escaped its authorized root before opening')
+        descriptor = os.open(path, flags)
+        try:
+            get_path = ctypes.windll.kernel32.GetFinalPathNameByHandleW
+            get_path.argtypes = [ctypes.c_void_p, ctypes.c_wchar_p, ctypes.c_uint32, ctypes.c_uint32]
+            get_path.restype = ctypes.c_uint32
+            buffer = ctypes.create_unicode_buffer(32768)
+            length = get_path(msvcrt.get_osfhandle(descriptor), buffer, len(buffer), 0)
+            if not length or length >= len(buffer):
+                raise AuxiliaryReadError('opened metadata path could not be verified')
+            actual = Path(_windows_path_key(buffer.value)).resolve(strict=True)
+            if (_windows_path_key(actual) != _windows_path_key(expected)
+                    or not actual.is_relative_to(boundary)):
+                raise AuxiliaryReadError('opened metadata escaped its authorized path')
+            yield descriptor
+        finally:
+            os.close(descriptor)
+        return
+
+    # POSIX traverses from a pinned directory handle without following links in
+    # any child component, even when an attacker replaces a parent concurrently.
+    directory_flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+    directory = os.open(root.absolute(), directory_flags)
+    try:
+        parts = path.relative_to(root.absolute()).parts
+        for part in parts[:-1]:
+            child = os.open(part, directory_flags, dir_fd=directory)
+            os.close(directory)
+            directory = child
+        descriptor = os.open(parts[-1], flags | os.O_NOFOLLOW, dir_fd=directory)
+        try:
+            yield descriptor
+        finally:
+            os.close(descriptor)
+    finally:
+        os.close(directory)
+
+
+def read_auxiliary(root: Path, relative: str | Path, *, max_bytes: int) -> bytes:
+    """Read at most max_bytes + one sentinel; never use an unbounded read."""
+    if max_bytes < 0:
+        raise ValueError("max_bytes must be non-negative")
+    path = auxiliary_path(root, relative)
+    try:
+        before = path.lstat()
+        flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+        with _open_metadata(root, path, flags) as descriptor, os.fdopen(descriptor, "rb", closefd=False) as stream:
+            opened = os.fstat(stream.fileno())
+            if not stat.S_ISREG(opened.st_mode) or (before.st_dev, before.st_ino) != (opened.st_dev, opened.st_ino):
+                raise AuxiliaryReadError("metadata changed or is not a regular file")
+            if opened.st_size > max_bytes:
+                raise AuxiliaryReadError("metadata exceeds byte limit")
+            data = stream.read(max_bytes + 1)
+        auxiliary_path(root, relative)
+        if len(data) > max_bytes:
+            raise AuxiliaryReadError("metadata exceeds byte limit")
+        return data
+    except OSError as error:
+        raise AuxiliaryReadError("metadata could not be read safely") from error
+
+
+def auxiliary_text(root: Path, relative: str | Path, *, max_bytes: int) -> str | None:
+    try:
+        return read_auxiliary(root, relative, max_bytes=max_bytes).decode("utf-8", errors="replace")
+    except AuxiliaryReadError:
+        return None

scan_core/baseline.py

@@ -0,0 +1,88 @@
+"""Local-only baseline resolution for repeated Scan runs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from .errors import ResourceLimitError, SourceError, ValidationError
+from .validate import reject_constant, unique_keys, validate_state
+
+DEFAULT_MAX_STATE_BYTES = 64_000_000
+
+
+@dataclass(frozen=True)
+class BaselineResolution:
+    mode: str
+    status: str
+    state: Mapping[str, Any] | None = None
+    warning: str | None = None
+
+
+def load_state_file(path: Path, *, max_state_bytes: int = DEFAULT_MAX_STATE_BYTES, explicit: bool = True) -> dict[str, Any]:
+    try:
+        stat = path.stat()
+    except OSError as error:
+        raise SourceError(f"Cannot access baseline state: {path}") from error
+    if not path.is_file():
+        raise SourceError(f"Baseline state is not a regular file: {path}")
+    if stat.st_size > max_state_bytes:
+        message = f"Baseline state exceeds configured ceiling ({stat.st_size} > {max_state_bytes} bytes)"
+        if explicit:
+            raise ResourceLimitError(message)
+        raise ValidationError(message)
+    try:
+        with path.open(encoding="utf-8") as stream:
+            state = json.load(stream, object_pairs_hook=unique_keys, parse_constant=reject_constant)
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise ValidationError(f"Cannot parse baseline state: {error}") from error
+    if not isinstance(state, dict):
+        raise ValidationError("Baseline state must be a JSON object")
+    if state.get("schema_version") not in {"1.3", "1.4"}:
+        raise ValidationError("Baseline state must use schema_version 1.3 or 1.4")
+    validate_state(state)
+    return state
+
+
+def resolve_baseline(
+    *,
+    mode: str,
+    output_state: Path | None,
+    explicit_path: Path | None = None,
+    max_state_bytes: int = DEFAULT_MAX_STATE_BYTES,
+) -> BaselineResolution:
+    """Resolve a local baseline without network access or filesystem searching."""
+    if mode == "none":
+        return BaselineResolution(mode="none", status="disabled")
+    if mode == "explicit":
+        if explicit_path is None:
+            raise SourceError("Explicit baseline path was not supplied")
+        path = Path(explicit_path)
+        if not path.exists():
+            raise SourceError(f"Baseline state does not exist: {path}")
+        state = load_state_file(path, max_state_bytes=max_state_bytes, explicit=True)
+        return BaselineResolution(mode="explicit", status="used", state=state)
+    if mode != "auto":
+        raise ValueError(f"Unsupported baseline mode: {mode}")
+    if output_state is None:
+        return BaselineResolution(mode="auto", status="not_found")
+    path = Path(output_state)
+    if not path.exists():
+        return BaselineResolution(mode="auto", status="not_found")
+    try:
+        state = load_state_file(path, max_state_bytes=max_state_bytes, explicit=False)
+    except ValidationError as error:
+        return BaselineResolution(
+            mode="auto",
+            status="invalid",
+            warning=f"Automatic baseline ignored: {error}",
+        )
+    except SourceError as error:
+        return BaselineResolution(
+            mode="auto",
+            status="invalid",
+            warning=f"Automatic baseline ignored: {error}",
+        )
+    return BaselineResolution(mode="auto", status="used", state=state)