saferun-cli 0.0.2__py3-none-any.whl

saferun/engine/paths.py

@@ -0,0 +1,41 @@
+"""Path normalisation for untrusted tool output."""
+from __future__ import annotations
+
+import ntpath
+import posixpath
+from pathlib import Path, PureWindowsPath
+
+from .. import hostos
+from .model import clean_text
+
+
+CONTAINER_ROOT = "/workspace"   # where the analyzer container sees the project; tools running there report paths under it
+
+
+def rel_path(value, root: Path) -> str | None:
+    """A tool-reported path as a clean, relative, posix path inside `root` (or the container's /workspace); None if it is not one."""
+    if not isinstance(value, str) or not value or "\0" in value:
+        return None
+    p = value
+    if hostos.IS_WINDOWS and ntpath.splitdrive(p)[0]:
+        # A drive-letter path can only be a host path (the analyzer container reports /workspace/...). Strip the project root, compare
+        # case-insensitively like NTFS, and refuse every other drive path.
+        for r in (root.resolve(), root):
+            try:
+                p = PureWindowsPath(p).relative_to(PureWindowsPath(r)).as_posix()
+                break
+            except ValueError:
+                continue
+        else:
+            return None
+    elif posixpath.isabs(p):
+        for r in (str(root.resolve()) + "/", str(root) + "/", CONTAINER_ROOT + "/"):
+            if p.startswith(r):
+                p = p[len(r):]
+                break
+        else:
+            return None
+    p = posixpath.normpath(p)
+    if p in (".", "") or p == ".." or p.startswith("../") or posixpath.isabs(p):
+        return None
+    return clean_text(p, 300)

saferun/engine/pysyntax.py

