coldrun 0.1.0__py3-none-any.whl

coldrun/fetch/base.py

@@ -0,0 +1,137 @@
+"""Shared pieces of the fetch step: errors, the fetched-source record and the quarantine.
+
+A quarantine directory holds exactly one fetched source plus a ``source.json``
+describing where it came from. It is created mode 0700 and nothing in it is
+ever imported or executed by the host.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import stat
+import tempfile
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Protocol
+
+#: Largest script or archive coldrun will fetch, in bytes.
+MAX_SOURCE_BYTES = 64 * 1024 * 1024
+_FILENAME_OK = re.compile(r"[^A-Za-z0-9._+-]+")
+_HASH_PREFIX = 16
+
+
+class FetchError(Exception):
+    """A source could not be fetched.
+
+    Args:
+        what: What failed, in one sentence.
+        hint: The next command or action the user should try.
+    """
+
+    def __init__(self, what: str, hint: str) -> None:
+        """Keep both halves so the report can show them separately."""
+        super().__init__(f"{what} {hint}".strip())
+        self.what = what
+        self.hint = hint
+
+
+@dataclass(frozen=True, slots=True)
+class Fetched:
+    """A source that now sits in quarantine.
+
+    Attributes:
+        kind: Fetcher that produced it, such as ``file`` or ``url``.
+        origin: The spec as the user gave it.
+        path: The quarantined file.
+        sha256: Hex digest of the file contents.
+        size: Size in bytes.
+        fetched_at: UTC timestamp in ISO 8601.
+    """
+
+    kind: str
+    origin: str
+    path: Path
+    sha256: str
+    size: int
+    fetched_at: str
+
+    @property
+    def quarantine(self) -> Path:
+        """The directory holding the file and its ``source.json``."""
+        return self.path.parent
+
+    def to_json(self) -> str:
+        """Serialise for ``source.json``."""
+        data = asdict(self)
+        data["path"] = str(self.path)
+        return json.dumps(data, indent=2, sort_keys=True) + "\n"
+
+
+class Fetcher(Protocol):
+    """One way of obtaining a source."""
+
+    kind: str
+
+    def matches(self, spec: str) -> bool:
+        """True when this fetcher understands ``spec``."""
+        ...
+
+    def fetch(self, spec: str, dest: Path) -> Path:
+        """Place the source inside ``dest`` and return the file path.
+
+        ``dest`` already exists, is empty and is private to this fetch.
+        Raise :class:`FetchError` on any failure.
+        """
+        ...
+
+
+def safe_filename(name: str, default: str = "script") -> str:
+    """Reduce an arbitrary name to something safe to create in quarantine."""
+    base = Path(name).name
+    cleaned = _FILENAME_OK.sub("_", base).strip("._")
+    if not cleaned or cleaned in {".", ".."}:
+        return default
+    return cleaned[:128]
+
+
+def sha256_of(path: Path) -> str:
+    """Hex SHA-256 of a file, streamed."""
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def new_quarantine(root: Path) -> Path:
+    """Create a fresh private directory under ``root`` and return it."""
+    root.mkdir(parents=True, exist_ok=True)
+    root.chmod(stat.S_IRWXU)
+    path = Path(tempfile.mkdtemp(prefix="q-", dir=root))
+    path.chmod(stat.S_IRWXU)
+    return path
+
+
+def seal(kind: str, origin: str, file: Path) -> Fetched:
+    """Hash the fetched file, make it read-only and write ``source.json``."""
+    size = file.stat().st_size
+    if size > MAX_SOURCE_BYTES:
+        file.unlink()
+        raise FetchError(
+            f"{origin} is {size} bytes, above the {MAX_SOURCE_BYTES} byte limit.",
+            "Fetch a smaller artefact or extract the one script you need.",
+        )
+    file.chmod(stat.S_IRUSR)
+    record = Fetched(
+        kind=kind,
+        origin=origin,
+        path=file,
+        sha256=sha256_of(file),
+        size=size,
+        fetched_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+    )
+    (file.parent / "source.json").write_text(record.to_json())
+    return record

coldrun/fetch/local.py

@@ -0,0 +1,46 @@
+"""Fetch a script that is already on disk by copying it into quarantine."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from coldrun.fetch.base import FetchError, safe_filename
+
+
+class LocalFetcher:
+    """Copies a regular file. Directories and archives come later."""
+
+    kind = "file"
+
+    def matches(self, spec: str) -> bool:
+        """Anything that is not a URL scheme is treated as a path."""
+        return "://" not in spec
+
+    def fetch(self, spec: str, dest: Path) -> Path:
+        """Copy ``spec`` into ``dest`` without following it anywhere surprising."""
+        src = Path(spec).expanduser()
+        if not src.exists():
+            raise FetchError(
+                f"{spec} does not exist.",
+                "Check the path, or pass a URL such as https://… to fetch it.",
+            )
+        if src.is_dir():
+            raise FetchError(
+                f"{spec} is a directory.",
+                "Point coldrun at the script inside it; repos arrive with the GitHub fetcher.",
+            )
+        resolved = src.resolve()
+        if not resolved.is_file():
+            raise FetchError(
+                f"{spec} is not a regular file.",
+                "coldrun fetches scripts and archives only.",
+            )
+        target = dest / safe_filename(src.name)
+        try:
+            shutil.copyfile(resolved, target, follow_symlinks=False)
+        except OSError as exc:
+            raise FetchError(
+                f"Could not read {spec}: {exc.strerror}.", "Check permissions."
+            ) from exc
+        return target

