doorcheck 0.1.0a1__py3-none-any.whl

doorcheck/__init__.py

@@ -0,0 +1 @@
+"""Doorcheck: see what a Home Assistant integration can do before you let it in."""

doorcheck/__main__.py

@@ -0,0 +1,6 @@
+"""Run the local scanner with python -m doorcheck."""
+
+from doorcheck.cli import entrypoint
+
+if __name__ == "__main__":
+    entrypoint()

doorcheck/adapters/__init__.py

@@ -0,0 +1,26 @@
+from doorcheck.adapters.base import (
+    Adapter,
+    Audience,
+    Command,
+    Parsed,
+    ScanInput,
+    ToolError,
+    ToolRun,
+    prepare,
+    run,
+)
+from doorcheck.adapters.registry import Loaded, load
+
+__all__ = [
+    "Adapter",
+    "Audience",
+    "Command",
+    "Loaded",
+    "Parsed",
+    "ScanInput",
+    "ToolError",
+    "ToolRun",
+    "load",
+    "prepare",
+    "run",
+]

doorcheck/adapters/base.py

@@ -0,0 +1,183 @@
+"""The one interface every scanning tool plugs into.
+
+An adapter builds a command and reads that command's output; running it
+(timeout, a clean environment, exit codes, the pinned version) is shared here,
+so each tool's quirks stay inside its own adapter.
+
+A run always ends in a Check: a tool that is missing, too slow or misbehaving
+gives a failed check instead of an empty list, so a gap never looks clean.
+"""
+
+import os
+import subprocess
+import tempfile
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Protocol
+
+from doorcheck.adapters.process import OutputLimitError, capture
+from doorcheck.checks import Check, Problem, Status, status_for
+from doorcheck.dependencies import Dependencies, resolve
+from doorcheck.errors import DoorcheckError
+from doorcheck.findings import Finding, param
+from doorcheck.pypi import Resolve, newest_version
+
+TIMEOUT_SECONDS = 300
+STDERR_SHOWN = 300
+MAX_OUTPUT_BYTES = 20 * 1024 * 1024
+
+
+class ToolError(DoorcheckError):
+    """A tool couldn't run, failed, or wrote output its adapter doesn't understand."""
+
+    key = "problem.tool_failed"
+
+
+class Audience(StrEnum):
+    USERS = "users"  # about the code an install puts on disk
+    AUTHORS = "authors"  # about how the project is built, such as its CI workflows
+
+
+@dataclass(frozen=True, slots=True)
+class ScanInput:
+    """What every tool scans. Dependencies are resolved once, for all of them."""
+
+    root: Path
+    dependencies: Dependencies = field(default_factory=Dependencies)
+
+
+def prepare(root: Path, resolve_one: Resolve = newest_version) -> ScanInput:
+    return ScanInput(root, resolve(root, resolve_one))
+
+
+@dataclass(frozen=True, slots=True)
+class Command:
+    argv: tuple[str, ...]
+    cwd: Path
+    ok_exit_codes: frozenset[int] = frozenset({0})
+
+
+@dataclass(frozen=True, slots=True)
+class Parsed:
+    findings: tuple[Finding, ...] = ()
+    problems: tuple[Problem, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ToolRun:
+    check: Check
+    findings: tuple[Finding, ...] = ()
+
+
+class Adapter(Protocol):
+    name: str
+    version: str  # the version doorcheck is tested with; any other is refused
+    executable: str
+    audience: Audience
+    experimental: bool  # off unless asked for, until test data shows it catches something
+
+    def version_command(self) -> Sequence[str]: ...
+
+    def command(self, scan: ScanInput, work: Path) -> Command | Parsed:
+        """The scan to run. When there is nothing for the tool to run on, the result
+        itself: empty, or listing what couldn't be covered. `work` is an empty
+        scratch folder the adapter may write inputs to."""
+        ...
+
+    def parse(self, output: bytes, scan: ScanInput) -> Parsed: ...
+
+
+def run(adapter: Adapter, scan: ScanInput, timeout: float = TIMEOUT_SECONDS) -> ToolRun:
+    try:
+        result = _result(adapter, scan, timeout)
+    except (ToolError, OSError) as error:
+        key = error.key if isinstance(error, ToolError) else "problem.tool_failed"
+        problem = Problem(key, params={"detail": param(str(error))})
+        return ToolRun(Check(adapter.name, adapter.version, Status.FAILED, (problem,)))
+    if result is None:
+        return ToolRun(Check(adapter.name, adapter.version, Status.NOTHING_TO_SCAN))
+    check = Check(adapter.name, adapter.version, status_for(result.problems), result.problems)
+    return ToolRun(check, result.findings)
+
+
+def _result(adapter: Adapter, scan: ScanInput, timeout: float) -> Parsed | None:
+    output = raw_output(adapter, scan, timeout)
+    if isinstance(output, Parsed):
+        return output if output.findings or output.problems else None
+    try:
+        return adapter.parse(output, scan)
+    except (
+        ValueError,
+        KeyError,
+        TypeError,
+        IndexError,
+        AttributeError,
+        StopIteration,
+        RecursionError,
+    ) as error:
+        message = f"{adapter.name} output not understood: {error!r}"
+        raise ToolError(message, "problem.tool_output_not_understood") from error
+
+
+def raw_output(
+    adapter: Adapter, scan: ScanInput, timeout: float = TIMEOUT_SECONDS
+) -> bytes | Parsed:
+    """What the tool prints for the scan, or the adapter's result if it didn't need to run."""
+    with tempfile.TemporaryDirectory() as work, tempfile.TemporaryDirectory() as home:
+        check_version(adapter, Path(home), timeout)
+        command = adapter.command(scan, Path(work))
+        if isinstance(command, Parsed):
+            return command
+        return _execute(adapter.name, command, Path(home), timeout)
+
+
+def check_version(adapter: Adapter, home: Path, timeout: float) -> None:
+    command = Command(tuple(adapter.version_command()), home)
+    reported = _execute(adapter.name, command, home, timeout).decode(errors="replace")
+    if adapter.version not in reported.split():
+        found = reported.strip()[:STDERR_SHOWN]
+        message = f"{adapter.name} {adapter.version} is required, found: {found}"
+        raise ToolError(message, "problem.tool_wrong_version")
+
+
+def _execute(name: str, command: Command, home: Path, timeout: float) -> bytes:
+    try:
+        done = capture(command.argv, command.cwd, _environment(home), timeout, MAX_OUTPUT_BYTES)
+    except FileNotFoundError as error:
+        message = f"{name} is not installed: {command.argv[0]}"
+        raise ToolError(message, "problem.tool_not_installed") from error
+    except subprocess.TimeoutExpired as error:
+        message = f"{name} took longer than {timeout} seconds"
+        raise ToolError(message, "problem.tool_timed_out") from error
+    except OutputLimitError as error:
+        raise ToolError(
+            f"{name} output exceeds {MAX_OUTPUT_BYTES} bytes", "problem.tool_output_too_large"
+        ) from error
+    if done.returncode not in command.ok_exit_codes:
+        detail = done.stderr.decode(errors="replace").strip()[-STDERR_SHOWN:]
+        raise ToolError(f"{name} failed with exit code {done.returncode}: {detail}")
+    return done.stdout
+
+
+def _environment(home: Path) -> dict[str, str]:
+    """Only what tools need. A fresh HOME keeps them from reading the user's settings
+    or tokens; the proxy and certificate settings (paths, not secrets) keep
+    downloads working behind a proxy."""
+    kept = {"PATH", "LANG", "HTTPS_PROXY", "https_proxy", "NO_PROXY", "no_proxy"}
+    kept |= {"SSL_CERT_FILE", "SSL_CERT_DIR", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE"}
+    env = {key: value for key, value in os.environ.items() if key in kept}
+    return {**env, "HOME": str(home.resolve()), "NO_COLOR": "1"}
+
+
+def relative(path: str, target: Path) -> str:
+    """A tool's path as a path inside the scanned folder; anything outside is refused.
+    Links aren't resolved: a finding is placed where the tool saw it."""
+    given = Path(path)
+    if given.is_absolute():
+        given = given.relative_to(target.absolute())  # ValueError when outside
+    normal = os.path.normpath(given.as_posix())
+    if normal == "." or normal == ".." or normal.startswith("../"):
+        raise ValueError(f"path outside the scanned folder: {path!r}")
+    return normal

doorcheck/adapters/guarddog.py

@@ -0,0 +1,173 @@
+"""GuardDog, Datadog's heuristics for malicious packages, in two places:
+the integration's own code, and the PyPI packages its manifest installs.
+
+Both are experimental: off unless asked for. On the benchmark corpus GuardDog's
+`threat-*` rules matched no known bug and fired on 11 of 75 benign
+integrations, on unit symbols, Cyrillic labels and town-name tables, and its
+package-metadata rules (typosquatting, a maintainer's lapsed email domain)
+flagged only benign packages. That changes when the malicious test set shows a
+rule earns it. Until then code heuristics are information and metadata rules
+are notices.
+
+A check GuardDog couldn't run, and a requirement it didn't report on at all,
+are recorded as not covered: a gap in the scan is shown, never passed off as clean.
+"""
+
+import json
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from doorcheck.adapters.base import (
+    Audience,
+    Command,
+    Parsed,
+    ScanInput,
+    relative,
+)
+from doorcheck.checks import Problem
+from doorcheck.dependencies import MANIFEST, Pin, pins_file, unresolved_problem
+from doorcheck.findings import Confidence, Finding, Location, Severity, evidence, param
+from doorcheck.requirements import normalized
+
+
+class GuardDog:
+    """The integration's own files."""
+
+    name = "guarddog"
+    version = "3.2.0"  # renovate: datasource=pypi depName=guarddog
+    audience = Audience.USERS
+    experimental = True
+
+    def __init__(self, executable: str = "guarddog") -> None:
+        self.executable = executable
+
+    def version_command(self) -> Sequence[str]:
+        return (self.executable, "--version")
+
+    def command(self, scan: ScanInput, work: Path) -> Command | Parsed:
+        argv = (self.executable, "pypi", "scan", ".", "--output-format", "json")
+        return Command(argv, scan.root)
+
+    def parse(self, output: bytes, scan: ScanInput) -> Parsed:
+        report = json.loads(output)
+        findings = tuple(
+            _code_finding(rule, match, self.name, Location(*_place(match, scan.root)), {})
+            for rule, matches in sorted(report["results"].items())
+            if isinstance(matches, list)  # rules with no match, and metadata rules, aren't
+            for match in matches
+        )
+        return Parsed(findings, tuple(_check_failures(report["errors"], None, {})))
+
+
+class GuardDogDependencies:
+    """The PyPI packages manifest.json installs, at the version a fresh install gets.
+    GuardDog misreads a range with more than one bound as a version, so it gets
+    exact pins (doorcheck.dependencies)."""
+
+    name = "guarddog-dependencies"
+    version = GuardDog.version
+    audience = Audience.USERS
+    experimental = True
+
+    def __init__(self, executable: str = "guarddog") -> None:
+        self.executable = executable
+
+    def version_command(self) -> Sequence[str]:
+        return (self.executable, "--version")
+
+    def command(self, scan: ScanInput, work: Path) -> Command | Parsed:
+        dependencies = scan.dependencies
+        if not dependencies.pins:
+            return Parsed(problems=tuple(map(unresolved_problem, dependencies.unresolved)))
+        (work / "requirements.txt").write_text(pins_file(dependencies.pins))
+        argv = (self.executable, "pypi", "verify", "requirements.txt", "--output-format", "json")
+        return Command(argv, work)
+
+    def parse(self, output: bytes, scan: ScanInput) -> Parsed:
+        pins = {normalized(pin.requirement.name): pin for pin in scan.dependencies.pins}
+        unreported = dict(pins)
+        findings: list[Finding] = []
+        problems = list(map(unresolved_problem, scan.dependencies.unresolved))
+        for item in json.loads(output):
+            package = normalized(item["dependency"])
+            unreported.pop(package, None)
+            here = Location(MANIFEST, pins[package].line if package in pins else 1)
+            about = {"package": param(item["dependency"]), "version": param(item["version"])}
+            found, failed = _package_results(item["result"], self.name, here, about)
+            findings += found
+            problems += failed
+        # GuardDog leaves out, without an error, a package it couldn't download.
+        problems += [_not_checked(pin) for pin in unreported.values()]
+        return Parsed(tuple(findings), tuple(problems))
+
+
+def _package_results(
+    result: Any, tool: str, here: Location, about: dict[str, str]
+) -> tuple[list[Finding], list[Problem]]:
+    if "results" not in result and not result["errors"]:
+        raise ValueError("guarddog reported neither results nor errors")
+    findings = []
+    for rule, matches in sorted(result.get("results", {}).items()):  # absent if not downloaded
+        if isinstance(matches, list):
+            findings += [
+                _code_finding(rule, m, tool, here, {**about, "file": param(m["location"])})
+                for m in matches
+            ]
+        elif isinstance(matches, str) and matches:
+            findings.append(_metadata_finding(rule, matches, tool, here, about))
+    return findings, _check_failures(result["errors"], here, about)
+
+
+def _code_finding(
+    rule: str, match: Any, tool: str, here: Location, about: dict[str, str]
+) -> Finding:
+    return Finding(
+        rule_id=f"{tool}/{_rule_name(rule)}",
+        severity=Severity.INFO,
+        confidence=Confidence.LOW,
+        location=here,
+        message_key="finding.tool_reported",
+        tool=tool,
+        evidence=evidence(match["code"]) or None,
+        params={**about, "message": param(match["message"])},
+    )
+
+
+def _metadata_finding(
+    rule: str, message: str, tool: str, here: Location, about: dict[str, str]
+) -> Finding:
+    return Finding(
+        rule_id=f"{tool}/{_rule_name(rule)}",
+        severity=Severity.NOTICE,
+        confidence=Confidence.LOW,
+        location=here,
+        message_key="finding.tool_reported",
+        tool=tool,
+        params={**about, "message": param(message)},
+    )
+
+
+def _check_failures(errors: Any, here: Location | None, about: dict[str, str]) -> list[Problem]:
+    return [
+        Problem(
+            "problem.tool_check_failed",
+            here,
+            {**about, "check": param(rule), "detail": param(str(message))},
+        )
+        for rule, message in sorted(errors.items())
+    ]
+
+
+def _not_checked(pin: Pin) -> Problem:
+    params = {"requirement": param(str(pin.requirement))}
+    return Problem("problem.dependency_not_checked", Location(MANIFEST, pin.line), params)
+
+
+def _place(match: Any, target: Path) -> tuple[str, int]:
+    path, _, line = match["location"].rpartition(":")
+    return relative(path, target), int(line)
+
+
+def _rule_name(rule: str) -> str:
+    return rule.replace("_", "-")

doorcheck/adapters/osv.py

@@ -0,0 +1,86 @@
+"""OSV-Scanner, for known vulnerabilities in the PyPI packages an integration installs.
+
+OSV-Scanner needs exact versions, so it gets each requirement pinned to the
+version a fresh install gets (doorcheck.dependencies), rebuilt from its parts
+so a manifest can't pass requirement-file options such as `-r /etc/passwd`.
+A requirement that couldn't be pinned is reported as not covered.
+
+OSV also lists packages known to be malicious (`MAL-` advisories). Those carry no
+severity score, so they are rated here instead of by score.
+"""
+
+import json
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from doorcheck.adapters.base import Audience, Command, Parsed, ScanInput
+from doorcheck.dependencies import MANIFEST, pins_file, unresolved_problem
+from doorcheck.findings import Confidence, Finding, Location, Severity, param
+from doorcheck.requirements import normalized
+
+MALICIOUS = "MAL-"
+
+
+class OsvScanner:
+    name = "osv-scanner"
+    version = "2.7.0"  # also pinned with its SHA-256 in .github/workflows/ci.yml
+    audience = Audience.USERS
+    experimental = False
+
+    def __init__(self, executable: str = "osv-scanner") -> None:
+        self.executable = executable
+
+    def version_command(self) -> Sequence[str]:
+        return (self.executable, "--version")
+
+    def command(self, scan: ScanInput, work: Path) -> Command | Parsed:
+        dependencies = scan.dependencies
+        if not dependencies.pins:
+            return Parsed(problems=tuple(map(unresolved_problem, dependencies.unresolved)))
+        (work / "requirements.txt").write_text(pins_file(dependencies.pins))
+        flags = ("--format", "json", "--no-resolve", "-L", "requirements.txt")
+        # Exit code 1 means vulnerabilities were found.
+        return Command((self.executable, "scan", "source", *flags), work, frozenset({0, 1}))
+
+    def parse(self, output: bytes, scan: ScanInput) -> Parsed:
+        lines = {normalized(pin.requirement.name): pin.line for pin in scan.dependencies.pins}
+        findings = tuple(
+            _finding(entry["package"], group, entry["vulnerabilities"], lines)
+            for result in json.loads(output)["results"]
+            for entry in result["packages"]
+            for group in entry["groups"]
+        )
+        return Parsed(findings, tuple(map(unresolved_problem, scan.dependencies.unresolved)))
+
+
+def _finding(package: Any, group: Any, vulns: Any, lines: dict[str, int]) -> Finding:
+    ids = group["ids"]
+    summary = next((str(v.get("summary") or "") for v in vulns if v["id"] in ids), "")
+    name, version = package["name"], package["version"]
+    malicious = any(str(i).startswith(MALICIOUS) for i in ids)
+    return Finding(
+        rule_id="osv/malicious-package" if malicious else "osv/known-vulnerability",
+        severity=Severity.SERIOUS if malicious else _severity(group.get("max_severity")),
+        confidence=Confidence.HIGH,
+        location=Location(MANIFEST, lines.get(normalized(name), 1)),
+        message_key="finding.malicious_package" if malicious else "finding.known_vulnerability",
+        tool=OsvScanner.name,
+        params={
+            "package": param(name),
+            "version": param(version),
+            "ids": param(", ".join(ids)),
+            "summary": param(summary),
+        },
+    )
+
+
+def _severity(score: object) -> Severity:
+    """From the group's highest CVSS score; an unscored advisory is still worth a look."""
+    try:
+        value = float(str(score))
+    except ValueError:
+        return Severity.REVIEW
+    if value >= 7:
+        return Severity.SERIOUS
+    return Severity.REVIEW if value >= 4 else Severity.NOTICE

doorcheck/adapters/process.py

@@ -0,0 +1,69 @@
+"""Bound tool output and stop its process group when a run ends (POSIX hosts)."""
+
+import os
+import selectors
+import signal
+import subprocess
+import time
+from collections.abc import Mapping, Sequence
+from contextlib import suppress
+from pathlib import Path
+
+CHUNK_BYTES = 64 * 1024
+
+
+class OutputLimitError(Exception):
+    """The combined stdout and stderr exceeded the allowed bytes."""
+
+
+def capture(
+    argv: Sequence[str], cwd: Path, env: Mapping[str, str], timeout: float, limit: int
+) -> subprocess.CompletedProcess[bytes]:
+    deadline = time.monotonic() + timeout
+    with subprocess.Popen(  # noqa: S603 - adapter-owned argv, never a shell
+        argv,
+        cwd=cwd,
+        env=env,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        start_new_session=True,
+    ) as process:
+        try:
+            output, errors = _read(process, deadline, limit)
+            code = process.wait(timeout=deadline - time.monotonic())
+            return subprocess.CompletedProcess(argv, code, bytes(output), bytes(errors))
+        finally:
+            _stop(process)
+
+
+def _read(
+    process: subprocess.Popen[bytes], deadline: float, limit: int
+) -> tuple[bytearray, bytearray]:
+    # PIPE guarantees these streams; the assertions only narrow their static types.
+    assert process.stdout is not None  # pragma: no mutate - PIPE invariant  # noqa: S101
+    assert process.stderr is not None  # pragma: no mutate - PIPE invariant  # noqa: S101
+    output, errors = bytearray(), bytearray()
+    with selectors.DefaultSelector() as selector:
+        selector.register(process.stdout, selectors.EVENT_READ, output)
+        selector.register(process.stderr, selectors.EVENT_READ, errors)
+        while selector.get_map():
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise subprocess.TimeoutExpired(process.args, 0)
+            for key, _ in selector.select(remaining):
+                budget = limit - len(output) - len(errors)
+                chunk = os.read(key.fd, min(CHUNK_BYTES, budget + 1))
+                if len(chunk) > budget:
+                    raise OutputLimitError
+                if chunk:
+                    key.data.extend(chunk)
+                else:
+                    selector.unregister(key.fileobj)
+    return output, errors
+
+
+def _stop(process: subprocess.Popen[bytes]) -> None:
+    # Descendants may still hold a pipe open after the main tool exits.
+    with suppress(ProcessLookupError):
+        os.killpg(process.pid, signal.SIGKILL)

doorcheck/adapters/registry.py

@@ -0,0 +1,62 @@
+"""Adapters are found through the `doorcheck.adapters` entry-point group, so a new
+tool plugs in by declaring one in its own package; the pipeline doesn't change.
+
+An installed package can add an adapter, so a broken one is reported by name
+instead of stopping every other tool from running.
+"""
+
+from dataclasses import dataclass
+from importlib.metadata import EntryPoint, entry_points
+
+from doorcheck.adapters.base import Adapter, Audience
+
+GROUP = "doorcheck.adapters"
+
+
+@dataclass(frozen=True, slots=True)
+class Loaded:
+    adapters: dict[str, Adapter]
+    problems: dict[str, str]  # entry-point name -> why it couldn't be loaded
+
+    def selected(self, audience: Audience, experimental: bool = False) -> list[Adapter]:
+        """The adapters for one audience; experimental ones only when asked for."""
+        return [
+            adapter
+            for _, adapter in sorted(self.adapters.items())
+            if adapter.audience is audience and (experimental or not adapter.experimental)
+        ]
+
+
+def load(points: tuple[EntryPoint, ...] | None = None) -> Loaded:
+    adapters: dict[str, Adapter] = {}
+    problems: dict[str, str] = {}
+    for point in points if points is not None else tuple(entry_points(group=GROUP)):
+        try:
+            adapter = point.load()()
+            problem = _problem(adapter, point.name)
+        except Exception as error:  # a third-party plugin can fail in any way
+            problems[point.name] = f"{type(error).__name__}: {error}"
+            continue
+        if problem:
+            problems[point.name] = problem
+            continue
+        adapters[point.name] = adapter
+    return Loaded(adapters, problems)
+
+
+def _problem(adapter: object, name: str) -> str:
+    called = getattr(adapter, "name", None)
+    if called != name:
+        return f"adapter calls itself {called!r}"
+    if not isinstance(getattr(adapter, "audience", None), Audience):
+        return "adapter doesn't say who its results are for (audience)"
+    if not isinstance(getattr(adapter, "experimental", None), bool):
+        return "adapter doesn't say whether it is experimental"
+    for field in ("version", "executable"):
+        value = getattr(adapter, field, None)
+        if not isinstance(value, str) or not value:
+            return f"adapter has no valid {field}"
+    for method in ("version_command", "command", "parse"):
+        if not callable(getattr(adapter, method, None)):
+            return f"adapter has no callable {method}"
+    return ""