@@ -0,0 +1,135 @@
+"""Python syntax validation INSIDE the sandbox (python:3.12-slim): `compile()` of every .py/.pyi file.
+
+Semgrep recovers from syntax errors without reporting them (observed with Semgrep 1.182: a file with `def f(:` is
+"scanned" with no error), so a separate check is needed or a broken file would look clean. One sandbox run executes
+a fixed driver that only *compiles* each file (never imports or runs it) and prints one JSON line per file.
+Syntax is that of the sandbox image's Python (3.12), not necessarily the project's target version.
+"""
+from __future__ import annotations
+
+import json
+import time
+
+from ..sandbox import SandboxError, SandboxLimits
+from ..sandbox.profiles import PYTHON
+from .context import CheckContext
+from .model import CheckResult, CheckStatus, Finding, Severity, clean_text
+from .semgrep import python_files
+
+NAME = "python-syntax"
+MAX_FILES = 1000
+
+DRIVER = """
+import json, os
+ROOT, MAX = '/workspace', %d
+SKIP = {'node_modules', '.git', '.venv', 'venv', 'site-packages'}
+files, truncated = [], False
+for d, dirs, names in os.walk(ROOT):
+    dirs[:] = sorted(x for x in dirs if x not in SKIP)
+    for n in sorted(names):
+        if n.endswith(('.py', '.pyi')):
+            if len(files) >= MAX:
+                truncated = True
+            else:
+                files.append(os.path.join(d, n))
+def out(o):
+    print(json.dumps(o), flush=True)
+for f in files:
+    rel = os.path.relpath(f, ROOT)
+    try:
+        with open(f, 'rb') as fh:
+            src = fh.read()
+        compile(src, rel, 'exec', dont_inherit=True)
+        out({'file': rel, 'ok': True})
+    except SyntaxError as e:
+        out({'file': rel, 'ok': False, 'line': e.lineno, 'msg': str(e.msg)[:300]})
+    except (ValueError, RecursionError, MemoryError, OSError) as e:
+        out({'file': rel, 'failed': type(e).__name__})
+out({'done': True, 'count': len(files), 'truncated': truncated})
+""" % MAX_FILES
+
+
+def build_command() -> list[str]:
+    return ["python", "-I", "-c", DRIVER]
+
+
+def parse_output(text: str, expected: list[str]) -> tuple[list[Finding], list[str], int]:
+    """(findings, per-file problems, files checked). ValueError on malformed/incomplete output."""
+    findings, problems, count, done, known = [], [], 0, None, set(expected)
+    for raw in text.splitlines():
+        if not raw.strip():
+            continue
+        try:
+            o = json.loads(raw)
+        except (json.JSONDecodeError, RecursionError):
+            raise ValueError("driver output is not valid JSON lines") from None
+        if not isinstance(o, dict):
+            raise ValueError("driver output line is not an object")
+        if o.get("done") is True:
+            done = o
+        elif isinstance(o.get("file"), str):
+            f = o["file"]
+            if f not in known:
+                raise ValueError("driver reported a file that was not in the project")
+            count += 1
+            if "failed" in o:
+                problems.append(f"{clean_text(f, 200)}: could not be compiled ({clean_text(o['failed'], 40)})")
+            elif o.get("ok") is False:
+                line = o.get("line")
+                findings.append(Finding(
+                    check=NAME, rule_id="python.syntax-error", severity=Severity.MEDIUM, category="syntax",
+                    message=clean_text(f"SyntaxError: {o.get('msg', '')}", 300), path=clean_text(f, 300),
+                    line=line if isinstance(line, int) and not isinstance(line, bool) and line > 0 else None))
+            elif o.get("ok") is not True:
+                raise ValueError("unrecognised driver output line")
+        else:
+            raise ValueError("unrecognised driver output line")
+    if done is None:
+        raise ValueError("driver output ended before its completion marker")
+    if done.get("count") != count:
+        raise ValueError("driver file count does not match its output")
+    if done.get("truncated"):
+        problems.append(f"more than {MAX_FILES} Python files; the rest were not checked")
+    return findings, problems, count
+
+
+def run_check(ctx: CheckContext) -> CheckResult:
+    targets = python_files(ctx.files)
+    if not targets:
+        return CheckResult(NAME, CheckStatus.NOT_APPLICABLE, detail="no Python files")
+    try:
+        ctx.image_available(PYTHON.image)
+    except SandboxError as e:
+        return CheckResult(NAME, CheckStatus.UNAVAILABLE, tool=f"compile() ({PYTHON.label})",
+                           detail=clean_text(f"sandbox or image unavailable: {e}"))
+    t0 = time.monotonic()
+    res = CheckResult(NAME, CheckStatus.ERROR, tool=f"compile() ({PYTHON.label}, sandboxed)")
+    try:
+        r = ctx.sandbox(ctx.project, build_command(), SandboxLimits(timeout_s=ctx.timeout_s, max_output_bytes=ctx.max_output),
+                        image=PYTHON.image)
+    except SandboxError as e:
+        res.detail = clean_text(f"sandbox refused or failed to run: {e}")
+        return res
+    finally:
+        res.duration_s = time.monotonic() - t0
+    if r.timed_out:
+        res.status, res.detail = CheckStatus.TIMEOUT, f"syntax check exceeded {ctx.timeout_s:g}s and was killed"
+        return res
+    if r.oom_killed or r.output_truncated or r.exit_code != 0:
+        res.detail = clean_text(f"sandboxed run failed (exit {r.exit_code}, oom={r.oom_killed}, "
+                                f"truncated={r.output_truncated}): {r.stderr.strip()[-200:]}")
+        return res
+    try:
+        findings, problems, count = parse_output(r.stdout, targets)
+    except ValueError as e:
+        res.detail = clean_text(f"driver output unusable: {e}")
+        return res
+    res.findings = findings[: ctx.max_findings]
+    res.truncated_findings = max(0, len(findings) - ctx.max_findings)
+    res.errors = problems
+    res.notes = [f"{count} Python file(s) compiled (not executed) with the sandbox image's Python 3.12"]
+    if problems:
+        res.status, res.detail = CheckStatus.INCOMPLETE, f"{len(problems)} problem(s): " + "; ".join(problems)[:300]
+    else:
+        res.status = CheckStatus.FINDINGS if findings else CheckStatus.PASSED
+    return res

