cordon-scanner 0.1.0__py3-none-any.whl

cordon_sandbox/__init__.py

@@ -0,0 +1,29 @@
+"""The runtime-analysis component. Separate from the scanner on purpose.
+
+Cordon's core promise is that it never executes the code it scans, and that
+promise is a security property rather than a limitation: running attacker code
+is the thing the tool exists to protect people from. This component does the
+opposite, deliberately, under isolation, and only when someone asks.
+
+So it is kept apart in every way that matters. It is not imported by the
+scanner, not reachable from `cordon-scanner scan`, and not run by any default.
+It has its own entry point, and that entry point refuses to do anything without
+an explicit flag whose only purpose is to be hard to pass by accident.
+
+**What it exists to see.** The static tiers resolve constant-derived
+obfuscation and turn runtime-computed dispatch into a signal of its own. What
+neither can decide is behaviour that only exists while the code runs -- a target
+decoded from a network response, logic gated on a fetched value. That residual
+is not a gap in the implementation, it is Rice's theorem, and the only tool that
+observes it is one that runs the code.
+
+**What it refuses to do.** If isolation cannot be established, it does not run
+the code. Not with a warning, not with reduced isolation, not on the host: it
+exits and says why. A sandbox that degrades to running untrusted code directly
+when its backend is missing is worse than no sandbox, because the person who
+asked for it believes they are protected.
+"""
+
+from cordon_sandbox.isolation import Backend, IsolationError, available_backend
+
+__all__ = ["Backend", "IsolationError", "available_backend"]

cordon_sandbox/cli.py

