worktree-shield 0.1.0__py3-none-any.whl

worktree_shield/reports/sarif.py

@@ -0,0 +1,116 @@
+"""SARIF 2.1.0 output, for code scanning (GitHub and other SARIF viewers).
+
+Only findings that need attention and point to a file become results: fail is
+``error``, warn ``warning``, unknown ``note``. Locations are the claims of the current
+worktree, relative to it, so a viewer of that checkout opens the right line; claims of
+other worktrees become related locations whose message names the worktree. Each result
+has a fingerprint from its rule and resource, stable across runs, so a viewer can tell
+a new collision from one it has seen. Pass a redacted snapshot.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any
+
+from worktree_shield.models import Finding, Snapshot, SourceRef, Status
+from worktree_shield.reports.markdown import PROJECT_URL
+from worktree_shield.rules.catalog import builtin_rules
+
+SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+_LEVEL = {Status.FAIL: "error", Status.WARN: "warning", Status.UNKNOWN: "note"}
+
+
+def _anchor(rule_id: str, title: str) -> str:
+    """The GitHub anchor of the rule's heading in docs/rules.md."""
+    heading = f"{rule_id}: {title}".lower()
+    return re.sub(r"[^a-z0-9 -]", "", heading).replace(" ", "-")
+
+
+def render_sarif(snapshot: Snapshot) -> str:
+    """One SARIF run with every rule and a result per located problem."""
+    rules = builtin_rules()
+    index = {rule.id: i for i, rule in enumerate(rules)}
+    current = snapshot.repository.current if snapshot.repository else None
+    results = [
+        result
+        for finding in snapshot.findings
+        if finding.status in _LEVEL and finding.sources
+        for result in [_result(finding, index[finding.id], current)]
+    ]
+    document: dict[str, Any] = {
+        "$schema": SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "worktree-shield",
+                        "version": snapshot.tool_version,
+                        "semanticVersion": snapshot.tool_version,
+                        "informationUri": PROJECT_URL,
+                        "rules": [
+                            {
+                                "id": rule.id,
+                                "name": rule.id.replace("-", ""),
+                                "shortDescription": {"text": rule.title},
+                                "helpUri": f"{PROJECT_URL}/blob/main/docs/rules.md#"
+                                + _anchor(rule.id, rule.title),
+                            }
+                            for rule in rules
+                        ],
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }
+    return json.dumps(document, indent=2, ensure_ascii=False) + "\n"
+
+
+def _location(source: SourceRef, message: str | None = None) -> dict[str, Any]:
+    physical: dict[str, Any] = {"artifactLocation": {"uri": source.path}}
+    if source.line is not None:
+        physical["region"] = {"startLine": source.line}
+    location: dict[str, Any] = {"physicalLocation": physical}
+    if message:
+        location["message"] = {"text": message}
+    return location
+
+
+def _message(finding: Finding) -> str:
+    """Summary, reason and next step: SARIF fixes need file edits, so advice goes here."""
+    parts = [f"{finding.summary}.", finding.reason]
+    if finding.recommended_action:
+        parts.append(f"Next: {finding.recommended_action}")
+    return " ".join(parts)
+
+
+def _result(finding: Finding, rule_index: int, current: str | None) -> dict[str, Any]:
+    files = [s for s in finding.sources if not s.path.startswith("pid ")]
+    here = [s for s in files if s.worktree == current] or files[:1]
+    elsewhere = [s for s in files if s not in here]
+    result: dict[str, Any] = {
+        "ruleId": finding.id,
+        "ruleIndex": rule_index,
+        "level": _LEVEL[finding.status],
+        "message": {"text": _message(finding)},
+        "locations": [_location(s) for s in here],
+        "partialFingerprints": {
+            "worktreeShield/v1": hashlib.sha256(
+                f"{finding.id}\0{finding.resource_key or finding.summary}".encode()
+            ).hexdigest()
+        },
+        "properties": {
+            "certainty": finding.certainty.value if finding.certainty else None,
+            "worktrees": list(finding.worktrees),
+        },
+    }
+    if elsewhere:
+        result["relatedLocations"] = [
+            {"id": i, **_location(s, f"in the worktree {s.worktree}")}
+            for i, s in enumerate(elsewhere)
+        ]
+    return result

