saferun-cli 0.0.2__py3-none-any.whl

saferun/sandbox/signature.py

@@ -0,0 +1,117 @@
+"""Cosign signature check for the published analyzer image (Phase 5E). Fails closed: every problem raises `SignatureError`.
+
+What is verified: that `<repository>@<digest>` carries a Sigstore "keyless" signature whose certificate was issued to the expected
+GitHub Actions identity (`AnalyzerRelease.signer_identity_regexp`, issuer `oidc_issuer`) and that the signed payload names exactly
+that repository and digest. The check is made by the `cosign` command line tool (`saferun init` fetches a pinned, hash-verified copy itself, see cosign_tool.py; a cosign 2.2+ on PATH is used if that copy is absent), which also checks the transparency log (Rekor).
+
+How it is run: argv list (no shell), absolute path of the executable, minimal environment (no tokens or credentials), a private
+HOME (so nothing is read from or written to the user's home), a hard timeout and an output cap. This runs on the HOST: cosign parses
+signature data from the registry, which is why the image itself is only pulled AFTER this check succeeds and why the digest, tags and
+labels are verified again afterwards. Needs internet (registry, Sigstore TUF root, Rekor); there is no offline or "skip" mode.
+
+What it does not prove: that the signed workflow itself is free of bugs, that the repository or its GitHub account was not compromised,
+or anything about cosign's own correctness. See docs/release-images.md.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .. import hostos
+from . import cosign_tool
+from . import docker as dk
+from .config import SandboxError
+from .images import DIGEST_RE, AnalyzerRelease
+
+COSIGN_TIMEOUT_S = 120
+MAX_OUTPUT = 1024 * 1024
+INSTALL_HINT = "run `saferun init --only analyzer` (it fetches a verified cosign) or install cosign 2.2+ (https://docs.sigstore.dev/cosign/system_config/installation/)"
+_ENV_KEEP = ("PATH", "LANG", "LC_ALL", "TZ", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy",
+             "SSL_CERT_FILE", "SSL_CERT_DIR")
+
+
+class SignatureError(SandboxError):
+    """The release signature is missing, wrong, or could not be checked. The image must not be pulled or trusted."""
+
+
+class CosignMissing(SignatureError):
+    """The `cosign` executable is not installed, so nothing could be verified."""
+
+
+def find_cosign() -> str | None:
+    """The cosign to use: SafeRun's own pinned, hash-verified copy (cosign_tool.py) if it is installed, else a cosign on PATH."""
+    managed = cosign_tool.managed_cosign()
+    if managed:
+        return managed
+    path = shutil.which("cosign")
+    return os.path.abspath(path) if path else None
+
+
+def build_command(cosign: str, rel: AnalyzerRelease) -> list[str]:
+    """argv for `cosign verify`. Refuses anything that is not a plain image reference and a sha256 digest."""
+    if not DIGEST_RE.match(rel.digest or ""):
+        raise SignatureError(f"release digest is not a sha256 digest: {rel.digest!r}")
+    if not rel.signer_identity_regexp or not rel.oidc_issuer:
+        raise SignatureError("the release names no signer identity or issuer, so its signature cannot be checked")
+    try:
+        dk.validate_image(rel.reference)
+    except SandboxError as e:
+        raise SignatureError(str(e)) from None
+    return [cosign, "verify",
+            "--certificate-identity-regexp", rel.signer_identity_regexp,
+            "--certificate-oidc-issuer", rel.oidc_issuer,
+            "--output", "json", rel.reference]
+
+
+def parse_output(stdout: str, rel: AnalyzerRelease) -> int:
+    """Number of signature payloads in cosign's JSON that name exactly `rel`'s repository and digest; raises if there is none.
+    cosign has already verified the signatures; this makes sure what it reports is about the image we asked for."""
+    try:
+        data = json.loads(stdout)
+    except (ValueError, RecursionError):
+        raise SignatureError("cosign printed no valid JSON; the signature was NOT confirmed") from None
+    if not isinstance(data, list):
+        raise SignatureError("cosign output has an unexpected shape; the signature was NOT confirmed")
+    good = 0
+    for item in data:
+        try:
+            crit = item["critical"]
+            digest = crit["image"]["docker-manifest-digest"]
+            ref = crit["identity"]["docker-reference"]
+        except (KeyError, TypeError):
+            continue
+        if digest == rel.digest and ref == rel.repository:
+            good += 1
+    if not good:
+        raise SignatureError("cosign reported no signature for exactly this repository and digest; it was NOT confirmed")
+    return good
+
+
+def verify_release_signature(rel: AnalyzerRelease, *, which=find_cosign, run=subprocess.run, timeout_s: float = COSIGN_TIMEOUT_S) -> int:
+    """Raise SignatureError / CosignMissing unless `rel` is validly signed by the expected identity. Returns the number of signatures."""
+    cosign = which()
+    if not cosign:
+        raise CosignMissing(f"cosign is not installed, so the signature of {rel.reference} cannot be checked: {INSTALL_HINT}")
+    argv = build_command(cosign, rel)
+    env = {k: os.environ[k] for k in _ENV_KEEP if k in os.environ and "\0" not in os.environ[k]}
+    with tempfile.TemporaryDirectory(prefix="saferun-cosign-") as home:
+        env.update(HOME=home, TMPDIR=home, XDG_CACHE_HOME=str(Path(home) / "cache"), XDG_CONFIG_HOME=str(Path(home) / "config"))
+        env.update({k: os.environ[k] for k in hostos.base_env_names() if k in os.environ})   # Windows: SYSTEMROOT etc. (needed to run at all)
+        env.update(hostos.private_home_env(home))
+        try:
+            r = run(argv, capture_output=True, text=True, errors="replace", timeout=timeout_s, stdin=subprocess.DEVNULL,
+                    env=env, cwd=home)
+        except subprocess.TimeoutExpired:
+            raise SignatureError(f"cosign did not finish within {int(timeout_s)} s; the signature was NOT confirmed") from None
+        except OSError as e:
+            raise SignatureError(f"cosign could not be started: {e}") from None
+    if r.returncode != 0:
+        tail = " ".join((r.stderr or "").split())[-300:]
+        raise SignatureError(f"cosign could not verify the signature of {rel.reference} (exit {r.returncode}): {tail or 'no message'}")
+    if len(r.stdout or "") > MAX_OUTPUT:
+        raise SignatureError("cosign printed an unexpectedly large output; the signature was NOT confirmed")
+    return parse_output(r.stdout or "", rel)