@@ -0,0 +1,151 @@
+"""The entry point, and the flag that has to be typed.
+
+`cordon-sandbox` runs untrusted code. That is its purpose and it is also the
+single most dangerous thing in this repository, so the interface is built to
+make the decision explicit and hard to make by accident:
+
+* Nothing runs without `--sandbox`. The flag carries no information the command
+  does not already imply -- naming the subcommand and the package would be
+  enough for an argument parser. It exists to be typed deliberately, and to make
+  a copied command line obviously the thing it is.
+* Nothing runs without isolation. A missing container runtime is an error with
+  no override, because the alternative is somebody believing they are protected
+  while a package installs on their laptop.
+* Nothing here is reachable from `cordon-scanner`. The scanner's promise is that
+  it never executes what it scans, and a promise with an entry point into
+  execution is not one.
+
+Exit codes match the scanner's, so a pipeline can treat the two the same way:
+0 nothing observed, 1 something was, 2 the component failed, 3 bad invocation.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from cordon_sandbox.fetch import fetch
+from cordon_sandbox.isolation import IsolationError, available_backend
+from cordon_sandbox.observe import Run, observe
+
+CLEAN = 0
+OBSERVED = 1
+FAILED = 2
+BAD_INVOCATION = 3
+
+REFUSAL = (
+    "cordon-sandbox installs and runs the package you name. Pass --sandbox to "
+    "say you meant that. It is not a switch that changes behaviour; it is there "
+    "so that running untrusted code is never something you did by accident."
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cordon-sandbox",
+        description=(
+            "Install a package under isolation and report what it did. "
+            "This EXECUTES the package. The scanner does not; this is the "
+            "separate component that does, and only when asked."
+        ),
+    )
+    parser.add_argument(
+        "ecosystem", choices=("npm", "pypi"), help="which registry the package is from"
+    )
+    parser.add_argument("package", help="package name, optionally with a version specifier")
+    parser.add_argument(
+        "--sandbox",
+        action="store_true",
+        help="required. Confirms you intend to execute this package.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="emit the observation record as JSON instead of prose",
+    )
+    return parser
+
+
+def render(run: Run) -> str:
+    lines = [
+        f"ran: {run.command}",
+        f"image: {run.image}",
+        f"runtime: {run.backend.command} {run.backend.version}",
+        "",
+        "isolation in effect:",
+        *[f"  - {claim}" for claim in run.guarantees],
+        "",
+    ]
+
+    if not run.observations:
+        traced = (
+            "This run recorded filesystem effects, exit status, output and the "
+            "install's execve and connect calls. What it does not see is "
+            "behaviour that needs neither: a package that read a file and held "
+            "it, or one that waited out the analysis window."
+            if run.traced
+            else "This run recorded filesystem effects, exit status and output "
+            "and produced no syscall trace, so a package that ran something or "
+            "tried to reach somewhere would look exactly like this."
+        )
+        lines += [
+            "observed: nothing worth reporting.",
+            "",
+            "That is not a clean bill of health. " + traced,
+        ]
+    else:
+        lines.append("observed:")
+        lines += [f"  [{o.kind}] {o.detail}" for o in run.observations]
+
+    if run.output_tail.strip():
+        lines += ["", "last output from the install:", run.output_tail.rstrip()]
+    return "\n".join(lines)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.sandbox:
+        print(REFUSAL, file=sys.stderr)
+        return BAD_INVOCATION
+
+    try:
+        # Isolation is established before anything is downloaded, so a missing
+        # runtime is discovered before the network is touched at all.
+        backend = available_backend()
+        artefact = fetch(args.ecosystem, args.package)
+        run = observe(backend, args.ecosystem, artefact)
+    except IsolationError as exc:
+        print(str(exc), file=sys.stderr)
+        return FAILED
+
+    if args.json:
+        import json
+
+        print(
+            json.dumps(
+                {
+                    "command": run.command,
+                    "image": run.image,
+                    "runtime": f"{run.backend.command} {run.backend.version}",
+                    "isolation": list(run.guarantees),
+                    "exit_status": run.exit_status,
+                    "timed_out": run.timed_out,
+                    "syscalls_traced": run.traced,
+                    "observations": [
+                        {"kind": o.kind, "detail": o.detail} for o in run.observations
+                    ],
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(render(run))
+
+    return OBSERVED if run.observations else CLEAN
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cordon_sandbox/fetch.py

@@ -0,0 +1,156 @@
+"""Getting the artefact before the isolation goes up.
+
+The first working version of this component installed the package inside a
+container with no network, which meant the installer could not reach the
+registry and every package failed at the fetch step. The observation "it failed
+without a network" then fired on everything, which is a signal that means
+nothing.
+
+The fix is the structure a sandbox needs anyway: separate *getting* the code
+from *running* it.
+
+**Fetching does not execute anything.** This reads the registry's JSON metadata
+and downloads the artefact over HTTP. A `.tar.gz` or a `.tgz` arriving as bytes
+runs nothing; the code in it runs later, inside the container, which is the
+point. Doing this with `pip download` instead would be a mistake -- pip executes
+`setup.py egg_info` on a source distribution to resolve it, so the payload would
+run on the host before the sandbox existed.
+
+**The artefact goes in without a mount.** It is copied into the created
+container rather than bind-mounted, so no host path is reachable from inside at
+any point, and the install runs with `--no-index` against the local file.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+
+from cordon_sandbox.isolation import IsolationError
+
+TIMEOUT_SECONDS = 30.0
+MAX_ARTEFACT_BYTES = 256 << 20
+"""Ceiling on what will be downloaded. A package larger than this is not
+something to analyse by accident."""
+
+USER_AGENT = "cordon-sandbox (+https://github.com/Threx-code/cordon)"
+
+
+@dataclass(frozen=True, slots=True)
+class Artefact:
+    """A downloaded package, held in memory until it is copied in."""
+
+    filename: str
+    data: bytes
+    source_url: str
+
+
+def _get(url: str, *, accept: str) -> bytes:
+    parsed = urllib.parse.urlsplit(url)
+    if parsed.scheme != "https":
+        raise IsolationError(f"refusing a non-HTTPS artefact URL: {url}")
+
+    request = urllib.request.Request(  # noqa: S310  (scheme checked above)
+        url, headers={"User-Agent": USER_AGENT, "Accept": accept}, method="GET"
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:  # noqa: S310
+            body = response.read(MAX_ARTEFACT_BYTES + 1)
+    except (urllib.error.URLError, urllib.error.HTTPError, OSError) as exc:
+        raise IsolationError(f"could not fetch {url}: {type(exc).__name__}") from exc
+
+    if len(body) > MAX_ARTEFACT_BYTES:
+        raise IsolationError(f"{url} exceeded {MAX_ARTEFACT_BYTES} bytes and was not downloaded")
+    return bytes(body)
+
+
+def _mapping(value: object) -> dict[str, object]:
+    """A mapping, or an empty one. Registry documents are written by whoever
+    published the package, so a field documented as an object arrives as
+    whatever they put there."""
+    return value if isinstance(value, dict) else {}
+
+
+def fetch(ecosystem: str, package: str) -> Artefact:
+    """Download the artefact for a package, without running any of it."""
+    if ecosystem == "pypi":
+        return _pypi(package)
+    if ecosystem == "npm":
+        return _npm(package)
+    raise IsolationError(f"no fetcher is defined for {ecosystem!r}")
+
+
+def _split(package: str, separator: str) -> tuple[str, str | None]:
+    name, found, version = package.rpartition(separator)
+    if not found:
+        return package, None
+    return name, version or None
+
+
+def _pypi(package: str) -> Artefact:
+    name, version = _split(package, "==")
+    document = json.loads(
+        _get(
+            f"https://pypi.org/pypi/{urllib.parse.quote(name, safe='')}/json",
+            accept="application/json",
+        )
+    )
+    releases = _mapping(document.get("releases"))
+    info = _mapping(document.get("info"))
+    declared = info.get("version")
+    version = version or (declared if isinstance(declared, str) else None)
+
+    entries = releases.get(version) if version else None
+    if not isinstance(entries, list) or not entries:
+        raise IsolationError(f"pypi has no downloadable files for {name} {version}")
+
+    # A source distribution is preferred over a wheel, because `setup.py` is
+    # where install-time code lives and a wheel usually has none. Analysing the
+    # wheel of a package whose payload is in its sdist would observe nothing and
+    # report it as nothing found.
+    ordered = sorted(entries, key=lambda e: e.get("packagetype") != "sdist")
+    chosen = ordered[0]
+    url = chosen.get("url")
+    if not isinstance(url, str):
+        raise IsolationError(f"pypi returned no URL for {name} {version}")
+
+    return Artefact(
+        filename=str(chosen.get("filename") or "package.tar.gz"),
+        data=_get(url, accept="application/octet-stream"),
+        source_url=url,
+    )
+
+
+def _npm(package: str) -> Artefact:
+    name, version = _split(package, "@") if not package.startswith("@") else (package, None)
+    if package.startswith("@") and package.count("@") > 1:
+        name, _, version = package.rpartition("@")
+
+    document = json.loads(
+        _get(
+            f"https://registry.npmjs.org/{urllib.parse.quote(name, safe='@/')}",
+            accept="application/json",
+        )
+    )
+    dist_tags = _mapping(document.get("dist-tags"))
+    versions = _mapping(document.get("versions"))
+    latest = dist_tags.get("latest")
+    version = version or (latest if isinstance(latest, str) else None)
+
+    entry = _mapping(versions.get(version)) if version else {}
+    dist = _mapping(entry.get("dist"))
+    url = dist.get("tarball")
+    if not isinstance(url, str):
+        raise IsolationError(f"npm has no tarball for {name} {version}")
+
+    return Artefact(
+        filename=f"{name.replace('/', '-').lstrip('@')}-{version}.tgz",
+        data=_get(url, accept="application/octet-stream"),
+        source_url=url,
+    )
+
+
+__all__ = ["MAX_ARTEFACT_BYTES", "TIMEOUT_SECONDS", "Artefact", "fetch"]

cordon_sandbox/isolation.py

@@ -0,0 +1,228 @@
+"""Establishing isolation, or refusing to proceed.
+
+This module answers one question: is there somewhere safe to run this? Every
+other part of the component depends on the answer being honest, so the failure
+mode is chosen carefully -- it raises rather than returning a degraded option.
+
+**Why refusal is the feature.** The person running this has decided to execute a
+package they do not trust. If the isolation they think they have is not there,
+running it anyway harms them more than not running it at all, because they will
+read the result as "it did nothing" rather than "it ran on my laptop". So a
+missing backend is an error, not a warning, and there is no flag to override it.
+
+**What counts as isolation here.** A container runtime with the network removed,
+no host filesystem mounted, dropped capabilities, no-new-privileges, a process
+ceiling and a memory ceiling. That is weaker than a microVM and it is stated as
+such: a container boundary is a kernel boundary, and a kernel exploit crosses
+it. It is what is available on an ordinary developer machine and a CI runner
+without privileged setup, and the alternative -- offering nothing until a
+hypervisor is present -- would mean the residual never gets looked at.
+
+**Except where a stronger boundary is already installed.** gVisor's `runsc`
+intercepts the guest's syscalls in userspace and serves them from its own
+kernel, so the host kernel sees a small, fixed surface rather than the whole
+syscall table. Where it is configured in the runtime this uses it, because the
+cost is one flag and the difference is the class of bug that gets you out. It
+is not required -- demanding it would put this back to running on nothing --
+and which boundary was actually used is recorded with the result, since a
+reader deciding what an observation is worth needs to know which one it was.
+
+**The container filesystem is writable, and that is deliberate.** The first
+version made the root read-only, which reads as stronger and was in fact
+useless: a payload that writes to `/etc/cron.d` simply failed, and the run
+reported "the install failed" rather than "it tried to persist". A sandbox that
+prevents the behaviour it exists to observe has been configured into
+uselessness. Nothing on the host is reachable either way -- that is what the
+absent mounts do -- and the container is destroyed when the run ends.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+RUNTIMES = ("podman", "docker")
+"""Runtimes tried in order.
+
+Podman first because it runs rootless by default, so a container escape lands as
+an unprivileged user rather than as root. Where both are present that is the
+better default, and where only Docker is present it is still isolation."""
+
+PROBE_TIMEOUT = 10.0
+"""How long to wait for a runtime to say it is working.
+
+A runtime that is installed but whose daemon is not running would otherwise hang
+the check, and a hang here is indistinguishable to the user from a sandbox that
+is thinking."""
+
+
+class IsolationError(RuntimeError):
+    """Isolation could not be established, so nothing was run.
+
+    Deliberately not recoverable by the caller into "run it anyway". There is no
+    degraded mode: the whole value of this component is that the code ran
+    somewhere it could not reach anything.
+    """
+
+
+GVISOR_RUNTIME = "runsc"
+"""gVisor's OCI runtime, as `--runtime` names it."""
+
+
+@dataclass(frozen=True, slots=True)
+class Backend:
+    """A runtime that can host the analysis, and what it guarantees."""
+
+    command: str
+    version: str
+    rootless: bool
+
+    runtime: str | None = None
+    """An OCI runtime to ask for by name, when one stronger than the default is
+    configured. `None` means the runtime's own default, which is `runc`."""
+
+    traces_syscalls: bool = False
+    """Whether the run can be traced.
+
+    Recorded on the backend rather than assumed, because tracing needs
+    `CAP_SYS_PTRACE` and a seccomp profile that permits `ptrace`, and a host
+    that refuses either produces a run with no trace. The difference between
+    "nothing called execve" and "nothing was watching" is the difference this
+    whole project is built around, so it is carried rather than inferred."""
+
+    @property
+    def guarantees(self) -> tuple[str, ...]:
+        """What this backend does and does not promise, in the report's words.
+
+        Carried with the result rather than described in documentation, because
+        a reader deciding what an observation is worth needs to know what the
+        boundary was -- and the boundary differs between a rootless and a
+        root-owned runtime.
+        """
+        common: tuple[str, ...] = (
+            "no network interface",
+            "no host filesystem mounted",
+            "container filesystem is writable but discarded afterwards",
+            "all Linux capabilities dropped",
+            "no new privileges",
+            "process and memory ceilings",
+        )
+        if self.runtime == GVISOR_RUNTIME:
+            common = (
+                *common,
+                "gVisor: the guest's syscalls are served by a userspace kernel, "
+                "so the host kernel sees a small fixed surface rather than the "
+                "whole syscall table",
+            )
+        else:
+            common = (
+                *common,
+                "the host kernel is the boundary: a kernel exploit crosses it, "
+                "which a virtual machine or gVisor would not allow",
+            )
+
+        common = (
+            *common,
+            "syscalls traced: execve and connect are recorded"
+            if self.traces_syscalls
+            else "syscalls are NOT traced: what the install executed and what "
+            "it tried to reach were not observed",
+        )
+
+        if self.rootless:
+            return (*common, "runtime is rootless: an escape lands unprivileged")
+        return (
+            *common,
+            "runtime is root-owned: an escape lands as root, which is weaker "
+            "than a rootless runtime and much weaker than a virtual machine",
+        )
+
+
+def available_backend() -> Backend:
+    """The first working runtime, or `IsolationError` if there is none."""
+    tried: list[str] = []
+
+    for runtime in RUNTIMES:
+        path = shutil.which(runtime)
+        if path is None:
+            tried.append(f"{runtime}: not installed")
+            continue
+        try:
+            probe = subprocess.run(  # noqa: S603  (fixed argv, resolved path)
+                [path, "version", "--format", "{{.Client.Version}}"],
+                capture_output=True,
+                text=True,
+                timeout=PROBE_TIMEOUT,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            tried.append(f"{runtime}: {type(exc).__name__}")
+            continue
+
+        if probe.returncode != 0:
+            detail = (probe.stderr or probe.stdout or "").strip().splitlines()
+            tried.append(f"{runtime}: not usable ({detail[0] if detail else 'no output'})")
+            continue
+
+        return Backend(
+            command=path,
+            version=(probe.stdout or "").strip() or "unknown",
+            rootless=runtime == "podman",
+            runtime=GVISOR_RUNTIME if _has_gvisor(path) else None,
+        )
+
+    raise IsolationError(
+        "no container runtime is available, so the package was not run. "
+        "Install podman (preferred, rootless) or docker. This does not fall "
+        "back to running the code on this machine: a sandbox that degrades to "
+        "no sandbox is worse than none, because you would read the result as "
+        "'it did nothing'.\n  " + "\n  ".join(tried)
+    )
+
+
+def _has_gvisor(command: str) -> bool:
+    """Whether this runtime has gVisor configured as an OCI runtime.
+
+    Asked of the runtime rather than of `PATH`. `runsc` sitting in a directory
+    the daemon does not know about is not a runtime that can be selected, and
+    passing `--runtime runsc` on that host fails the container creation --
+    which would turn "a stronger boundary is available" into "nothing ran".
+
+    **Every failure is "no".** `docker info` talks to the daemon, so on a
+    machine where Docker is installed and not running it hangs until the
+    timeout and raises -- and this is called from `available_backend`, whose
+    entire job is to answer that situation with a sentence rather than a
+    traceback. It went unhandled: a user with Docker installed and stopped got
+    `subprocess.TimeoutExpired` out of `cordon-sandbox` instead of the refusal
+    that explains what to install. Windows CI, where the daemon is absent, is
+    what surfaced it.
+
+    Refusing to answer is also the safe direction. A runtime that cannot say
+    whether it has gVisor is used with its default runtime, which is what would
+    have happened anyway.
+    """
+    try:
+        probe = subprocess.run(  # noqa: S603  (fixed argv, resolved path)
+            [command, "info", "--format", "{{.Runtimes}}"],
+            capture_output=True,
+            text=True,
+            timeout=PROBE_TIMEOUT,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+    if probe.returncode != 0:
+        return False
+    return GVISOR_RUNTIME in (probe.stdout or "")
+
+
+__all__ = [
+    "GVISOR_RUNTIME",
+    "PROBE_TIMEOUT",
+    "RUNTIMES",
+    "Backend",
+    "IsolationError",
+    "available_backend",
+]