saferun/engine/rules/python.yml

@@ -0,0 +1,103 @@
+# SafeRun's own, small, local Python rule set. Passed to Semgrep with --config <this file>; no registry,
+# no network. It is a starting point, NOT a complete security ruleset: absence of findings proves nothing.
+# metadata.saferun_severity (critical|high|medium|low) is what SafeRun uses; `severity` is Semgrep's own.
+rules:
+  - id: saferun.python.dynamic-code-execution
+    languages: [python]
+    severity: ERROR
+    message: eval()/exec() runs dynamically built code; never pass untrusted data to it.
+    pattern-either:
+      - pattern: eval(...)
+      - pattern: exec(...)
+    metadata: {saferun_severity: high, cwe: ["CWE-95"]}
+
+  - id: saferun.python.subprocess-shell-true
+    languages: [python]
+    severity: ERROR
+    message: subprocess call with shell=True is vulnerable to command injection; pass an argument list instead.
+    pattern-either:
+      - pattern: subprocess.$FUNC(..., shell=True, ...)
+    metadata: {saferun_severity: high, cwe: ["CWE-78"]}
+
+  - id: saferun.python.os-command-execution
+    languages: [python]
+    severity: ERROR
+    message: os.system()/os.popen() run a shell command line; use subprocess with an argument list.
+    pattern-either:
+      - pattern: os.system(...)
+      - pattern: os.popen(...)
+    metadata: {saferun_severity: high, cwe: ["CWE-78"]}
+
+  - id: saferun.python.unsafe-deserialization
+    languages: [python]
+    severity: ERROR
+    message: pickle/marshal/shelve deserialization can execute arbitrary code; never load untrusted data with it.
+    pattern-either:
+      - pattern: pickle.load(...)
+      - pattern: pickle.loads(...)
+      - pattern: marshal.loads(...)
+      - pattern: shelve.open(...)
+    metadata: {saferun_severity: high, cwe: ["CWE-502"]}
+
+  - id: saferun.python.yaml-unsafe-load
+    languages: [python]
+    severity: ERROR
+    message: yaml.load()/unsafe_load() can construct arbitrary objects; use yaml.safe_load().
+    patterns:
+      - pattern-either:
+          - pattern: yaml.load(...)
+          - pattern: yaml.unsafe_load(...)
+      - pattern-not: yaml.load(..., Loader=yaml.SafeLoader, ...)
+      - pattern-not: yaml.load(..., Loader=SafeLoader, ...)
+    metadata: {saferun_severity: high, cwe: ["CWE-502"]}
+
+  - id: saferun.python.tls-verification-disabled
+    languages: [python]
+    severity: ERROR
+    message: TLS certificate verification is disabled (verify=False).
+    pattern-either:
+      - pattern: requests.$FUNC(..., verify=False, ...)
+      - pattern: httpx.$FUNC(..., verify=False, ...)
+    metadata: {saferun_severity: high, cwe: ["CWE-295"]}
+
+  - id: saferun.python.weak-hash
+    languages: [python]
+    severity: WARNING
+    message: MD5/SHA-1 are broken for security purposes.
+    pattern-either:
+      - pattern: hashlib.md5(...)
+      - pattern: hashlib.sha1(...)
+    metadata: {saferun_severity: medium, cwe: ["CWE-327"]}
+
+  - id: saferun.python.insecure-tempfile
+    languages: [python]
+    severity: WARNING
+    message: tempfile.mktemp() is racy; use tempfile.mkstemp() or NamedTemporaryFile().
+    pattern: tempfile.mktemp(...)
+    metadata: {saferun_severity: medium, cwe: ["CWE-377"]}
+
+  - id: saferun.python.flask-debug
+    languages: [python]
+    severity: WARNING
+    message: Flask debug mode exposes an interactive debugger; do not enable it outside local development.
+    pattern: $APP.run(..., debug=True, ...)
+    metadata: {saferun_severity: medium, cwe: ["CWE-489"]}
+
+  - id: saferun.python.hardcoded-secret
+    languages: [python]
+    severity: WARNING
+    message: A credential-like variable is assigned a string literal; keep secrets out of source.
+    patterns:
+      - pattern: $NAME = "..."
+      - metavariable-regex:
+          metavariable: $NAME
+          regex: (?i)^(.*_)?(password|passwd|secret|api_?key|token|private_key)$
+      - pattern-not: $NAME = ""
+    metadata: {saferun_severity: medium, cwe: ["CWE-798"]}
+
+  - id: saferun.python.assert-for-validation
+    languages: [python]
+    severity: INFO
+    message: assert statements are removed under python -O; do not rely on them for security checks.
+    pattern: assert $X
+    metadata: {saferun_severity: low, cwe: ["CWE-617"]}