worktree_shield/reports/terminal.py

@@ -0,0 +1,327 @@
+"""Terminal output of an already redacted snapshot.
+
+Collected text (paths, branch names, lock reasons) is added as plain ``Text``, never as
+Rich markup, so a branch called ``[bold]x`` is printed as it is.
+"""
+
+from __future__ import annotations
+
+import os
+from collections import defaultdict
+from collections.abc import Callable
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from worktree_shield.models import (
+    Policy,
+    Repository,
+    ResourceClaim,
+    ResourceKind,
+    Snapshot,
+    SourceRef,
+    Worktree,
+)
+
+_REDACTION_NAMES = {
+    "home_path": ("home path", "home paths"),
+    "user_name": ("user name", "user names"),
+    "host_name": ("host name", "host names"),
+    "secret_value": ("secret value", "secret values"),
+    "url_credentials": ("URL credential", "URL credentials"),
+    "token": ("token", "tokens"),
+}
+
+
+def redaction_line(snapshot: Snapshot) -> str | None:
+    """'Redacted from this output: 3 home paths, 1 secret value', or None if nothing was."""
+    if not snapshot.redactions:
+        return None
+    parts = []
+    for item in snapshot.redactions:
+        singular, plural = _REDACTION_NAMES.get(item.kind, (item.kind, item.kind))
+        parts.append(f"{item.count} {singular if item.count == 1 else plural}")
+    return "Redacted from this output: " + ", ".join(parts)
+
+
+def display_path(path: str) -> str:
+    """A path on one line: newlines, tabs and other control characters shown escaped."""
+    out = []
+    for char in path:
+        if char == "\n":
+            out.append("\\n")
+        elif char == "\t":
+            out.append("\\t")
+        elif ord(char) < 32 or ord(char) == 127:
+            out.append(f"\\x{ord(char):02x}")
+        else:
+            out.append(char)
+    return "".join(out)
+
+
+def common_parent(paths: list[str]) -> str | None:
+    """The directory all worktrees live in, if they share one below the root."""
+    try:
+        parent = os.path.commonpath(paths)
+    except ValueError:  # different drives on Windows
+        return None
+    if parent in paths:  # one worktree contains the others: use its parent
+        parent = str(Path(parent).parent)
+    return parent if parent not in {"", ".", "/", os.sep} else None
+
+
+def _ref(worktree: Worktree) -> str:
+    if worktree.bare:
+        return "bare repository"
+    if worktree.branch:
+        return worktree.branch.removeprefix("refs/heads/")
+    if worktree.head:
+        return f"detached at {worktree.head[:7]}"
+    return "no commit"
+
+
+def _notes(worktree: Worktree) -> str:
+    notes = []
+    if worktree.locked is not None:
+        notes.append(f"locked: {worktree.locked}" if worktree.locked else "locked")
+    if worktree.prunable is not None:
+        notes.append(f"prunable: {worktree.prunable}" if worktree.prunable else "prunable")
+    return "; ".join(notes)
+
+
+def render_worktrees(snapshot: Snapshot, console: Console) -> None:
+    """Every worktree of the repository, the current one marked."""
+    repository: Repository | None = snapshot.repository
+    console.print(Text(f"worktree-shield {snapshot.tool_version}", style="bold"))
+    if repository is None:
+        console.print(Text("The worktrees could not be listed:"))
+        for failure in snapshot.probe_failures:
+            console.print(Text(f"  {failure.probe}: {failure.detail}"))
+        return
+    count = len(repository.worktrees)
+    plural = "s" if count != 1 else ""
+    console.print(Text(f"{count} worktree{plural} sharing {display_path(repository.common_dir)}"))
+    parent = common_parent([w.path for w in repository.worktrees])
+    if parent is not None:
+        console.print(Text(f"Paths below are relative to {display_path(parent)}", style="dim"))
+    console.print()
+    table = Table(box=None, show_edge=False, pad_edge=False, header_style="bold")
+    table.add_column("", no_wrap=True)
+    table.add_column("Worktree", overflow="fold")
+    table.add_column("Branch", overflow="fold")
+    table.add_column("Notes")
+    for worktree in repository.worktrees:
+        here = "*" if repository.current is not None and worktree.path == repository.current else ""
+        shown = os.path.relpath(worktree.path, parent) if parent is not None else worktree.path
+        table.add_row(
+            Text(here), Text(display_path(shown)), Text(_ref(worktree)), Text(_notes(worktree))
+        )
+    console.print(table)
+    if any(w.prunable is not None for w in repository.worktrees):
+        console.print()
+        console.print(
+            Text(
+                "Prunable worktrees are listed by Git but their directory is gone; "
+                "worktree-shield never prunes them (git worktree prune would).",
+                style="dim",
+            )
+        )
+    line = redaction_line(snapshot)
+    if line:
+        console.print()
+        console.print(Text(line, style="dim"))
+
+
+def _policy_rows(policy: Policy) -> list[tuple[str, str, str]]:
+    """(setting, value, default value) in the order of the policy file."""
+    default = Policy()
+
+    def flag(value: bool) -> str:
+        return "true" if value else "false"
+
+    def listed(values: tuple[object, ...]) -> str:
+        return ", ".join(display_path(str(v)) for v in values) if values else "none"
+
+    return [
+        ("scan.include_runtime", flag(policy.include_runtime), flag(default.include_runtime)),
+        ("scan.include_env_files", flag(policy.include_env_files), flag(default.include_env_files)),
+        ("scan.max_file_bytes", str(policy.max_file_bytes), str(default.max_file_bytes)),
+        ("policy.shared_host_ports", policy.shared_host_ports, default.shared_host_ports),
+        ("policy.shared_database", policy.shared_database, default.shared_database),
+        (
+            "policy.shared_compose_projects",
+            policy.shared_compose_projects,
+            default.shared_compose_projects,
+        ),
+        (
+            "policy.fixed_container_names",
+            policy.fixed_container_names,
+            default.fixed_container_names,
+        ),
+        (
+            "policy.shared_absolute_paths",
+            policy.shared_absolute_paths,
+            default.shared_absolute_paths,
+        ),
+        ("allow.ports", listed(policy.allow_ports), listed(default.allow_ports)),
+        ("allow.paths", listed(policy.allow_paths), listed(default.allow_paths)),
+    ]
+
+
+def render_policy(policy: Policy, worktree: str | None, console: Console) -> None:
+    """The effective policy of a worktree and where each value comes from."""
+    if policy.source is not None:
+        console.print(Text(f"Policy from {display_path(policy.source)}", style="bold"))
+    elif worktree is not None:
+        console.print(Text("Built-in defaults", style="bold"))
+        console.print(Text(f"No .worktree-shield.toml in {display_path(worktree)}", style="dim"))
+    else:
+        console.print(
+            Text("Built-in defaults (a bare repository has no policy file)", style="bold")
+        )
+    console.print()
+    table = Table(box=None, show_edge=False, pad_edge=False, header_style="bold")
+    table.add_column("Setting", no_wrap=True)
+    table.add_column("Value", overflow="fold")
+    table.add_column("")
+    for name, value, default in _policy_rows(policy):
+        note = "" if value == default or policy.source is None else f"default: {default}"
+        table.add_row(Text(name), Text(str(value)), Text(note, style="dim"))
+    console.print(table)
+    console.print()
+    console.print(
+        Text(
+            "deny fails --strict, warn is reported, allow is information only. allow.ports "
+            "are endpoints the worktrees may share as clients; two listeners on one port are "
+            "never allowed by it.",
+            style="dim",
+        )
+    )
+
+
+_KIND_TITLES = (
+    (ResourceKind.LISTEN_PORT, "Listen ports"),
+    (ResourceKind.DATABASE, "Databases"),
+    (ResourceKind.COMPOSE_PROJECT, "Compose projects"),
+    (ResourceKind.CONTAINER_NAME, "Container names"),
+    (ResourceKind.VOLUME, "Volumes"),
+    (ResourceKind.ABSOLUTE_PATH, "Absolute paths"),
+    (ResourceKind.CLIENT_ENDPOINT, "Servers the worktrees connect to"),
+)
+
+
+def _where(source: SourceRef) -> str:
+    line = f":{source.line}" if source.line is not None else ""
+    return display_path(source.path) + line
+
+
+def worktree_names(repository: Repository) -> tuple[Callable[[str], str], str | None]:
+    """How reports name a worktree (relative to the directory all of them share) and
+    that directory, if any."""
+    parent = common_parent([w.path for w in repository.worktrees])
+
+    def name(worktree: str) -> str:
+        return display_path(os.path.relpath(worktree, parent) if parent is not None else worktree)
+
+    return name, parent
+
+
+def render_failed_discovery(snapshot: Snapshot, console: Console) -> None:
+    console.print(Text("The worktrees could not be listed:"))
+    for failure in snapshot.probe_failures:
+        console.print(Text(f"  {failure.probe}: {failure.detail}"))
+
+
+def render_resources(snapshot: Snapshot, console: Console) -> None:
+    """Every resource the worktrees declare, grouped by kind; shared ones marked."""
+    repository = snapshot.repository
+    console.print(Text(f"worktree-shield {snapshot.tool_version}", style="bold"))
+    if repository is None:
+        render_failed_discovery(snapshot, console)
+        return
+    name, parent = worktree_names(repository)
+
+    by_key: dict[tuple[ResourceKind, str], list[ResourceClaim]] = defaultdict(list)
+    for claim in snapshot.claims:
+        by_key[(claim.kind, claim.key)].append(claim)
+    shared = sum(1 for claims in by_key.values() if len({c.worktree for c in claims}) > 1)
+    count = len(repository.worktrees)
+    console.print(
+        Text(
+            f"{count} worktree{'s' if count != 1 else ''}, {len(by_key)} "
+            f"resource{'s' if len(by_key) != 1 else ''}, {shared} used by more than one worktree"
+        )
+    )
+    if parent is not None:
+        console.print(Text(f"Worktrees are named relative to {display_path(parent)}", style="dim"))
+    for kind, title in _KIND_TITLES:
+        keys = sorted(key for key in by_key if key[0] is kind)
+        if not keys:
+            continue
+        console.print()
+        console.print(Text(title, style="bold"))
+        table = Table(box=None, show_edge=False, pad_edge=False, show_header=False)
+        table.add_column("Resource", no_wrap=True)
+        table.add_column("Worktree", overflow="fold")
+        table.add_column("Where", overflow="fold")
+        table.add_column("What", overflow="fold")
+        for key in keys:
+            claims = by_key[key]
+            users = len({c.worktree for c in claims})
+            label = Text(key[1])
+            if users > 1:
+                label.append(f"  {users} worktrees", style="bold yellow")
+            for index, claim in enumerate(claims):
+                table.add_row(
+                    label if index == 0 else Text(""),
+                    Text(name(claim.worktree)),
+                    Text(_where(claim.source)),
+                    Text(claim.detail),
+                )
+        console.print(table)
+    if not by_key:
+        console.print()
+        console.print(Text("No ports, databases or paths were found in the configuration."))
+    _render_gaps(snapshot, name, console)
+
+
+def _render_gaps(snapshot: Snapshot, label: Callable[[str], str], console: Console) -> None:
+    """What could not be read: skipped files, unreadable values, files left out."""
+    if snapshot.skipped:
+        console.print()
+        console.print(Text("Not read", style="bold"))
+        for skipped in snapshot.skipped:
+            where = _where(skipped.source)
+            console.print(Text(f"  {label(skipped.source.worktree)}  {where} {skipped.reason}"))
+    if snapshot.unreadable:
+        console.print()
+        console.print(Text("Could not be identified", style="bold"))
+        for value in snapshot.unreadable:
+            where = _where(value.source)
+            console.print(
+                Text(f"  {label(value.source.worktree)}  {where} {value.name}: {value.reason}")
+            )
+    runtime = snapshot.runtime
+    if runtime is not None and runtime.unattributed:
+        console.print()
+        console.print(Text("Configured ports in use outside the worktrees", style="bold"))
+        for listener in runtime.unattributed:
+            owner = listener.process or "a process"
+            if listener.pid is not None:
+                owner += f" (pid {listener.pid})"
+            address = f"[{listener.address}]" if ":" in listener.address else listener.address
+            console.print(
+                Text(f"  {listener.protocol} {address}:{listener.port}  {owner}: {listener.note}")
+            )
+    if runtime is not None:
+        for limitation in runtime.limitations:
+            console.print(Text(f"Running processes: {limitation}.", style="dim"))
+    elif snapshot.policy is not None:
+        console.print()
+        console.print(Text("Running processes were not looked at.", style="dim"))
+    line = redaction_line(snapshot)
+    if line:
+        console.print()
+        console.print(Text(line, style="dim"))

