feat(three-stage-scan): run or skip deep regression with visible degradation

src/openultrasast/sandbox/__init__.py

@@ -1,6 +1,6 @@
 """Isolated Docker CLI sandbox."""
 
-from .probe import FakeSandboxProbe, SandboxProbe
+from .probe import FakeSandboxProbe, SandboxProbe, resolve_sandbox_probe
 from .runner import (
     DockerCliRunner,
     FakeSandboxRunner,
@@ -8,6 +8,7 @@ from .runner import (
     SandboxResult,
     SandboxRunner,
     build_docker_argv,
+    resolve_sandbox_runner,
 )
 
 __all__ = [
@@ -19,4 +20,6 @@ __all__ = [
     "SandboxResult",
     "SandboxRunner",
     "build_docker_argv",
+    "resolve_sandbox_probe",
+    "resolve_sandbox_runner",
 ]

src/openultrasast/sandbox/probe.py

@@ -2,13 +2,17 @@
 
 from __future__ import annotations
 
+import os
 import subprocess
 from collections.abc import Callable
 from subprocess import CompletedProcess
 
 PROBE_TIMEOUT_SECONDS = 5
+PROBE_ENV = "OPENULTRASAST_SANDBOX_PROBE"
 
 _DOCKER_INFO = ("docker", "info")
+_PROBE_OFF = frozenset({"0", "off", "false", "unavailable", "no"})
+_PROBE_ON = frozenset({"1", "on", "true", "available", "yes"})
 
 
 class SandboxProbe:
@@ -40,3 +44,13 @@ class FakeSandboxProbe:
 
     def available(self) -> bool:
         return self._available
+
+
+def resolve_sandbox_probe() -> SandboxProbe | FakeSandboxProbe:
+    """Return a real probe, or a fake when OPENULTRASAST_SANDBOX_PROBE is set."""
+    flag = os.environ.get(PROBE_ENV, "").strip().lower()
+    if flag in _PROBE_OFF:
+        return FakeSandboxProbe(False)
+    if flag in _PROBE_ON:
+        return FakeSandboxProbe(True)
+    return SandboxProbe()

src/openultrasast/sandbox/runner.py

@@ -15,8 +15,10 @@ NONROOT_USER = "65534:65534"
 WORKSPACE_MOUNT = "/workspace"
 SCRATCH_MOUNT = "/scratch"
 SCRATCH_SEED_MOUNT = "/scratch-in"
+RUNNER_ENV = "OPENULTRASAST_SANDBOX_RUNNER"
 _COPY_SEED_THEN_EXEC = 'cp -r /scratch-in/. /scratch/ && exec "$@"'
 _SEED_ARGV0 = "ousast-sandbox"
+_FAKE_RUNNER = frozenset({"fake"})
 
 
 class SandboxRunner(Protocol):
@@ -54,6 +56,14 @@ class FakeSandboxRunner:
         return self.result
 
 
+def resolve_sandbox_runner() -> SandboxRunner:
+    """Return the Docker CLI runner, or a fake when OPENULTRASAST_SANDBOX_RUNNER=fake."""
+    flag = os.environ.get(RUNNER_ENV, "").strip().lower()
+    if flag in _FAKE_RUNNER:
+        return FakeSandboxRunner()
+    return DockerCliRunner()
+
+
 class DockerCliRunner:
     """Run a job with Docker CLI flags that match the threat model."""