saferun/engine/semgrep.py

@@ -0,0 +1,173 @@
+"""Python static security analysis with Semgrep, run INSIDE the analyzer container (Phase 5B). Never on the host.
+
+Invocation (argv, no shell), run on the sanitized project copy mounted read-only at /workspace:
+    /usr/local/bin/semgrep scan --json --quiet --metrics=off --disable-version-check --no-git-ignore --disable-nosem --no-rewrite-rule-ids
+           --config /opt/saferun/rules/python.yml --timeout 10 --max-target-bytes 1000000
+           --exclude node_modules --exclude .venv --exclude venv --exclude site-packages .
+Only the rule file baked into the verified image is used (no registry, no network, no auto config); project-supplied Semgrep
+configuration is not read. If the analyzer image is missing, locked-but-different, or isolation cannot be set up, the check is
+UNAVAILABLE/ERROR (never clean); there is no host-side fallback. `--disable-nosem` stops `# nosem` comments in untrusted code from hiding findings.
+Exit codes: 0 = scan done (findings do not change it); anything else = operational error.
+
+Coverage is verified, not assumed: Semgrep silently skips files (over --max-target-bytes, or matched by a
+project-supplied .semgrepignore) without reporting an error, so every targeted Python file must appear in the
+`paths.scanned` list of its JSON output; otherwise the check is INCOMPLETE. `.semgrepignore` files are also removed
+from SafeRun's private copy before the scan (Semgrep has no flag to disable them), so an untrusted project cannot
+use one to hide code.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+from .context import CheckContext
+from .model import CheckResult, CheckStatus, Finding, Severity, clean_text
+from .paths import rel_path
+from ..sandbox import SandboxError
+from ..sandbox.analyzer import RULES_PATH, SEMGREP_EXE, AnalyzerIntegrityError
+from .tools import ToolUnavailable
+
+NAME = "python-static-analysis"
+RULES_FILE = Path(__file__).parent / "rules" / "python.yml"
+EXCLUDES = ("node_modules", ".venv", "venv", "site-packages")
+_SEV = {"critical": Severity.CRITICAL, "high": Severity.HIGH, "medium": Severity.MEDIUM, "low": Severity.LOW,
+        "info": Severity.INFO}
+_SEMGREP_SEV = {"ERROR": Severity.HIGH, "WARNING": Severity.MEDIUM, "INFO": Severity.LOW}
+
+
+def python_files(files: list[str]) -> list[str]:
+    return [f for f in files if f.endswith((".py", ".pyi")) and not _vendored(f)]
+
+
+def _vendored(rel: str) -> bool:
+    return any(p in EXCLUDES for p in rel.split("/")[:-1])
+
+
+def build_argv(exe: str = SEMGREP_EXE, rules: str = RULES_PATH) -> list[str]:
+    argv = [exe, "scan", "--json", "--quiet", "--metrics=off", "--disable-version-check", "--no-git-ignore",
+            "--disable-nosem", "--no-rewrite-rule-ids", "--config", rules, "--timeout", "10", "--max-target-bytes", "1000000"]
+    for e in EXCLUDES:
+        argv += ["--exclude", e]
+    return argv + ["."]
+
+
+def _as_int(v) -> int | None:
+    return v if isinstance(v, int) and not isinstance(v, bool) and v >= 0 else None
+
+
+def parse_output(text: str, root: Path) -> tuple[list[Finding], list[str], set[str] | None]:
+    """Return (findings, tool-reported errors, scanned paths or None if not reported).
+    Raises ValueError on anything that is not Semgrep JSON."""
+    try:
+        data = json.loads(text)
+    except (json.JSONDecodeError, RecursionError) as e:
+        raise ValueError(f"output is not valid JSON: {e}") from None
+    if not isinstance(data, dict) or not isinstance(data.get("results"), list):
+        raise ValueError("JSON has no 'results' list")
+    findings: list[Finding] = []
+    for r in data["results"]:
+        if not isinstance(r, dict) or not isinstance(r.get("extra"), dict):
+            raise ValueError("malformed entry in 'results'")
+        extra = r["extra"]
+        meta = extra.get("metadata") if isinstance(extra.get("metadata"), dict) else {}
+        sev = _SEV.get(str(meta.get("saferun_severity", "")).lower()) \
+            or _SEMGREP_SEV.get(str(extra.get("severity", "")).upper(), Severity.UNKNOWN)
+        cwe = meta.get("cwe", [])
+        cwe = [cwe] if isinstance(cwe, str) else cwe if isinstance(cwe, list) else []
+        start, end = r.get("start"), r.get("end")
+        findings.append(Finding(
+            check=NAME, rule_id=clean_text(r.get("check_id", "unknown"), 200), severity=sev,
+            message=clean_text(extra.get("message", "")), category="code",
+            path=rel_path(r.get("path"), root),
+            line=_as_int(start.get("line")) if isinstance(start, dict) else None,
+            end_line=_as_int(end.get("line")) if isinstance(end, dict) else None,
+            cwe=tuple(clean_text(c, 40) for c in cwe if isinstance(c, str)),
+        ))
+    errs = []
+    for e in data.get("errors") or []:
+        if isinstance(e, dict):
+            where = rel_path(e.get("path"), root) or ""
+            errs.append(clean_text(f"{e.get('type', 'error')} {where}: {e.get('message') or e.get('long_msg') or ''}".strip(), 300))
+        else:
+            errs.append(clean_text(e, 300))
+    paths = data.get("paths")
+    raw = paths.get("scanned") if isinstance(paths, dict) else None
+    scanned = {p for p in (rel_path(x, root) for x in raw) if p} if isinstance(raw, list) else None
+    return findings, errs, scanned
+
+
+def remove_ignore_files(ctx: CheckContext) -> int:
+    """Delete .semgrepignore files from the private analysis copy. Returns how many were removed."""
+    n = 0
+    for f in ctx.files:
+        if f.rsplit("/", 1)[-1] == ".semgrepignore":
+            try:
+                os.unlink(ctx.project / f)
+                n += 1
+            except OSError:
+                pass   # the coverage cross-check below still catches anything Semgrep then skips
+    return n
+
+
+def run_check(ctx: CheckContext) -> CheckResult:
+    targets = python_files(ctx.files)
+    if not targets:
+        return CheckResult(NAME, CheckStatus.NOT_APPLICABLE, detail="no Python files")
+    if not RULES_FILE.is_file():
+        return CheckResult(NAME, CheckStatus.ERROR, detail=f"bundled rule file missing: {RULES_FILE.name}", tool="semgrep")
+    try:
+        ctx.analyzer_available()
+    except AnalyzerIntegrityError as e:
+        return CheckResult(NAME, CheckStatus.ERROR, tool="semgrep",
+                           detail=clean_text(f"analyzer image failed verification; Semgrep was not run (no host fallback): {e}"))
+    except SandboxError as e:
+        return CheckResult(NAME, CheckStatus.UNAVAILABLE, tool="semgrep",
+                           detail=clean_text(f"analyzer image unavailable; Semgrep was not run (no host fallback): {e}"))
+    removed = remove_ignore_files(ctx)
+    t0 = time.monotonic()
+    try:
+        run = ctx.analyzer(build_argv(), cwd=ctx.project, env=None, timeout_s=ctx.timeout_s, max_output=ctx.max_output)
+    except ToolUnavailable as e:
+        return CheckResult(NAME, CheckStatus.UNAVAILABLE, detail=clean_text(e), tool="semgrep")
+    except SandboxError as e:
+        return CheckResult(NAME, CheckStatus.ERROR, tool="semgrep", duration_s=time.monotonic() - t0,
+                           detail=clean_text(f"isolated analyzer run failed; Semgrep results are not available (no host fallback): {e}"))
+    res = CheckResult(NAME, CheckStatus.ERROR, tool="semgrep", duration_s=time.monotonic() - t0)
+    if run.timed_out:
+        res.status, res.detail = CheckStatus.TIMEOUT, f"semgrep exceeded {ctx.timeout_s:g}s and was killed"
+        return res
+    if run.output_truncated:
+        res.detail = "semgrep output exceeded the size limit and the run was killed"
+        return res
+    if run.exit_code != 0:
+        res.detail = clean_text(f"semgrep exited with code {run.exit_code}: {run.stderr.strip()[:300]}")
+        return res
+    try:
+        findings, errs, scanned = parse_output(run.stdout, ctx.project)
+    except ValueError as e:
+        res.detail = clean_text(f"semgrep output unusable: {e}")
+        return res
+    res.findings = findings[: ctx.max_findings]
+    res.truncated_findings = max(0, len(findings) - ctx.max_findings)
+    res.errors = errs
+    res.notes = [f"{len(targets)} Python file(s) targeted", "rules: bundled local set (saferun/engine/rules/python.yml)"]
+    if removed:
+        res.notes.append(f"{removed} .semgrepignore file(s) removed from the analysis copy")
+    problems = []
+    if errs:
+        problems.append(f"semgrep reported {len(errs)} error(s); some files were not fully analysed")
+    if scanned is None:
+        problems.append("semgrep did not report which files it scanned; coverage cannot be verified")
+    else:
+        missing = sorted(set(targets) - scanned)
+        if missing:
+            shown = ", ".join(clean_text(m, 80) for m in missing[:5]) + (f" and {len(missing) - 5} more" if len(missing) > 5 else "")
+            problems.append(f"{len(missing)} targeted Python file(s) were not scanned by semgrep (e.g. too large): {shown}")
+            res.errors = errs + [f"not scanned: {clean_text(m, 200)}" for m in missing[:50]]
+    if problems:
+        res.status, res.detail = CheckStatus.INCOMPLETE, "; ".join(problems)
+    else:
+        res.status = CheckStatus.FINDINGS if res.findings else CheckStatus.PASSED
+    return res

saferun/engine/tools.py

@@ -0,0 +1,167 @@
+"""Controlled execution of external analysis tools (Semgrep, OSV-Scanner).
+
+These tools are *analyzers*: they read a sanitized copy of the project, they never run project code. Even so
+they parse untrusted input, so they get: argv only (no shell), an absolute executable path, a minimal
+environment, a private HOME, a new process group killed as a whole on timeout, and a hard output cap.
+Failure to run is reported as ToolUnavailable / a ToolRun flag - never as an empty "clean" output.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import subprocess
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+from .. import hostos
+from ..hostos import process as hostproc
+
+MAX_ARGS, MAX_ARG_LEN = 256, 4096
+DEFAULT_MAX_OUTPUT = 8 * 1024 * 1024
+_BASE_ENV = ("PATH", "LANG", "LC_ALL", "TZ")
+_NET_ENV = ("HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy",
+            "SSL_CERT_FILE", "SSL_CERT_DIR")
+
+
+class ToolUnavailable(RuntimeError):
+    """The executable is missing or cannot be started."""
+
+
+@dataclass
+class ToolRun:
+    argv: list[str]
+    exit_code: int | None        # None when killed (timeout / output cap)
+    stdout: str
+    stderr: str
+    timed_out: bool = False
+    output_truncated: bool = False   # output cap hit: the process was killed, output is incomplete
+    duration_s: float = 0.0
+    cancelled: bool = False          # the caller's cancel event fired (server shutdown): the process was interrupted/killed
+
+
+# Signature of the injectable runner; checks take one so tests can substitute canned results.
+ToolRunner = Callable[..., ToolRun]
+
+
+def find_tool(name: str) -> str | None:
+    """Absolute path of `name` on PATH, or None."""
+    p = shutil.which(name)
+    return os.path.abspath(p) if p else None
+
+
+def validate_argv(argv) -> list[str]:
+    if (not isinstance(argv, (list, tuple)) or not argv or len(argv) > MAX_ARGS
+            or not all(isinstance(a, str) and len(a) <= MAX_ARG_LEN and "\0" not in a for a in argv)
+            or not argv[0] or not os.path.isabs(argv[0])):
+        raise ValueError("argv must be a list of strings (NUL-free) starting with an absolute executable path")
+    return list(argv)
+
+
+def build_env(home: Path, network: bool = False, extra: dict[str, str] | None = None) -> dict[str, str]:
+    """Minimal environment: no inherited credentials/tokens. Proxy/cert variables only if `network`."""
+    env = {k: os.environ[k] for k in _BASE_ENV if k in os.environ}
+    if network:
+        env.update({k: os.environ[k] for k in _NET_ENV if k in os.environ})
+    env.update({k: os.environ[k] for k in hostos.base_env_names() if k in os.environ})
+    env.update(HOME=str(home), XDG_CACHE_HOME=str(home / "cache"), XDG_CONFIG_HOME=str(home / "config"),
+               TMPDIR=str(home))
+    env.update(hostos.private_home_env(str(home)))
+    env.update(extra or {})
+    return env
+
+
+def _drain(stream, cap: int, buf: bytearray, over: threading.Event) -> None:
+    while chunk := stream.read(65536):
+        room = cap - len(buf)
+        if room > 0:
+            buf += chunk[:room]
+        if len(chunk) > room:
+            over.set()
+
+
+def _kill_group(proc: subprocess.Popen) -> None:
+    if hostos.IS_WINDOWS:   # job object: ends the whole tree
+        return hostproc.kill_tree(proc)
+    try:
+        os.killpg(proc.pid, signal.SIGKILL)
+    except (ProcessLookupError, PermissionError):
+        pass
+    try:
+        proc.kill()
+    except OSError:
+        pass
+
+
+def _interrupt_group(proc: subprocess.Popen) -> None:
+    """SIGINT to the process group: lets a SafeRun CLI worker run its own cleanup (container, workspace) before it exits."""
+    if hostos.IS_WINDOWS:
+        return hostproc.interrupt_tree(proc)
+    try:
+        os.killpg(proc.pid, signal.SIGINT)
+    except (ProcessLookupError, PermissionError):
+        pass
+
+
+def run_tool(argv: list[str], *, cwd: Path, env: dict[str, str], timeout_s: float,
+             max_output: int = DEFAULT_MAX_OUTPUT, cancel: threading.Event | None = None,
+             cancel_grace_s: float = 15.0) -> ToolRun:
+    """Run `argv` (absolute executable, no shell). Raises ToolUnavailable if it cannot be started.
+
+    `cancel` (optional): when set, the process group gets SIGINT, then SIGKILL after `cancel_grace_s`; the result
+    has `cancelled=True` and no exit code (the run is never usable as a verdict)."""
+    argv = validate_argv(argv)
+    if not (timeout_s > 0):
+        raise ValueError("timeout_s must be positive")
+    t0 = time.monotonic()
+    try:
+        proc = subprocess.Popen(argv, cwd=str(cwd), env=env, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE, **hostproc.popen_kwargs())
+        hostproc.after_spawn(proc)   # Windows: confine to a job object, then let it run; POSIX: nothing
+    except OSError as e:
+        raise ToolUnavailable(f"cannot start {argv[0]}: {e}") from e
+    out, err, over = bytearray(), bytearray(), threading.Event()
+    readers = [threading.Thread(target=_drain, args=(s, max_output, b, over), daemon=True)
+               for s, b in ((proc.stdout, out), (proc.stderr, err))]
+    for t in readers:
+        t.start()
+    timed_out = cancelled = False
+    deadline = t0 + timeout_s
+    try:
+        while proc.poll() is None:
+            if cancel is not None and cancel.is_set():
+                cancelled = True
+                _interrupt_group(proc)
+                grace_end = time.monotonic() + cancel_grace_s
+                while proc.poll() is None and time.monotonic() < grace_end:
+                    time.sleep(0.02)
+                _kill_group(proc)   # also reaps anything the interrupted process left in its group
+                break
+            if over.is_set():
+                _kill_group(proc)
+                break
+            if time.monotonic() >= deadline:
+                timed_out = True
+                _kill_group(proc)
+                break
+            time.sleep(0.02)
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            _kill_group(proc)
+            proc.wait(timeout=10)
+    finally:
+        for t in readers:
+            t.join(timeout=5)
+        for s in (proc.stdout, proc.stderr):
+            s.close()
+        hostproc.release(proc)   # Windows: closing the job also ends anything the tool left behind
+    return ToolRun(
+        argv=argv, exit_code=None if (timed_out or cancelled or over.is_set()) else proc.returncode,
+        stdout=out.decode("utf-8", "replace"), stderr=err.decode("utf-8", "replace"),
+        timed_out=timed_out, output_truncated=over.is_set(), duration_s=time.monotonic() - t0,
+        cancelled=cancelled,
+    )