coldrun/fetch/url.py

@@ -0,0 +1,136 @@
+"""Fetch a script from a plain http or https URL.
+
+Downloads stream to disk with a size cap. Redirects are followed only to
+http or https, never to ``file://`` or anything else that could reach the
+host, and the GitHub ``blob`` and gist page forms are rewritten to their raw
+equivalents so the user can paste what the browser shows.
+"""
+
+from __future__ import annotations
+
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import TYPE_CHECKING, Any
+
+from coldrun import __version__
+from coldrun.fetch.base import MAX_SOURCE_BYTES, FetchError, safe_filename
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+TIMEOUT_SECONDS = 30
+MAX_REDIRECTS = 5
+_CHUNK = 256 * 1024
+_GITHUB_BLOB = re.compile(r"^https://github\.com/([^/]+)/([^/]+)/blob/([^/]+)/(.+)$")
+_GITHUB_RAW = re.compile(r"^https://raw\.githubusercontent\.com/([^/]+)/([^/]+)/([^/]+)/(.+)$")
+
+
+class _SafeRedirects(urllib.request.HTTPRedirectHandler):
+    """Refuse redirects that leave http or https, and cap how many we follow.
+
+    The check runs before urllib's own handling so the user sees why the
+    fetch stopped instead of a bare ``HTTP 302``.
+    """
+
+    def http_error_302(
+        self,
+        req: urllib.request.Request,
+        fp: Any,  # noqa: ANN401 - urllib's own signature
+        code: int,
+        msg: str,
+        headers: Any,  # noqa: ANN401
+    ) -> Any:  # noqa: ANN401
+        location = headers.get("location") or headers.get("uri") or ""
+        newurl = urllib.parse.urljoin(req.full_url, location)
+        scheme = urllib.parse.urlsplit(newurl).scheme
+        if scheme not in {"http", "https"}:
+            raise FetchError(
+                f"Redirect to {scheme}:// refused.",
+                "Only http and https destinations are followed.",
+            )
+        hops = sum(getattr(req, "redirect_dict", {}).values())
+        if hops >= MAX_REDIRECTS:
+            raise FetchError("Too many redirects.", "Fetch the final URL directly.")
+        return super().http_error_302(req, fp, code, msg, headers)
+
+    http_error_301 = http_error_303 = http_error_307 = http_error_308 = http_error_302
+
+
+def to_raw(url: str) -> str:
+    """Turn a GitHub ``blob`` page URL into its raw download URL."""
+    if m := _GITHUB_BLOB.match(url):
+        owner, repo, ref, path = m.groups()
+        return f"https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}"
+    return url
+
+
+def filename_for(url: str) -> str:
+    """Pick the quarantine file name from the URL path."""
+    return safe_filename(urllib.parse.unquote(urllib.parse.urlsplit(url).path))
+
+
+class UrlFetcher:
+    """Plain downloads. Repos, gists and exploit-db have their own fetchers."""
+
+    kind = "url"
+
+    def __init__(self, opener: urllib.request.OpenerDirector | None = None) -> None:
+        """Use ``opener`` for requests; tests inject one, callers leave it."""
+        self._opener = opener or urllib.request.build_opener(_SafeRedirects())
+
+    def matches(self, spec: str) -> bool:
+        """Accept http and https only; other schemes are refused by :func:`fetch`."""
+        return spec.startswith(("http://", "https://"))
+
+    def fetch(self, spec: str, dest: Path) -> Path:
+        """Download ``spec`` into ``dest`` with a size cap and a timeout."""
+        url = to_raw(spec)
+        target = dest / filename_for(url)
+        req = urllib.request.Request(  # noqa: S310 - scheme checked by matches()
+            url, headers={"User-Agent": f"coldrun/{__version__}"}
+        )
+        try:
+            with self._opener.open(req, timeout=TIMEOUT_SECONDS) as resp:
+                declared = resp.headers.get("Content-Length")
+                if declared and int(declared) > MAX_SOURCE_BYTES:
+                    raise FetchError(
+                        f"{url} is {declared} bytes, above the {MAX_SOURCE_BYTES} byte limit.",
+                        "Fetch a smaller artefact.",
+                    )
+                self._stream(resp, target, url)
+        except urllib.error.HTTPError as exc:
+            target.unlink(missing_ok=True)
+            if 300 <= exc.code < 400:  # noqa: PLR2004 - HTTP redirect class
+                # urllib gives up on loops and repeated hops with a 3xx error.
+                raise FetchError("Too many redirects.", "Fetch the final URL directly.") from exc
+            raise FetchError(
+                f"{url} returned HTTP {exc.code}.",
+                "Check the URL in a browser; for private repos use a local clone.",
+            ) from exc
+        except urllib.error.URLError as exc:
+            target.unlink(missing_ok=True)
+            raise FetchError(
+                f"Could not reach {url}: {exc.reason}.",
+                "Check the host name and your network, then retry.",
+            ) from exc
+        except TimeoutError as exc:
+            target.unlink(missing_ok=True)
+            raise FetchError(f"{url} timed out after {TIMEOUT_SECONDS}s.", "Retry later.") from exc
+        return target
+
+    @staticmethod
+    def _stream(resp: Any, target: Path, url: str) -> None:  # noqa: ANN401 - http.client response
+        written = 0
+        with target.open("wb") as out:
+            while chunk := resp.read(_CHUNK):
+                written += len(chunk)
+                if written > MAX_SOURCE_BYTES:
+                    out.close()
+                    target.unlink(missing_ok=True)
+                    raise FetchError(
+                        f"{url} exceeded the {MAX_SOURCE_BYTES} byte limit while downloading.",
+                        "Fetch a smaller artefact.",
+                    )
+                out.write(chunk)