saferun/sandbox/verify.py

@@ -0,0 +1,75 @@
+"""`saferun verify-images`: check that the local Docker images carry the pinned digests (Phase 5A).
+
+Read-only: it inspects local images through the Docker CLI. It never pulls, never creates containers, and
+never changes images. A missing image or a digest mismatch is a failure (fail closed), not a warning.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+from . import docker as dk
+from .analyzer import ANALYZER_REPO_TAG, AnalyzerIntegrityError, AnalyzerUnavailable, verify_analyzer_image
+from .config import SandboxError
+from .images import PINNED_IMAGES, PinnedImage, repo_digests
+
+VERIFIED, MISSING, MISMATCH, ERROR = "verified", "missing", "mismatch", "error"
+
+
+@dataclass(frozen=True)
+class ImageCheck:
+    name: str
+    reference: str
+    pinned_digest: str
+    status: str
+    detail: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.status == VERIFIED
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def check_image(img: PinnedImage) -> ImageCheck:
+    base = dict(name=img.name, reference=img.reference, pinned_digest=img.digest)
+    try:
+        r = dk.docker("image", "inspect", "--format", "{{json .RepoDigests}}", dk.validate_image(img.reference))
+    except SandboxError as e:
+        return ImageCheck(**base, status=ERROR, detail=str(e))
+    if r.returncode != 0:
+        if "no such image" in r.stderr.lower():
+            return ImageCheck(**base, status=MISSING,
+                              detail=f"not present locally; fetch it explicitly with: docker pull {img.pull_reference}")
+        return ImageCheck(**base, status=ERROR, detail=f"docker image inspect failed: {r.stderr.strip()[:200]}")
+    try:
+        have = repo_digests(r.stdout.strip())
+    except ValueError as e:
+        return ImageCheck(**base, status=ERROR, detail=f"unexpected docker output: {e}")
+    if img.digest in have:
+        return ImageCheck(**base, status=VERIFIED)
+    return ImageCheck(**base, status=MISMATCH,
+                      detail=f"local image has {', '.join(have) if have else 'no registry digest'}, pinned is {img.digest}")
+
+
+def check_analyzer() -> ImageCheck:
+    """The locally built analyzer image against its build lock and pinned tool/rules labels."""
+    base = dict(name="analyzer", reference=ANALYZER_REPO_TAG, pinned_digest="")
+    try:
+        image_id = verify_analyzer_image()
+    except AnalyzerUnavailable as e:
+        return ImageCheck(**base, status=MISSING, detail=str(e))
+    except AnalyzerIntegrityError as e:
+        return ImageCheck(**base, status=MISMATCH, detail=str(e))
+    except SandboxError as e:
+        return ImageCheck(**base, status=ERROR, detail=str(e))
+    return ImageCheck(**{**base, "pinned_digest": image_id}, status=VERIFIED)
+
+
+def verify_images(images: tuple[PinnedImage, ...] = PINNED_IMAGES, *, analyzer: bool = True) -> list[ImageCheck]:
+    """Raises SandboxError when Docker itself is unusable (remote endpoint, daemon down)."""
+    dk.check_local_daemon()
+    checks = [check_image(i) for i in images]
+    if analyzer:
+        checks.append(check_analyzer())
+    return checks

saferun/sandbox/workspace.py

@@ -0,0 +1,92 @@
+"""Temporary, sanitized copy of an untrusted project directory."""
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .. import hostos
+from .config import SandboxError, SensitivePolicy, SkippedEntry, WithheldEntry, WorkspaceLimits
+from .secrets import Redactor
+
+if hostos.IS_WINDOWS:
+    from .copy_windows import copy_tree
+else:
+    import fcntl
+
+    from .copy import copy_tree
+
+WS_PREFIX = "saferun-ws-"
+LOCK_NAME = ".lock"  # flock held for the life of a run; the kernel drops it if we die
+
+
+@dataclass
+class Workspace:
+    root: Path
+    project: Path  # the only thing ever mounted into a container
+    skipped: list[SkippedEntry] = field(default_factory=list)
+    withheld: list[WithheldEntry] = field(default_factory=list)
+    redactor: Redactor = field(default_factory=Redactor, repr=False)  # holds secret values: never log
+    entries_scanned: int = 0
+    copied_files: int = 0
+    copied_dirs: int = 0
+    copied_bytes: int = 0
+    _lock_fd: int | None = None
+
+    def cleanup(self) -> None:
+        """Delete the workspace and release the lock. Raises if it is still there."""
+        try:
+            if hostos.IS_WINDOWS and self._lock_fd is not None:   # an open exclusive lock file cannot be deleted on Windows
+                os.close(self._lock_fd)
+                self._lock_fd = None
+            shutil.rmtree(hostos.long_path(self.root) if hostos.IS_WINDOWS else self.root, ignore_errors=False,
+                          **({"onexc": hostos.rmtree_onexc} if hostos.IS_WINDOWS else {}))
+        except FileNotFoundError:
+            pass
+        except OSError as e:
+            raise SandboxError(f"could not delete workspace {self.root}: {e}") from e
+        finally:
+            if self._lock_fd is not None:
+                os.close(self._lock_fd)
+                self._lock_fd = None
+        if self.root.exists():
+            raise SandboxError(f"workspace {self.root} still exists after cleanup")
+
+
+def create_workspace(src: Path, limits: WorkspaceLimits | None = None,
+                     policy: SensitivePolicy | None = None) -> Workspace:
+    """Copy `src` into a fresh temp dir. Symlinks, special files and external hard links are skipped, and
+    sensitive files withheld; both are recorded."""
+    try:
+        src = Path(src).resolve()
+        is_dir = src.is_dir()
+    except (TypeError, ValueError, OSError, RuntimeError) as e:  # NUL byte, symlink loop, bad type...
+        raise SandboxError(f"invalid project path {src!r}: {e}") from e
+    if not is_dir:
+        raise SandboxError(f"not a directory: {src}")
+    root = Path(tempfile.mkdtemp(prefix=WS_PREFIX))
+    ws = Workspace(root=root, project=root / "project")
+    try:
+        if hostos.IS_WINDOWS:   # POSIX: the directory is 0700 from mkdtemp; Windows: protected ACL for this user (and SYSTEM) only
+            hostos.restrict_to_owner(root)
+        if hostos.IS_WINDOWS:   # held with share mode 0: the Windows counterpart of the flock below (released by the OS if we die)
+            ws._lock_fd = hostos.create_workspace_lock(root / LOCK_NAME)
+        else:
+            ws._lock_fd = os.open(root / LOCK_NAME, os.O_RDWR | os.O_CREAT | os.O_EXCL | os.O_CLOEXEC, 0o600)
+            fcntl.flock(ws._lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        ws.project.mkdir(mode=0o755)
+        r = copy_tree(str(src), str(ws.project), limits or WorkspaceLimits(), policy)
+        ws.skipped, ws.withheld, ws.redactor = r.skipped, r.withheld, r.redactor
+        ws.entries_scanned, ws.copied_files, ws.copied_dirs, ws.copied_bytes = (
+            r.entries_scanned, r.copied_files, r.copied_dirs, r.copied_bytes)
+        ws.project.chmod(0o755)
+        root.chmod(0o711)  # traversable by the container user, not listable
+    except BaseException:
+        try:
+            ws.cleanup()
+        except SandboxError:
+            pass  # keep the original exception; the reaper will collect the leftovers
+        raise
+    return ws