saferun/engine/verdict.py

@@ -0,0 +1,47 @@
+"""Verdict rules. Deterministic and documented (README/PROJECT.md mirror this).
+
+FAIL     any finding of severity CRITICAL or HIGH.
+WARNING  not FAIL, and any of: a finding of severity MEDIUM, LOW or UNKNOWN (UNKNOWN is treated as MEDIUM);
+         a check that is INCOMPLETE, ERROR, TIMEOUT, UNAVAILABLE or SKIPPED (the project was not fully
+         checked); a partial workspace copy (skipped/withheld entries); no check completed at all.
+PASS     at least one check ran to completion, none of the above applies. INFO findings do not matter.
+
+PASS means "the checks that exist found nothing", not "the code is safe". An operational problem can never
+produce PASS, and can never be hidden by a clean result from another check; it also does not by itself
+produce FAIL, because FAIL is reserved for demonstrated findings.
+"""
+from __future__ import annotations
+
+from .model import CheckResult, CheckStatus, Severity, Verdict
+
+_FAIL_AT = Severity.HIGH.rank
+
+
+def compute_verdict(checks: list[CheckResult], partial_workspace: str = "") -> tuple[Verdict, list[str], bool]:
+    """Return (verdict, reasons, complete). `partial_workspace` is a non-empty description when the
+    sandbox copy skipped or withheld entries."""
+    fail, warn = [], []
+    complete = True
+    for c in checks:
+        n_fail = sum(1 for f in c.findings if f.severity.rank >= _FAIL_AT)
+        n_warn = sum(1 for f in c.findings if 2 <= f.severity.rank < _FAIL_AT)
+        if n_fail:
+            fail.append(f"{c.name}: {n_fail} finding(s) of severity high or critical")
+        if n_warn:
+            warn.append(f"{c.name}: {n_warn} finding(s) of severity medium, low or unknown")
+        if c.truncated_findings:
+            warn.append(f"{c.name}: {c.truncated_findings} further finding(s) not listed (cap reached)")
+        if c.status.operational_problem:
+            complete = False
+            warn.append(f"{c.name}: {c.status.value}" + (f" - {c.detail}" if c.detail else ""))
+    if partial_workspace:
+        complete = False
+        warn.append(f"partial scan: {partial_workspace}")
+    if not any(c.status.completed and c.analysis for c in checks):
+        complete = False
+        warn.append("no check ran to completion; nothing was validated")
+    if fail:
+        return Verdict.FAIL, fail + warn, complete
+    if warn:
+        return Verdict.WARNING, warn, complete
+    return Verdict.PASS, ["all applicable checks completed with no findings above informational"], complete