worktree_shield/rules/__init__.py

@@ -0,0 +1 @@
+"""The WTS rules: pure functions from a snapshot to findings (docs/rules.md lists them)."""

worktree_shield/rules/catalog.py

@@ -0,0 +1,28 @@
+"""The built-in rules, in the order reports list them."""
+
+from __future__ import annotations
+
+from worktree_shield.rules import context, runtime, shared
+from worktree_shield.rules.engine import Rule
+
+_ORDER = (
+    "WTS-PORT-001",
+    "WTS-PORT-002",
+    "WTS-DB-001",
+    "WTS-DB-002",
+    "WTS-DOCKER-001",
+    "WTS-DOCKER-002",
+    "WTS-DOCKER-003",
+    "WTS-PATH-001",
+    "WTS-ENV-001",
+    "WTS-CONFIG-001",
+    "WTS-GIT-002",
+    "WTS-RUNTIME-001",
+    "WTS-POLICY-001",
+)
+
+
+def builtin_rules() -> tuple[Rule, ...]:
+    """Every rule, ordered by resource: ports, databases, Docker, paths, then context."""
+    rules = {rule.id: rule for rule in (*shared.RULES, *runtime.RULES, *context.RULES)}
+    return tuple(rules[rule_id] for rule_id in _ORDER)

