coldrun 0.1.0__tar.gz

coldrun-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.python-version
+
+# Tooling
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+site/
+
+# coldrun
+coldrun-out/

coldrun-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `coldrun doctor`: checks Python, bubblewrap, unprivileged user namespaces, TIOCSTI, podman, uv and the cache directory, prints pass/warn/fail with the exact fix, exits 1 on failures (#14).
+- Report layer: `Report` model filled in as the pipeline advances, a Rich summary of source, runner, dependencies, findings by severity, sandbox and network policy, what was blocked, files written and the exit code; errors always print what failed and `next:` what to try; `ExitCode` 100/101/102 (#13).
+- Bubblewrap sandbox backend and the policy model behind every backend: new user, PID, mount, IPC, UTS and network namespaces, no capabilities, `no_new_privs`, read-only `/usr`, private tmpfs `/tmp` and `/run`, scratch directory at `/work`, script mounted read-only, synthetic `/etc/passwd`, resolver and CA files only when network is allowed, environment cleared to an allowlist, `--rw` refused for `/`, `$HOME` and credential directories, TIOCSTI-aware TTY passthrough, and a probe that reports bubblewrap's own error with a `coldrun doctor` hint (#12).
+- Type detection: shared shebang, extension and file-magic signals (`detect.py`), every registered runner scores the file, the best above 0.5 wins, ties and low confidence produce an error naming the candidates and `--lang`; `--lang` forces a runner (#10).
+- Fetch step: local file and http(s) URL fetchers place the source in a private 0700 quarantine directory under `~/.cache/coldrun/quarantine/` with a `source.json` (origin, SHA-256, size, time). 64 MiB size cap, redirects limited to http(s), GitHub `blob` URLs rewritten to raw. XDG-aware config and cache paths in `config.py` (#9).
+- `Runner` protocol, `DepSet` and `Finding` models, and an entry-point registry (`coldrun.runners` group) that loads built-in and third-party runners, skips broken plugins with a logged reason, and a shared contract test suite in `tests/unit/runners/contract.py` (#11).
+
+### Changed
+
+- **Breaking:** the project is renamed from `muzzle` to `coldrun`: package, console script, entry-point group `coldrun.runners`, config path `~/.config/coldrun/` and cache path `~/.cache/coldrun/` (#50). The PyPI name `muzzle` belongs to another maintainer; `coldrun` is free everywhere.
+
+## [0.1.0] - 2026-11-12
+
+Foundation release (published under the former name `muzzle`): an empty `muzzle --version` that passes every check on a pull request. No fetching, vetting or sandboxing yet; that starts in M1.
+
+### Added
+
+- Package scaffold with the spec layout and `muzzle --version` (#1, #2).
+- Ruff lint and format, mypy strict and pre-commit hooks including a secrets scan and a Conventional Commits check (#3).
+- GitHub Actions workflows: CI (ruff, mypy, pytest 3.10 to 3.13, coverage, wheel build), integration (bubblewrap and Podman on the runner), CodeQL, security (pip-audit, gitleaks, Semgrep), PR lint, release and docs; Dependabot for uv and Actions (#5).
+- Bubblewrap smoke test in `tests/integration` proving user namespaces work on the runner (#5).
+- Issue templates (bug, feature, new runner, false positive), pull request template, CODEOWNERS, CONTRIBUTING, SECURITY and CODE_OF_CONDUCT (#4).
+- CLAUDE.md with the repo workflow, branch protection, code quality bar and the hard security rules for agents and contributors (#8).
+
+[Unreleased]: https://github.com/rj-karan/coldrun/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/rj-karan/coldrun/releases/tag/v0.0.1

coldrun-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KARAN RJ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

coldrun-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: coldrun
+Version: 0.1.0
+Summary: Fetch, vet and sandbox any downloaded script in one command
+Project-URL: Homepage, https://github.com/rj-karan/coldrun
+Project-URL: Repository, https://github.com/rj-karan/coldrun
+Project-URL: Issues, https://github.com/rj-karan/coldrun/issues
+Project-URL: Changelog, https://github.com/rj-karan/coldrun/blob/main/CHANGELOG.md
+Author: KARAN RJ
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bubblewrap,cli,sandbox,scripts,security
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# coldrun
+
+[![CI](https://github.com/rj-karan/coldrun/actions/workflows/ci.yml/badge.svg)](https://github.com/rj-karan/coldrun/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/rj-karan/coldrun/graph/badge.svg)](https://codecov.io/gh/rj-karan/coldrun)
+[![PyPI](https://img.shields.io/pypi/v/coldrun?label=pypi)](https://pypi.org/project/coldrun/)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+
+Fetch, vet and sandbox any downloaded script in one command.
+
+```
+coldrun run https://github.com/someone/tool/blob/main/script.py -- --target 10.10.11.5
+```
+
+coldrun takes a script from a file, URL, GitHub repo, gist or exploit-db ID,
+works out what it needs, checks it for behaviour aimed at your machine, and runs
+it inside a sandbox with no network and no access to your home directory.
+
+The project is under construction. The full specification is in
+[docs/SPEC.md](docs/SPEC.md).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

coldrun-0.1.0/README.md

@@ -0,0 +1,23 @@
+# coldrun
+
+[![CI](https://github.com/rj-karan/coldrun/actions/workflows/ci.yml/badge.svg)](https://github.com/rj-karan/coldrun/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/rj-karan/coldrun/graph/badge.svg)](https://codecov.io/gh/rj-karan/coldrun)
+[![PyPI](https://img.shields.io/pypi/v/coldrun?label=pypi)](https://pypi.org/project/coldrun/)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+
+Fetch, vet and sandbox any downloaded script in one command.
+
+```
+coldrun run https://github.com/someone/tool/blob/main/script.py -- --target 10.10.11.5
+```
+
+coldrun takes a script from a file, URL, GitHub repo, gist or exploit-db ID,
+works out what it needs, checks it for behaviour aimed at your machine, and runs
+it inside a sandbox with no network and no access to your home directory.
+
+The project is under construction. The full specification is in
+[docs/SPEC.md](docs/SPEC.md).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

coldrun-0.1.0/packaging/README.md

@@ -0,0 +1 @@
+# AUR and Debian packaging land here in M5 (issues #37 and #38).

coldrun-0.1.0/pyproject.toml

@@ -0,0 +1,151 @@
+[build-system]
+requires = ["hatchling>=1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "coldrun"
+version = "0.1.0"
+description = "Fetch, vet and sandbox any downloaded script in one command"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "KARAN RJ" }]
+requires-python = ">=3.10"
+keywords = ["sandbox", "bubblewrap", "security", "scripts", "cli"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Information Technology",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: System :: Systems Administration",
+  "Typing :: Typed",
+]
+dependencies = [
+  "typer>=0.12",
+  "rich>=13.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/rj-karan/coldrun"
+Repository = "https://github.com/rj-karan/coldrun"
+Issues = "https://github.com/rj-karan/coldrun/issues"
+Changelog = "https://github.com/rj-karan/coldrun/blob/main/CHANGELOG.md"
+
+[project.scripts]
+coldrun = "coldrun.cli:app"
+
+# Third-party runners register here; see docs/writing-a-runner.md (M5).
+[project.entry-points."coldrun.runners"]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3",
+  "pytest-cov>=6.0",
+  "ruff>=0.8",
+  "mypy>=1.13",
+  "pre-commit>=4.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/coldrun"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/coldrun", "tests", "rules", "LICENSE", "README.md", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "sandbox: needs bubblewrap or podman; proves the sandbox holds",
+  "e2e: full coldrun run on a fixture; installs dependencies",
+]
+addopts = "-ra --strict-markers"
+
+[tool.coverage.run]
+source = ["coldrun"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 85
+show_missing = true
+exclude_also = ["if TYPE_CHECKING:", "\\.\\.\\.$"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+extend-exclude = ["docs", "tests/fixtures"]
+
+[tool.ruff.lint]
+select = [
+  "E", "W",    # pycodestyle
+  "F",         # pyflakes
+  "I",         # isort
+  "UP",        # pyupgrade
+  "B",         # bugbear
+  "S",         # bandit: flags shell=True, eval, tempfile misuse
+  "N",         # naming
+  "D",         # docstrings on public objects
+  "ANN",       # type annotations everywhere
+  "C4",        # comprehensions
+  "SIM",       # simplify
+  "PTH",       # pathlib over os.path
+  "RUF",       # ruff-specific
+  "T20",       # no stray print
+  "ISC",       # implicit string concatenation
+  "PIE",
+  "RET",
+  "ARG",       # unused arguments
+  "TC",        # type-checking imports
+  "PGH",       # blanket noqa / type: ignore
+  "PERF",
+  "FURB",
+  "LOG", "G",  # logging
+  "ERA",       # commented-out code
+  "PL",        # pylint subset
+]
+ignore = [
+  "D105",    # magic methods need no docstring
+  "D107",    # __init__ documented on the class
+  "D203",    # conflicts with D211
+  "D213",    # conflicts with D212
+  "PLR0913", # argument counts are reviewed, not counted
+  "ISC001",  # conflicts with the formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+  "S101",   # assert is the test idiom
+  "D",      # test names are the documentation
+  "ANN",    # fixtures and test functions stay light
+  "PLR2004",# magic values in assertions are fine
+  "ARG",    # fixtures are injected by name
+  "TC",     # type-checking blocks add noise in tests
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["coldrun"]
+required-imports = ["from __future__ import annotations"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src", "tests"]
+exclude = ["^tests/fixtures/"]
+strict = true
+warn_unreachable = true
+warn_unused_ignores = true
+enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
+pretty = true
+show_error_codes = true

coldrun-0.1.0/rules/README.md

@@ -0,0 +1 @@
+# Semgrep and YARA rules land here in M3 (issue #22).

coldrun-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)