coldrun 0.1.0__py3-none-any.whl

coldrun/__init__.py

@@ -0,0 +1,12 @@
+"""coldrun: fetch, vet and sandbox any downloaded script in one command."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("coldrun")
+except PackageNotFoundError:  # pragma: no cover - only when run from a bare checkout
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

coldrun/cli.py

@@ -0,0 +1,53 @@
+"""Typer application for the ``coldrun`` command.
+
+This module wires command-line options to the pipeline and holds no logic of
+its own. Commands are added here as the milestones land.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from coldrun import __version__
+from coldrun import doctor as doctor_mod
+
+app = typer.Typer(
+    name="coldrun",
+    help="Fetch, vet and sandbox any downloaded script in one command.",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"coldrun {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show the version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Fetch, vet and sandbox any downloaded script in one command."""
+
+
+@app.command()
+def doctor() -> None:
+    """Check bwrap, podman, uv and kernel support, and say how to fix what is missing."""
+    results = doctor_mod.run_checks()
+    doctor_mod.render(results, Console(highlight=False))
+    raise typer.Exit(code=1 if doctor_mod.has_failures(results) else 0)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

coldrun/config.py

@@ -0,0 +1,29 @@
+"""Where coldrun keeps its files on the host.
+
+Only paths live here for now; the TOML config file arrives when there are
+settings worth persisting. Both directories honour the XDG variables.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+APP = "coldrun"
+
+
+def config_dir() -> Path:
+    """``$XDG_CONFIG_HOME/coldrun`` or ``~/.config/coldrun``."""
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / APP
+
+
+def cache_dir() -> Path:
+    """``$XDG_CACHE_HOME/coldrun`` or ``~/.cache/coldrun``."""
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / APP
+
+
+def quarantine_root() -> Path:
+    """Parent of every quarantine directory, under the cache."""
+    return cache_dir() / "quarantine"

coldrun/detect.py

@@ -0,0 +1,223 @@
+"""Pick a runner from shebang, extension and file magic.
+
+The language knowledge lives in the runners: each one scores a file through
+``Runner.detect``. This module supplies the cheap, shared signals runners
+build on, asks every registered runner, and turns the scores into one choice
+or one clear error. Only bytes are inspected; nothing is executed or imported.
+"""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from coldrun.runners.base import Runner
+    from coldrun.runners.registry import Registry
+
+#: A runner must be at least this sure before coldrun runs anything.
+THRESHOLD = 0.5
+_SNIFF_BYTES = 512
+_SHEBANG_MAX = 256
+
+
+class FileKind(str, Enum):
+    """Coarse shape of a file, from its first bytes."""
+
+    SCRIPT = "script"  # has a shebang
+    TEXT = "text"  # readable text without a shebang
+    ELF = "elf"
+    PE = "pe"
+    MACHO = "macho"
+    ZIP = "zip"
+    GZIP = "gzip"
+    XZ = "xz"
+    BZIP2 = "bzip2"
+    ZSTD = "zstd"
+    BINARY = "binary"  # other non-text
+    EMPTY = "empty"
+
+
+_MAGIC: tuple[tuple[bytes, FileKind], ...] = (
+    (b"\x7fELF", FileKind.ELF),
+    (b"MZ", FileKind.PE),
+    (b"\xcf\xfa\xed\xfe", FileKind.MACHO),
+    (b"\xfe\xed\xfa\xcf", FileKind.MACHO),
+    (b"\xca\xfe\xba\xbe", FileKind.MACHO),
+    (b"PK\x03\x04", FileKind.ZIP),
+    (b"\x1f\x8b", FileKind.GZIP),
+    (b"\xfd7zXZ\x00", FileKind.XZ),
+    (b"BZh", FileKind.BZIP2),
+    (b"\x28\xb5\x2f\xfd", FileKind.ZSTD),
+)
+_TEXT_BYTES = bytes(range(0x20, 0x7F)) + b"\t\n\r\x0b\x0c\x1b"
+_ASCII_LIMIT = 0x80
+_BINARY_RATIO = 0.1
+
+
+class DetectError(Exception):
+    """No runner could be chosen.
+
+    Args:
+        what: Why, in one sentence.
+        hint: What the user can do, usually ``--lang``.
+        candidates: Runner names and scores that were considered.
+    """
+
+    def __init__(self, what: str, hint: str, candidates: list[tuple[str, float]]) -> None:
+        """Keep the parts separate for the report."""
+        super().__init__(f"{what} {hint}")
+        self.what = what
+        self.hint = hint
+        self.candidates = candidates
+
+
+@dataclass(frozen=True, slots=True)
+class Signals:
+    """The shared evidence about one file."""
+
+    kind: FileKind
+    shebang: str | None
+    interpreter: str | None
+    extension: str
+
+    @property
+    def is_text(self) -> bool:
+        """True for scripts and plain text."""
+        return self.kind in {FileKind.SCRIPT, FileKind.TEXT}
+
+
+@dataclass(frozen=True, slots=True)
+class Detection:
+    """The chosen runner and why."""
+
+    runner: Runner
+    confidence: float
+    signals: Signals
+    forced: bool = False
+    candidates: list[tuple[str, float]] = field(default_factory=list)
+
+    @property
+    def reasons(self) -> list[str]:
+        """Human-readable evidence for the report."""
+        out: list[str] = []
+        if self.forced:
+            out.append(f"--lang {self.runner.name}")
+        if self.signals.shebang:
+            out.append(f"shebang {self.signals.shebang}")
+        if self.signals.extension:
+            out.append(f"extension {self.signals.extension}")
+        if not self.signals.is_text:
+            out.append(f"magic {self.signals.kind.value}")
+        return out
+
+
+def sniff_kind(path: Path) -> FileKind:
+    """Classify a file from its first bytes."""
+    with path.open("rb") as fh:
+        head = fh.read(_SNIFF_BYTES)
+    if not head:
+        return FileKind.EMPTY
+    for magic, kind in _MAGIC:
+        if head.startswith(magic):
+            return kind
+    if head.startswith(b"#!"):
+        return FileKind.SCRIPT
+    if b"\x00" in head:
+        return FileKind.BINARY
+    sample = head.translate(None, _TEXT_BYTES)
+    # Allow UTF-8 multibyte sequences; anything with lots of control bytes is binary.
+    control = sum(1 for b in sample if b < _ASCII_LIMIT)
+    return FileKind.BINARY if control > len(head) * _BINARY_RATIO else FileKind.TEXT
+
+
+def read_shebang(path: Path) -> str | None:
+    """Return the shebang line without ``#!`` and trailing whitespace, or ``None``."""
+    with path.open("rb") as fh:
+        head = fh.read(_SHEBANG_MAX)
+    if not head.startswith(b"#!"):
+        return None
+    line = head[2:].split(b"\n", 1)[0].strip()
+    try:
+        return line.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
+def interpreter_from_shebang(shebang: str) -> str | None:
+    """Name of the interpreter a shebang asks for, such as ``python3`` or ``bash``.
+
+    Handles ``/usr/bin/env name``, ``/usr/bin/env -S name args`` and plain
+    ``/bin/name``. Returns ``None`` for an unparsable line.
+    """
+    try:
+        parts = shlex.split(shebang)
+    except ValueError:
+        return None
+    if not parts:
+        return None
+    if Path(parts[0]).name == "env":
+        rest = [p for p in parts[1:] if not p.startswith("-") and "=" not in p]
+        return Path(rest[0]).name if rest else None
+    return Path(parts[0]).name
+
+
+def signals_for(path: Path) -> Signals:
+    """Gather the shared evidence for ``path``."""
+    kind = sniff_kind(path)
+    shebang = read_shebang(path) if kind == FileKind.SCRIPT else None
+    return Signals(
+        kind=kind,
+        shebang=shebang,
+        interpreter=interpreter_from_shebang(shebang) if shebang else None,
+        extension=path.suffix.lower(),
+    )
+
+
+def detect(path: Path, registry: Registry, lang: str | None = None) -> Detection:
+    """Choose the runner for ``path``.
+
+    Args:
+        path: The quarantined file.
+        registry: Where runners come from.
+        lang: ``--lang`` override; skips scoring and takes that runner.
+
+    Raises:
+        DetectError: When nothing is confident enough, or ``lang`` is unknown.
+    """
+    signals = signals_for(path)
+    if lang is not None:
+        try:
+            runner = registry.get(lang)
+        except LookupError as exc:
+            raise DetectError(
+                str(exc) + ".",
+                "Pick one of the available runners with --lang.",
+                [],
+            ) from exc
+        return Detection(runner=runner, confidence=1.0, signals=signals, forced=True)
+
+    scored: list[tuple[float, Runner]] = []
+    for runner in registry.all():
+        score = float(runner.detect(path))
+        scored.append((min(max(score, 0.0), 1.0), runner))
+    scored.sort(key=lambda s: s[0], reverse=True)
+    candidates = [(r.name, s) for s, r in scored]
+    if not scored or scored[0][0] < THRESHOLD:
+        what = f"Could not tell what kind of script {path.name} is ({signals.kind.value}"
+        what += f", shebang {signals.shebang}" if signals.shebang else ""
+        what += ")."
+        names = ", ".join(registry.names()) or "none installed"
+        raise DetectError(what, f"Force a runner with --lang NAME. Available: {names}.", candidates)
+    best, runner = scored[0]
+    if len(scored) > 1 and scored[1][0] == best:
+        tied = ", ".join(r.name for s, r in scored if s == best)
+        raise DetectError(
+            f"{path.name} matches more than one runner equally ({tied}).",
+            "Choose one with --lang NAME.",
+            candidates,
+        )
+    return Detection(runner=runner, confidence=best, signals=signals, candidates=candidates)

coldrun/doctor.py

@@ -0,0 +1,208 @@
+"""``coldrun doctor``: check bwrap, podman, uv and kernel support.
+
+Each check is a small function that returns a :class:`CheckResult` with the
+fix for its failure, so the output tells the user exactly what to run next.
+The probes are injectable for tests.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from rich.table import Table
+from rich.text import Text
+
+from coldrun.config import cache_dir
+from coldrun.sandbox import bwrap as bw
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+    from rich.console import Console
+
+MIN_PYTHON = (3, 10)
+
+
+class Status(str, Enum):
+    """Outcome of one check."""
+
+    PASS = "pass"  # noqa: S105 - a status, not a password
+    WARN = "warn"
+    FAIL = "fail"
+
+
+@dataclass(frozen=True, slots=True)
+class CheckResult:
+    """One line of doctor output."""
+
+    name: str
+    status: Status
+    detail: str
+    fix: str = ""
+
+
+def _run_version(argv: list[str]) -> str | None:
+    try:
+        out = subprocess.run(  # noqa: S603 - fixed argv of a known tool
+            argv, capture_output=True, text=True, check=False, timeout=10
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    line = (out.stdout or out.stderr).strip().splitlines()
+    return line[0] if line else None
+
+
+@dataclass(frozen=True, slots=True)
+class Probes:
+    """Host lookups the checks depend on; tests replace them."""
+
+    which: Callable[[str], str | None] = shutil.which
+    version_of: Callable[[list[str]], str | None] = _run_version
+    userns_problem: Callable[[], tuple[str, str] | None] = bw.userns_problem
+    tiocsti_blocked: Callable[[], bool] = bw.tiocsti_is_blocked
+    python_version: tuple[int, int] = sys.version_info[:2]
+    kernel: str = platform.release()
+    cache: Path | None = None
+
+
+def check_bwrap(p: Probes) -> CheckResult:
+    """Bubblewrap is installed."""
+    path = p.which("bwrap")
+    if path is None:
+        return CheckResult(
+            "bubblewrap",
+            Status.FAIL,
+            "not installed",
+            "sudo pacman -S bubblewrap  (Arch)  or  sudo apt install bubblewrap  (Debian, Kali)",
+        )
+    ver = p.version_of([path, "--version"]) or "version unknown"
+    return CheckResult("bubblewrap", Status.PASS, f"{path} ({ver})")
+
+
+def check_userns(p: Probes) -> CheckResult:
+    """Unprivileged user namespaces are allowed."""
+    problem = p.userns_problem()
+    if problem is None:
+        return CheckResult("user namespaces", Status.PASS, "unprivileged user namespaces allowed")
+    return CheckResult("user namespaces", Status.FAIL, problem[0], problem[1])
+
+
+def check_tiocsti(p: Probes) -> CheckResult:
+    """The kernel blocks TIOCSTI so interactive scripts can keep the terminal."""
+    if p.tiocsti_blocked():
+        return CheckResult("TIOCSTI", Status.PASS, "blocked by the kernel; TTY passthrough is safe")
+    return CheckResult(
+        "TIOCSTI",
+        Status.WARN,
+        "legacy TIOCSTI allowed; interactive scripts run in a new session (no job control)",
+        "sudo sysctl -w dev.tty.legacy_tiocsti=0  (kernel 6.2 or newer)",
+    )
+
+
+def check_podman(p: Probes) -> CheckResult:
+    """Podman is optional until a runner needs a full image."""
+    path = p.which("podman")
+    if path is None:
+        return CheckResult(
+            "podman",
+            Status.WARN,
+            "not installed; only needed for Python 2, Node, Go and Ruby runners (M5)",
+            "sudo pacman -S podman  or  sudo apt install podman",
+        )
+    ver = p.version_of([path, "--version"]) or "version unknown"
+    return CheckResult("podman", Status.PASS, f"{path} ({ver})")
+
+
+def check_uv(p: Probes) -> CheckResult:
+    """Uv installs Python dependencies inside the sandbox."""
+    path = p.which("uv")
+    if path is None:
+        return CheckResult(
+            "uv",
+            Status.WARN,
+            "not installed; needed by the Python runner (M2)",
+            "curl -LsSf https://astral.sh/uv/install.sh | sh   or   sudo pacman -S uv",
+        )
+    ver = p.version_of([path, "--version"]) or "version unknown"
+    return CheckResult("uv", Status.PASS, f"{path} ({ver})")
+
+
+def check_python(p: Probes) -> CheckResult:
+    """Python is new enough for coldrun itself."""
+    ver = ".".join(map(str, p.python_version))
+    if p.python_version < MIN_PYTHON:
+        return CheckResult(
+            "python", Status.FAIL, f"{ver} is too old", "coldrun needs Python 3.10 or newer"
+        )
+    return CheckResult("python", Status.PASS, f"{ver} ({p.kernel})")
+
+
+def check_cache(p: Probes) -> CheckResult:
+    """The cache directory can be created and written."""
+    path = p.cache if p.cache is not None else cache_dir()
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        probe = path / ".doctor-write-test"
+        probe.write_text("ok")
+        probe.unlink()
+    except OSError as exc:
+        return CheckResult(
+            "cache", Status.FAIL, f"{path}: {exc.strerror}", f"chown or chmod {path}"
+        )
+    return CheckResult("cache", Status.PASS, str(path))
+
+
+CHECKS: tuple[Callable[[Probes], CheckResult], ...] = (
+    check_python,
+    check_bwrap,
+    check_userns,
+    check_tiocsti,
+    check_podman,
+    check_uv,
+    check_cache,
+)
+
+
+def run_checks(probes: Probes | None = None) -> list[CheckResult]:
+    """Run every check and return the results in display order."""
+    p = probes or Probes()
+    return [check(p) for check in CHECKS]
+
+
+def has_failures(results: list[CheckResult]) -> bool:
+    """True when at least one check failed outright."""
+    return any(r.status is Status.FAIL for r in results)
+
+
+_STYLE = {Status.PASS: "green", Status.WARN: "yellow", Status.FAIL: "bold red"}
+
+
+def render(results: list[CheckResult], console: Console) -> None:
+    """Print the doctor table."""
+    table = Table(show_header=True, header_style="bold", box=None, pad_edge=False, padding=(0, 1))
+    table.add_column("check", no_wrap=True)
+    table.add_column("status", no_wrap=True)
+    table.add_column("detail")
+    for r in results:
+        detail = Text(r.detail)
+        if r.fix:
+            detail.append("\nfix: ", style="bold")
+            detail.append(r.fix)
+        table.add_row(r.name, Text(r.status.value, style=_STYLE[r.status]), detail)
+    console.print(table)
+    if has_failures(results):
+        console.print(
+            Text(
+                "coldrun cannot sandbox scripts until the failures above are fixed.",
+                style="bold red",
+            )
+        )
+    else:
+        console.print(Text("ready to run.", style="green"))

coldrun/fetch/__init__.py

@@ -0,0 +1,82 @@
+"""Fetchers that place a source into a quarantine directory without executing it.
+
+:func:`fetch` is the only entry point the pipeline uses. It picks the first
+fetcher whose :meth:`Fetcher.matches` accepts the spec, gives it a fresh
+quarantine directory, then seals the result with a hash and ``source.json``.
+"""
+
+from __future__ import annotations
+
+import shutil
+import urllib.parse
+from typing import TYPE_CHECKING
+
+from coldrun.config import quarantine_root
+from coldrun.fetch.base import (
+    MAX_SOURCE_BYTES,
+    Fetched,
+    Fetcher,
+    FetchError,
+    new_quarantine,
+    seal,
+)
+from coldrun.fetch.local import LocalFetcher
+from coldrun.fetch.url import UrlFetcher
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+__all__ = [
+    "MAX_SOURCE_BYTES",
+    "FetchError",
+    "Fetched",
+    "Fetcher",
+    "LocalFetcher",
+    "UrlFetcher",
+    "default_fetchers",
+    "fetch",
+]
+
+
+def default_fetchers() -> list[Fetcher]:
+    """Fetchers in the order they are tried. URL forms first, paths last."""
+    return [UrlFetcher(), LocalFetcher()]
+
+
+def _pick(spec: str, fetchers: Sequence[Fetcher]) -> Fetcher:
+    for f in fetchers:
+        if f.matches(spec):
+            return f
+    scheme = urllib.parse.urlsplit(spec).scheme or "that"
+    raise FetchError(
+        f"No fetcher understands {spec!r} ({scheme} is not supported).",
+        "Use a local path, an http(s) URL, or a GitHub blob URL.",
+    )
+
+
+def fetch(
+    spec: str, root: Path | None = None, fetchers: Sequence[Fetcher] | None = None
+) -> Fetched:
+    """Fetch ``spec`` into a new quarantine directory.
+
+    Args:
+        spec: Local path or URL as the user typed it.
+        root: Parent for quarantine directories; defaults to the cache.
+        fetchers: Override the fetcher list; tests use this.
+
+    Returns:
+        The sealed :class:`Fetched` record.
+
+    Raises:
+        FetchError: With what failed and what to try next. The quarantine
+            directory is removed on failure.
+    """
+    fetcher = _pick(spec, fetchers if fetchers is not None else default_fetchers())
+    qdir = new_quarantine(root if root is not None else quarantine_root())
+    try:
+        file = fetcher.fetch(spec, qdir)
+        return seal(fetcher.kind, spec, file)
+    except BaseException:
+        shutil.rmtree(qdir, ignore_errors=True)
+        raise