worktree_shield/rules/common.py

@@ -0,0 +1,61 @@
+"""Pieces the rule modules share: key parsing, evidence and finding helpers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from pathlib import PurePosixPath
+
+from worktree_shield.collectors.envfiles import TEMPLATE_FILES
+from worktree_shield.models import (
+    Confidence,
+    Evidence,
+    Finding,
+    Policy,
+    ResourceClaim,
+    Severity,
+    SourceRef,
+    Status,
+)
+
+VERIFY = "worktree-shield scan --strict"
+VERIFY_WITH_ENV = VERIFY + " --include-env"
+
+
+def verify_for(claims: Iterable[ResourceClaim], policy: Policy) -> str:
+    """The scan that can see the fix: a value from a ``.env`` template is fixed in a
+    ``.env``, which a scan reads only with ``--include-env`` (or the policy's opt-in)."""
+    from_template = any(PurePosixPath(c.source.path).name in TEMPLATE_FILES for c in claims)
+    return VERIFY_WITH_ENV if from_template and not policy.include_env_files else VERIFY
+
+
+_PORT = re.compile(r"[a-z]+://.*:([0-9]+)")
+
+
+def port_of(key: str) -> int | None:
+    """The port of a ``tcp://host:port`` or ``db://engine/host:port/db`` key."""
+    match = _PORT.fullmatch(key.rsplit("/", 1)[0] if key.startswith("db://") else key)
+    return int(match.group(1)) if match else None
+
+
+def name_of(key: str) -> str:
+    """What follows the scheme: ``shop`` of ``compose-project://shop``."""
+    return key.split("://", 1)[-1]
+
+
+def where(source: SourceRef) -> str:
+    return source.path if source.line is None else f"{source.path}:{source.line}"
+
+
+def evidence(claims: tuple[ResourceClaim, ...] | list[ResourceClaim]) -> tuple[Evidence, ...]:
+    """One line per claim: where it was found, in which worktree, what was read."""
+    return tuple(Evidence(where(c.source), c.worktree, c.detail) for c in claims)
+
+
+def plural(count: int, word: str) -> str:
+    return f"{count} {word}" if count == 1 else f"{count} {word}s"
+
+
+def plain(rule: str, status: Status, summary: str, reason: str) -> Finding:
+    """A finding about no resource in particular: nothing to check, or nothing found."""
+    return Finding(rule, status, Severity.INFO, Confidence.MEDIUM, summary, reason)