coldrun/pipeline.py

@@ -0,0 +1 @@
+"""The eight pipeline steps: fetch, detect, resolve, vet, decide, build, run, report."""

coldrun/report.py

@@ -0,0 +1,195 @@
+"""Render what ran, what was blocked and the exit code.
+
+Human output goes through Rich to stderr-safe consoles; the JSON form
+arrives with the vetting milestone. Errors from any pipeline step are shown
+the same way: what failed, then the next command to try.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from coldrun.vet.findings import Severity
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from coldrun.detect import Detection
+    from coldrun.fetch.base import Fetched
+    from coldrun.runners.base import DepSet
+    from coldrun.vet.findings import Finding
+
+
+class ExitCode(IntEnum):
+    """Exit codes coldrun uses for its own failures.
+
+    Anything else is the script's own exit code, passed through.
+    """
+
+    OK = 0
+    REFUSED = 100
+    SANDBOX_FAILED = 101
+    DEPS_FAILED = 102
+    USAGE = 2
+
+
+@runtime_checkable
+class UserFacingError(Protocol):
+    """Errors that carry a one-sentence cause and a next step."""
+
+    what: str
+    hint: str
+
+
+@dataclass(slots=True)
+class Report:
+    """Everything the user should know about one run.
+
+    Fields are filled in as the pipeline advances, so a report rendered after
+    a failure shows how far it got.
+    """
+
+    source: Fetched | None = None
+    detection: Detection | None = None
+    deps: DepSet | None = None
+    findings: list[Finding] = field(default_factory=list)
+    verdict: str | None = None
+    backend: str | None = None
+    net: str = "none"
+    blocked: list[str] = field(default_factory=list)
+    exit_code: int | None = None
+    out_dir: str | None = None
+    wrote: list[str] = field(default_factory=list)
+
+    @property
+    def max_severity(self) -> Severity | None:
+        """Highest severity among the findings, or ``None``."""
+        if not self.findings:
+            return None
+        return max((f.severity for f in self.findings), key=lambda s: s.rank)
+
+
+_SEVERITY_STYLE = {
+    Severity.INFO: "dim",
+    Severity.LOW: "green",
+    Severity.MEDIUM: "yellow",
+    Severity.HIGH: "bold red",
+}
+
+
+def default_blocked(net: str) -> list[str]:
+    """The protections every run gets, phrased for the report."""
+    blocked = [
+        "home directory, SSH keys, browser profiles, cloud credentials",
+        "Docker socket and D-Bus session",
+        "writes outside /work and /tmp",
+        "capabilities and privilege escalation",
+    ]
+    if net == "none":
+        blocked.insert(0, "all network access")
+    elif net == "allow":
+        blocked.insert(0, "network except --allow-host destinations")
+    return blocked
+
+
+def make_console(*, stderr: bool = False, force_plain: bool = False) -> Console:
+    """A console for reports; ``force_plain`` disables colour and width tricks for tests."""
+    if force_plain:
+        return Console(stderr=stderr, color_system=None, width=100, highlight=False)
+    return Console(stderr=stderr, highlight=False)
+
+
+def render(report: Report, console: Console) -> None:
+    """Print the run summary."""
+    table = Table(show_header=False, box=None, pad_edge=False, padding=(0, 1))
+    table.add_column("key", style="bold", no_wrap=True)
+    table.add_column("value")
+
+    if report.source is not None:
+        table.add_row("source", f"{report.source.origin}  ({report.source.kind})")
+        table.add_row("sha256", report.source.sha256)
+    if report.detection is not None:
+        det = report.detection
+        why = ", ".join(det.reasons) or "runner score"
+        table.add_row("runner", f"{det.runner.name}  ({det.confidence:.0%}: {why})")
+    if report.deps is not None:
+        table.add_row("dependencies", _format_deps(report.deps))
+    if report.findings:
+        table.add_row("findings", _format_findings(report.findings))
+    if report.verdict is not None:
+        table.add_row("verdict", report.verdict)
+    if report.backend is not None:
+        table.add_row("sandbox", f"{report.backend}, network {report.net}")
+    if report.blocked:
+        table.add_row("blocked", "\n".join(report.blocked))
+    if report.wrote:
+        where = f" -> {report.out_dir}" if report.out_dir else ""
+        table.add_row("wrote", "\n".join(report.wrote) + where)
+    if report.exit_code is not None:
+        table.add_row("exit code", _format_exit(report.exit_code))
+    console.print(table)
+
+
+def render_error(err: BaseException, console: Console) -> None:
+    """Print a failure as *what failed* then *next: what to try*."""
+    if isinstance(err, UserFacingError):
+        console.print(Text(err.what, style="bold red"))
+        console.print(Text(f"next: {err.hint}", style="yellow"))
+    else:
+        console.print(Text(f"{type(err).__name__}: {err}", style="bold red"))
+        console.print(Text("next: rerun with COLDRUN_DEBUG=1 and open an issue.", style="yellow"))
+
+
+def exit_code_for(err: BaseException) -> int:
+    """Map a pipeline error to the exit code the CLI should use."""
+    code = getattr(err, "exit_code", None)
+    if isinstance(code, int):
+        return code
+    by_name = {
+        "FetchError": ExitCode.USAGE,
+        "DetectError": ExitCode.USAGE,
+        "SandboxError": ExitCode.SANDBOX_FAILED,
+        "DepsError": ExitCode.DEPS_FAILED,
+        "RefusedError": ExitCode.REFUSED,
+    }
+    return int(by_name.get(type(err).__name__, 1))
+
+
+def _format_deps(deps: DepSet) -> str:
+    parts: list[str] = []
+    if deps.interpreter:
+        parts.append(deps.interpreter)
+    if deps.packages:
+        eco = f"{deps.ecosystem}: " if deps.ecosystem else ""
+        parts.append(eco + ", ".join(deps.packages))
+    if deps.system_binaries:
+        parts.append("binaries: " + ", ".join(deps.system_binaries))
+    if not parts:
+        return "none"
+    return "; ".join(parts) + f"  (from {deps.source})"
+
+
+def _format_findings(findings: Sequence[Finding]) -> Text:
+    text = Text()
+    for i, f in enumerate(sorted(findings, key=lambda x: -x.severity.rank)):
+        if i:
+            text.append("\n")
+        text.append(f"{f.severity.value:<6}", style=_SEVERITY_STYLE[f.severity])
+        text.append(f" {f.rule_id}  {f.location()}: {f.message}")
+    return text
+
+
+def _format_exit(code: int) -> Text:
+    if code == 0:
+        return Text("0", style="green")
+    try:
+        label = ExitCode(code).name.lower().replace("_", " ")
+    except ValueError:
+        return Text(str(code), style="red")
+    return Text(f"{code} ({label})", style="red")

coldrun/runners/__init__.py

@@ -0,0 +1,15 @@
+"""Language runners: one module per language plus the shared base contract."""
+
+from __future__ import annotations
+
+from coldrun.runners.base import DepSet, Runner, RunnerInfo
+from coldrun.runners.registry import Registry, RunnerNotFoundError, default_registry
+
+__all__ = [
+    "DepSet",
+    "Registry",
+    "Runner",
+    "RunnerInfo",
+    "RunnerNotFoundError",
+    "default_registry",
+]

coldrun/runners/base.py

@@ -0,0 +1,97 @@
+"""The contract every language runner implements.
+
+A runner knows how to recognise a script, work out what it needs, and produce
+the commands that install those needs and run the script. The commands are
+executed by the sandbox, never by the runner itself, and never on the host.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from coldrun.vet.findings import Finding
+
+
+@dataclass(frozen=True, slots=True)
+class DepSet:
+    """Everything a script needs before it can run.
+
+    Attributes:
+        ecosystem: Package registry the packages come from, such as ``pypi``
+            or ``npm``. Empty when there are no packages.
+        packages: Package requirement strings as the ecosystem spells them,
+            for example ``requests>=2.31``. Sorted and de-duplicated.
+        system_binaries: Command names the script expects on ``PATH``.
+        interpreter: Interpreter requirement, such as ``python>=3.10`` or
+            ``bash``. ``None`` for prebuilt binaries.
+        source: Where the requirements came from, for the report: a manifest
+            file name or ``inferred``.
+    """
+
+    ecosystem: str = ""
+    packages: tuple[str, ...] = ()
+    system_binaries: tuple[str, ...] = ()
+    interpreter: str | None = None
+    source: str = "inferred"
+
+    def __post_init__(self) -> None:
+        """Normalise ordering so equal needs compare and hash equal."""
+        object.__setattr__(self, "packages", tuple(sorted(set(self.packages))))
+        object.__setattr__(self, "system_binaries", tuple(sorted(set(self.system_binaries))))
+
+    @property
+    def is_empty(self) -> bool:
+        """True when nothing has to be installed."""
+        return not self.packages and not self.system_binaries
+
+
+@runtime_checkable
+class Runner(Protocol):
+    """What a language plugin provides.
+
+    Runners are discovered through the ``coldrun.runners`` entry-point group.
+    Each entry point names a class with a no-argument constructor, or a
+    zero-argument factory, that yields an object satisfying this protocol.
+    """
+
+    name: str
+
+    def detect(self, path: Path) -> float:
+        """Return confidence from 0.0 to 1.0 that this runner owns ``path``.
+
+        Only inspect the bytes; never execute or import the file.
+        """
+        ...
+
+    def resolve_deps(self, path: Path) -> DepSet:
+        """Work out what ``path`` needs, from a manifest or from the code."""
+        ...
+
+    def install_cmd(self, deps: DepSet) -> list[str]:
+        """Argument list that installs ``deps``. Runs inside the sandbox.
+
+        Return an empty list when nothing has to be installed.
+        """
+        ...
+
+    def run_cmd(self, path: Path, args: list[str]) -> list[str]:
+        """Argument list that runs ``path`` with ``args``. Runs inside the sandbox."""
+        ...
+
+    def vet(self, path: Path, deps: DepSet) -> list[Finding]:
+        """Language-specific checks on the script and its dependencies."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class RunnerInfo:
+    """A loaded runner together with where it came from."""
+
+    runner: Runner
+    entry_point: str
+    distribution: str | None = None
+    load_error: str | None = field(default=None, compare=False)