sproxy 0.1.0__py3-none-any.whl

sproxy/runner.py

@@ -0,0 +1,850 @@
+"""Orchestration: launch mitmdump with the guard addon, then run the agent.
+
+Trust boundary: this process is trusted and resolves the real secret values. It
+writes them to a 0600 file that only the *mitmdump* subprocess is told about
+(via ``SPROXY_POLICY``). The agent child process is given the proxy/CA env plus
+opaque, per-session replacement handles, but never real secret values or that
+policy path. Any env-sourced secrets are scrubbed before those handles are
+added. PostgreSQL passwords likewise stay in this process: the child only
+receives local gateway endpoints and a per-session token (see :mod:`sproxy.pg`).
+
+The policy file is watched while the session runs, so editing it takes effect
+without a restart (see :class:`LiveSession`). A reload changes the *rules*, never
+the session's identity: every handle already issued - secret handles, the
+postgres token, the local gateway ports - outlives it, because a child process's
+environment is frozen at exec time and revoking it would break a running agent.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import shlex
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from collections.abc import Iterable
+from pathlib import Path
+
+from sproxy import ca, pg
+from sproxy.policy import Policy, load
+from sproxy.secrets_resolver import SecretResolutionError, resolve
+
+_PKG_DIR = Path(__file__).resolve().parent
+_ADDON = _PKG_DIR / "addon.py"
+_PKG_PARENT = str(_PKG_DIR.parent)
+_ENV_VAR_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_SESSION_TOKEN_PREFIX = "sproxy_v1_"
+
+
+class RunnerError(RuntimeError):
+    pass
+
+
+class SessionIdentity:
+    """The handles a session hands out, which a policy reload must not rotate.
+
+    The guarded process reads its credentials from its environment once, at
+    startup. So the *names* stay valid for the whole session and only what they
+    unlock changes: a reloaded policy re-resolves a secret's value behind the
+    same handle, and a postgres profile keeps its token and local port. A secret
+    dropped from the policy has its handle revoked rather than forgotten - see
+    :meth:`revoked_handles`.
+    """
+
+    def __init__(self) -> None:
+        self._pg_token = ""
+        self.secret_tokens: dict[str, str] = {}
+        self.pg_ports: dict[str, int] = {}
+
+    @property
+    def pg_token(self) -> str:
+        """The postgres gateway password, minted once per session on first use."""
+        if not self._pg_token:
+            self._pg_token = secrets.token_urlsafe(24)
+        return self._pg_token
+
+    def secret_token(self, name: str) -> str:
+        token = self.secret_tokens.get(name)
+        if token is None:
+            token = _SESSION_TOKEN_PREFIX + secrets.token_urlsafe(32)
+            self.secret_tokens[name] = token
+        return token
+
+    def revoked_handles(self, live: Iterable[str]) -> list[dict]:
+        """Handles issued for secrets the policy no longer defines.
+
+        The guarded process still has them in its environment, so the guard
+        keeps recognising them - they just unlock nothing now, and turning up in
+        a request counts as a leak.
+        """
+        current = set(live)
+        return [
+            {"name": name, "session_token": token}
+            for name, token in self.secret_tokens.items()
+            if name not in current
+        ]
+
+    def remember_ports(self, endpoints: list[pg.Endpoint]) -> None:
+        for endpoint in endpoints:
+            if endpoint.bound_port:
+                self.pg_ports[endpoint.profile.name] = endpoint.bound_port
+
+
+def find_mitmdump(override: str | None = None) -> str:
+    path = override or shutil.which("mitmdump")
+    if not path:
+        raise RunnerError(
+            "mitmdump not found on PATH. Install mitmproxy "
+            "(https://mitmproxy.org/) or `pip install \"mitmproxy>=11\"`, "
+            "or pass --mitmdump /path/to/mitmdump."
+        )
+    return path
+
+
+def resolve_policy(policy: Policy, identity: SessionIdentity | None = None) -> dict:
+    """Resolve secret sources to values, returning the dict handed to the addon."""
+    identity = identity or SessionIdentity()
+    resolved_secrets = []
+    for spec in policy.secrets:
+        try:
+            value = resolve(spec.source)
+        except SecretResolutionError as exc:
+            raise RunnerError(f"secret {spec.name!r}: {exc}") from exc
+        resolved_secret = {
+            "name": spec.name,
+            "value": value,
+            "allow_hosts": spec.allow_hosts,
+        }
+        # Conventional SDKs read a configured environment variable rather than
+        # a literal request placeholder. Give valid variable names an opaque,
+        # per-session handle that the addon can replace in transit. The handle
+        # belongs to the session, so a reload re-resolves the value behind it.
+        if _ENV_VAR_NAME.fullmatch(spec.name):
+            resolved_secret["session_token"] = identity.secret_token(spec.name)
+        resolved_secrets.append(resolved_secret)
+    return {
+        "mode": policy.mode,
+        "on_leak": policy.on_leak,
+        "detect_patterns": policy.detect_patterns,
+        "audit_log": str(Path(policy.audit_log).expanduser()) if policy.audit_log else "",
+        "watch_values": policy.watch_values,
+        "passthrough_hosts": policy.passthrough_hosts,
+        "secrets": resolved_secrets,
+        "revoked_handles": identity.revoked_handles(s.name for s in policy.secrets),
+    }
+
+
+def resolve_postgres(
+    policy: Policy, identity: SessionIdentity | None = None
+) -> list[pg.Endpoint]:
+    """Resolve each profile's password source. Values never leave this process."""
+    endpoints = []
+    for profile in policy.postgres:
+        try:
+            password = resolve(profile.password_source)
+        except SecretResolutionError as exc:
+            raise RunnerError(f"postgres profile {profile.name!r}: {exc}") from exc
+        endpoint = pg.Endpoint(profile, password)
+        if identity is not None:
+            # The port this profile last served on, so a profile that is removed
+            # from the policy and put back keeps the endpoint already advertised.
+            endpoint.bound_port = identity.pg_ports.get(profile.name)
+        endpoints.append(endpoint)
+    return endpoints
+
+
+def _pg_audit_path(audit_log: str) -> str:
+    """Sibling audit file for the gateway - each hash chain has one writer."""
+    if not audit_log:
+        return ""
+    p = Path(audit_log).expanduser()
+    return str(p.with_name(p.stem + "-postgres" + p.suffix))
+
+
+def _write_policy_file(path: Path, resolved: dict) -> None:
+    """Publish the resolved policy for the addon: 0600, and atomically.
+
+    The addon re-reads this file whenever it changes, so the swap must be a
+    rename - a guard that read a half-written file would be a guard with no
+    rules. The temporary file is created in the same private directory.
+    """
+    tmp = path.with_name(path.name + ".new")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(resolved, fh)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def _file_stamp(path: str | Path | None) -> tuple[int, int] | None:
+    """Cheap change detector: (mtime_ns, size), or None when unreadable."""
+    if not path:
+        return None
+    try:
+        st = os.stat(path)
+    except OSError:
+        return None
+    return st.st_mtime_ns, st.st_size
+
+
+def session_env_path() -> Path:
+    """Well-known location of the live session's environment file.
+
+    Lets shells that were not started by ``sproxy run`` join the session
+    (``eval "$(sproxy env)"``) - the ssh-agent pattern. XDG_RUNTIME_DIR is a
+    per-user tmpfs cleaned on logout; the home fallback covers systems
+    without it.
+    """
+    runtime = os.environ.get("XDG_RUNTIME_DIR")
+    base = Path(runtime) / "sproxy" if runtime else Path.home() / ".sproxy"
+    return base / "session.env"
+
+
+def _write_session_env(
+    path: Path,
+    port: int,
+    additions: dict[str, str],
+    scrub: set[str],
+    replacements: list[str] | None = None,
+    session_handles: set[str] | None = None,
+) -> str:
+    """Write the session's env additions as shell export lines, mode 0600.
+
+    ``scrub`` names env-sourced secrets: joining shells may still carry the
+    real values that ``sproxy run`` strips from its own child, so the file
+    unsets them. ``replacements`` are rendered as comments so ``sproxy env``
+    can advertise the request placeholders without exposing resolved values or
+    breaking ``eval "$(sproxy env)"``. ``session_handles`` are environment
+    variable names whose exported values are temporary local capabilities.
+    """
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    lines = [
+        '# sproxy session environment - join with: eval "$(sproxy env)"',
+        f"# sproxy-port: {port}",
+    ]
+    replacements = replacements or []
+    if replacements:
+        lines.append("# sproxy replacements:")
+        for token in replacements:
+            # A TOML quoted key can technically contain newlines. Keep every
+            # placeholder on its comment line so sourcing the file stays safe.
+            safe_token = token.replace("\r", r"\r").replace("\n", r"\n")
+            lines.append(f"#   {safe_token}")
+    else:
+        lines.append("# sproxy replacements: (none)")
+    session_handles = session_handles or set()
+    if session_handles:
+        lines.append("# sproxy temporary secret handles:")
+        for name in sorted(session_handles):
+            lines.append(f"#   {name} (session-only)")
+    for name in sorted(scrub):
+        lines.append(f"unset {name}")
+    for key, value in additions.items():
+        lines.append(f"export {key}={shlex.quote(value)}")
+    content = "\n".join(lines) + "\n"
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(content)
+    return content
+
+
+def _print_session_env(content: str, *, stream=None) -> None:
+    """Print the exact shell exports available from ``sproxy env``."""
+    destination = stream or sys.stderr
+    print("sproxy: session environment (same as `sproxy env`):", file=destination)
+    print(content, end="" if content.endswith("\n") else "\n", file=destination, flush=True)
+
+
+def _env_sourced_names(policy: Policy) -> set[str]:
+    names = set()
+    for spec in policy.secrets:
+        backend, _, path = spec.source.partition(":")
+        if backend == "env" and path:
+            names.add(path)
+    return names
+
+
+def _session_secret_env(resolved: dict) -> dict[str, str]:
+    """Environment variables exposing opaque handles for SDK-style clients."""
+    return {
+        secret["name"]: secret["session_token"]
+        for secret in resolved.get("secrets", [])
+        if isinstance(secret.get("name"), str)
+        and _ENV_VAR_NAME.fullmatch(secret["name"])
+        and isinstance(secret.get("session_token"), str)
+        and secret["session_token"]
+    }
+
+
+def _replacement_tokens(policy: Policy) -> list[str]:
+    """Return the public placeholders accepted by the request injector."""
+    return [f"{{{{{spec.name}}}}}" for spec in policy.secrets]
+
+
+def _plus_minus(added: Iterable[str], removed: Iterable[str],
+                changed: Iterable[str] = ()) -> str:
+    return " ".join(
+        [f"+{name}" for name in added]
+        + [f"-{name}" for name in removed]
+        + [f"~{name}" for name in changed]
+    )
+
+
+def _restart_only_notes(live: Policy, new: Policy) -> list[str]:
+    """Fields the session is built around and cannot adopt while running."""
+    notes = []
+    if new.port != live.port:
+        notes.append(f"port {live.port} -> {new.port} needs a restart (still on {live.port})")
+    if new.confdir != live.confdir:
+        notes.append("confdir change needs a restart (CA is already in use)")
+    return notes
+
+
+def _policy_changes(live: Policy, new: Policy) -> list[str]:
+    """Human-readable diff of what a reload actually changed. Never values."""
+    notes = []
+    for field in ("mode", "on_leak", "detect_patterns", "audit_log"):
+        before, after = getattr(live, field), getattr(new, field)
+        if before != after:
+            notes.append(f"{field}: {before} -> {after}")
+    before, after = live.passthrough_hosts, new.passthrough_hosts
+    summary = _plus_minus(
+        [h for h in after if h not in before], [h for h in before if h not in after]
+    )
+    if summary:
+        notes.append(f"passthrough_hosts: {summary}")
+    if len(live.watch_values) != len(new.watch_values):
+        # Values are secrets in their own right; report the count only.
+        notes.append(f"watch_values: {len(live.watch_values)} -> {len(new.watch_values)}")
+
+    before_secrets = {s.name: s for s in live.secrets}
+    after_secrets = {s.name: s for s in new.secrets}
+    summary = _plus_minus(
+        [n for n in after_secrets if n not in before_secrets],
+        [n for n in before_secrets if n not in after_secrets],
+        [
+            n for n, spec in after_secrets.items()
+            if n in before_secrets
+            and (
+                spec.source != before_secrets[n].source
+                or spec.allow_hosts != before_secrets[n].allow_hosts
+            )
+        ],
+    )
+    if summary:
+        notes.append(f"secrets: {summary}")
+    return notes
+
+
+def _postgres_notes(changes: dict[str, list[str]], gateway) -> list[str]:
+    """Spell out what a postgres change means for credentials already issued."""
+    notes = []
+    ports = {}
+    if gateway is not None:
+        ports = {e.profile.name: e.bound_port for e in gateway.gateway.endpoints}
+    for name in changes.get("added", []):
+        notes.append(
+            f"postgres +{name}: listening on 127.0.0.1:{ports.get(name)} - shells "
+            'already running cannot see it; join again with eval "$(sproxy env)"'
+        )
+    for name in changes.get("updated", []):
+        notes.append(f"postgres ~{name}: same endpoint and token, applies to the next connection")
+    for name in changes.get("rebound", []):
+        notes.append(
+            f"postgres >{name}: moved to 127.0.0.1:{ports.get(name)} - the endpoint "
+            "issued earlier is stale, rejoin the session"
+        )
+    for name in changes.get("removed", []):
+        notes.append(
+            f"postgres -{name}: no new connections accepted; open ones keep running"
+        )
+    return notes
+
+
+class LiveSession:
+    """A running session whose policy file can be re-read on the fly.
+
+    Holds everything a reload is allowed to touch, and knows what it must not:
+    the listen port, the CA, the postgres session token and every secret handle
+    already exported into the guarded process are fixed for the session.
+    """
+
+    def __init__(
+        self,
+        policy: Policy,
+        identity: SessionIdentity,
+        resolved: dict,
+        *,
+        config_path: str | Path | None,
+        policy_file: Path,
+        cert: Path,
+        port: int,
+        reserved_env: set[str],
+        gateway: pg.GatewayThread | None = None,
+        stream=None,
+    ):
+        self.policy = policy
+        self.identity = identity
+        self.resolved = resolved
+        self.config_path = config_path
+        self.policy_file = policy_file
+        self.cert = cert
+        self.port = port
+        self.gateway = gateway
+        self.session_file: Path | None = None
+        self._reserved_env = reserved_env
+        self._stream = stream
+        self._lock = threading.Lock()
+        self._closed = False
+
+    # -- session environment --------------------------------------------
+
+    def session_secrets(self) -> dict[str, str]:
+        """Handles to export, minus names the guarded environment already uses."""
+        reserved = self._reserved_env - _env_sourced_names(self.policy)
+        return {
+            name: value
+            for name, value in _session_secret_env(self.resolved).items()
+            if name not in reserved
+        }
+
+    def write_session_env(self) -> str:
+        """(Re)write the file that ``sproxy env`` hands to joining shells."""
+        additions = ca.proxy_env(self.port, self.cert, base={})
+        additions.update(self.session_secrets())
+        if self.gateway is not None:
+            additions.update(self.gateway.child_env())
+        path = session_env_path()
+        try:
+            content = _write_session_env(
+                path,
+                self.port,
+                additions,
+                _env_sourced_names(self.policy),
+                _replacement_tokens(self.policy),
+                set(self.session_secrets()),
+            )
+        except OSError as exc:
+            self._say(f"sproxy: could not write session env file: {exc}")
+            self.session_file = None
+            return ""
+        self.session_file = path
+        return content
+
+    # -- reload ----------------------------------------------------------
+
+    def reload(self) -> bool:
+        """Re-read the policy file and apply it. True when it took effect.
+
+        Nothing is applied unless everything resolves: a policy that no longer
+        parses, a secret backend that is down or a local port that is taken
+        leaves the session running exactly as it was.
+        """
+        if self.config_path is None:
+            return False
+        with self._lock:
+            if self._closed:
+                return False
+            try:
+                return self._reload()
+            except Exception as exc:  # a bad edit must never end the session
+                self._say(f"sproxy: reload failed, keeping the running policy: {exc}")
+                return False
+
+    def close(self) -> None:
+        """Refuse further reloads, waiting for one already under way.
+
+        Taking the lock is the point: teardown must not race a reload that is
+        part-way through binding listeners it would then leave running.
+        """
+        with self._lock:
+            self._closed = True
+
+    def _reload(self) -> bool:
+        new_policy = load(self.config_path)
+        pinned = _restart_only_notes(self.policy, new_policy)
+        resolved = resolve_policy(new_policy, self.identity)
+        endpoints = resolve_postgres(new_policy, self.identity)
+        resolved["watch_values"] = [
+            *resolved["watch_values"], *(e.password for e in endpoints)
+        ]
+        # Bind first: a port collision must abort while the old rules still hold.
+        pg_changes = self._apply_postgres(endpoints, new_policy)
+        self.identity.remember_ports(endpoints)
+        # The addon is watching this file - this line is where the new rules
+        # start applying to traffic.
+        _write_policy_file(self.policy_file, resolved)
+
+        previous, self.policy, self.resolved = self.policy, new_policy, resolved
+        self.write_session_env()
+        self._report(_policy_changes(previous, new_policy) + pinned
+                     + _postgres_notes(pg_changes, self.gateway))
+        return True
+
+    def _apply_postgres(
+        self, endpoints: list[pg.Endpoint], new_policy: Policy
+    ) -> dict[str, list[str]]:
+        audit_log = _pg_audit_path(new_policy.audit_log)
+        if self.gateway is None:
+            if not endpoints:
+                return {}
+            # The session started without any database; stand the gateway up now.
+            gateway = pg.GatewayThread(
+                pg.PostgresGateway(endpoints, self.identity.pg_token, audit_log=audit_log)
+            )
+            # Keep the thread even if binding fails: it is empty but usable, so
+            # the next reload can retry instead of leaking another thread.
+            self.gateway = gateway
+            gateway.start()
+            return {"added": [e.profile.name for e in endpoints]}
+        return self.gateway.apply(endpoints, audit_log=audit_log)
+
+    def _report(self, notes: list[str]) -> None:
+        header = f"sproxy: reloaded {self.config_path}"
+        if not notes:
+            self._say(f"{header} (no effective changes)")
+            return
+        self._say("\n".join([header] + [f"sproxy:   {note}" for note in notes]))
+
+    def _say(self, message: str) -> None:
+        print(message, file=self._stream or sys.stderr, flush=True)
+
+
+class ConfigWatcher:
+    """Reload a :class:`LiveSession` when its policy file changes, or on SIGHUP.
+
+    Polling rather than inotify: sproxy has no third-party dependencies here,
+    and a policy file is often a bind mount or a projected secret that inotify
+    would never report a change for.
+    """
+
+    interval = 1.0
+    settle = 0.3
+
+    def __init__(self, session: LiveSession):
+        self._session = session
+        self._stop = threading.Event()
+        self._hup = threading.Event()
+        self._previous_sighup = None
+        self._thread = threading.Thread(
+            target=self._watch, name="sproxy-config", daemon=True
+        )
+
+    def start(self) -> None:
+        sighup = getattr(signal, "SIGHUP", None)
+        if sighup is not None:
+            try:
+                self._previous_sighup = signal.signal(sighup, self._on_sighup)
+            except ValueError:  # not the main thread (tests)
+                self._previous_sighup = None
+        self._thread.start()
+
+    def stop(self, timeout: float = 2.0) -> None:
+        self._stop.set()
+        if self._thread.is_alive():
+            self._thread.join(timeout)
+        sighup = getattr(signal, "SIGHUP", None)
+        if sighup is not None and self._previous_sighup is not None:
+            try:
+                signal.signal(sighup, self._previous_sighup)
+            except ValueError:
+                pass
+
+    def _on_sighup(self, signum, frame) -> None:
+        # Signal handlers run on the main thread, where the session may be
+        # mid-reload; just ask the watcher to do it.
+        self._hup.set()
+
+    def _watch(self) -> None:
+        path = self._session.config_path
+        stamp = _file_stamp(path)
+        while not self._stop.wait(self.interval):
+            if self._hup.is_set():
+                self._hup.clear()
+                self._session.reload()
+                stamp = _file_stamp(path)
+                continue
+            current = _file_stamp(path)
+            # A missing file is treated as "no change": an editor that replaces
+            # the file has a moment where it does not exist, and a policy the
+            # user deleted should not silently disarm the guard.
+            if current is None or current == stamp:
+                continue
+            if self._stop.wait(self.settle):
+                return
+            if _file_stamp(path) != current:
+                continue  # still being written; the next tick picks it up
+            stamp = current
+            self._session.reload()
+
+
+def _port_open(port: int, host: str = "127.0.0.1") -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(0.25)
+        return s.connect_ex((host, port)) == 0
+
+
+def _wait_port(port: int, proc: subprocess.Popen, timeout: float = 15.0) -> None:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if proc.poll() is not None:
+            raise RunnerError(
+                f"mitmdump exited early (code {proc.returncode}); "
+                f"is port {port} already in use?"
+            )
+        if _port_open(port):
+            return
+        time.sleep(0.1)
+    raise RunnerError(f"proxy did not start listening on port {port} in time")
+
+
+def run(policy: Policy, command: list[str], *, insecure: bool = False,
+        mitmdump: str | None = None, log_file: str | None = None,
+        config_path: str | Path | None = None, port: int | None = None,
+        watch_config: bool = True) -> int:
+    """Run ``command`` behind the guard, returning its exit code.
+
+    With no command, hold the session open until Ctrl-C so that other shells
+    can join it via ``eval "$(sproxy env)"``.
+
+    ``config_path`` is the policy file this session was loaded from; while it is
+    given and ``watch_config`` is set, edits to it are applied to the running
+    session (and so is SIGHUP). ``port`` overrides the policy's listen port for
+    this session only, which keeps ``policy.port`` free to track the file.
+    """
+    mitmdump_bin = find_mitmdump(mitmdump)
+    listen_port = port or policy.port
+    identity = SessionIdentity()
+    resolved = resolve_policy(policy, identity)
+    pg_endpoints = resolve_postgres(policy, identity)
+    # A database password showing up in HTTP traffic is a leak - have the
+    # addon watch for the resolved values like any other guarded secret.
+    resolved["watch_values"] = [
+        *resolved["watch_values"], *(e.password for e in pg_endpoints)
+    ]
+    confdir = ca.default_confdir() if not policy.confdir else Path(policy.confdir).expanduser()
+    cert = ca.cert_path(confdir)
+
+    run_dir = Path(tempfile.mkdtemp(prefix="sproxy-"))
+    os.chmod(run_dir, 0o700)
+    policy_file = run_dir / "policy.json"
+    _write_policy_file(policy_file, resolved)
+
+    mitm_env = dict(os.environ)
+    mitm_env["SPROXY_POLICY"] = str(policy_file)
+    mitm_env["SPROXY_PKG"] = _PKG_PARENT
+
+    mitm_cmd = [
+        mitmdump_bin,
+        "-q",
+        "--set", f"confdir={confdir}",
+        "--listen-host", "127.0.0.1",
+        "--listen-port", str(listen_port),
+        "--set", "connection_strategy=lazy",  # needed for WebFetch-style tools
+        "--set", "flow_detail=0",
+        "-s", str(_ADDON),
+    ]
+    if insecure:
+        mitm_cmd += ["--set", "ssl_insecure=true"]
+
+    log = None
+    if log_file:
+        path = Path(log_file).expanduser()
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            # The proxy log can include URLs and host names, so keep it private
+            # by default.  Append so a separate `tail -f` session survives runs.
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+            log = os.fdopen(fd, "a", encoding="utf-8", buffering=1)
+        except OSError as exc:
+            raise RunnerError(f"could not open proxy log {path}: {exc}") from exc
+
+    proxy = subprocess.Popen(
+        mitm_cmd,
+        env=mitm_env,
+        stdout=log if log is not None else None,
+        stderr=log if log is not None else None,
+    )
+    child: subprocess.Popen | None = None
+    gateway: pg.GatewayThread | None = None
+    session: LiveSession | None = None
+    watcher: ConfigWatcher | None = None
+
+    def _terminate(signum, frame):
+        raise KeyboardInterrupt
+
+    try:
+        # A plain `kill` (systemd, pod eviction) must clean up like Ctrl-C -
+        # especially in no-command mode, where nothing else ends the session.
+        previous_sigterm = signal.signal(signal.SIGTERM, _terminate)
+    except ValueError:  # not the main thread (tests)
+        previous_sigterm = None
+    try:
+        _wait_port(listen_port, proxy)
+        if not ca.wait_for_cert(cert):
+            raise RunnerError(
+                f"mitmproxy CA cert not found at {cert}. "
+                f"Try running `mitmdump` once, or set confdir in your policy."
+            )
+
+        child_env = ca.proxy_env(listen_port, cert)
+        for name in _env_sourced_names(policy):  # don't leak env secrets to the agent
+            child_env.pop(name, None)
+        for var in ("SPROXY_POLICY", "SPROXY_PKG"):
+            child_env.pop(var, None)
+
+        if pg_endpoints:
+            gateway = pg.GatewayThread(
+                pg.PostgresGateway(
+                    pg_endpoints,
+                    identity.pg_token,
+                    audit_log=_pg_audit_path(policy.audit_log),
+                )
+            )
+            try:
+                gateway.start()
+            except pg.PgError as exc:
+                raise RunnerError(str(exc)) from exc
+            child_env.update(gateway.child_env())
+        identity.remember_ports(pg_endpoints)
+
+        # Do not override the proxy/CA environment. A secret with a reserved
+        # name remains available through its {{NAME}} request placeholder.
+        session = LiveSession(
+            policy,
+            identity,
+            resolved,
+            config_path=config_path,
+            policy_file=policy_file,
+            cert=cert,
+            port=listen_port,
+            reserved_env=set(child_env),
+            gateway=gateway,
+            stream=log,
+        )
+        session_secrets = session.session_secrets()
+        child_env.update(session_secrets)
+        session_env_content = session.write_session_env()
+
+        _print_banner(
+            policy,
+            cert,
+            stream=log,
+            gateway=gateway,
+            session_secrets=session_secrets,
+            port=listen_port,
+            config_path=config_path,
+        )
+        if session.session_file is not None:
+            _print_session_env(session_env_content, stream=log)
+            print(
+                'sproxy: other shells can join this session: eval "$(sproxy env)"',
+                file=log or sys.stderr,
+                flush=True,
+            )
+        if watch_config and config_path is not None:
+            watcher = ConfigWatcher(session)
+            watcher.start()
+            print(
+                f"sproxy: watching {config_path} - edits apply live "
+                "(session tokens and database endpoints stay valid)",
+                file=log or sys.stderr,
+                flush=True,
+            )
+        if not command:
+            print(
+                "sproxy: no command given - holding the session open (Ctrl-C to stop)",
+                file=log or sys.stderr,
+                flush=True,
+            )
+            while proxy.poll() is None:
+                time.sleep(0.5)
+            raise RunnerError(f"mitmdump exited unexpectedly (code {proxy.returncode})")
+        child = subprocess.Popen(command, env=child_env)
+        return child.wait()
+    except KeyboardInterrupt:
+        if child is not None:
+            child.wait()
+            return 130
+        return 0  # Ctrl-C is the normal way to stop a held-open session
+    finally:
+        if watcher is not None:
+            # Stop reloading before tearing anything down, so a config change
+            # landing during shutdown cannot resurrect a listener.
+            watcher.stop()
+        if session is not None:
+            session.close()
+        for proc in (child, proxy):
+            if proc is not None and proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+        # A reload may have created the gateway after this session started.
+        gateway = session.gateway if session is not None else gateway
+        if gateway is not None:
+            try:
+                gateway.stop()
+            except Exception:
+                pass
+        if session is not None and session.session_file is not None:
+            session.session_file.unlink(missing_ok=True)
+        if previous_sigterm is not None:
+            signal.signal(signal.SIGTERM, previous_sigterm)
+        if log is not None:
+            log.close()
+        shutil.rmtree(run_dir, ignore_errors=True)
+
+
+def _print_banner(
+    policy: Policy,
+    cert: Path,
+    *,
+    stream=None,
+    gateway: pg.GatewayThread | None = None,
+    session_secrets: dict[str, str] | None = None,
+    port: int | None = None,
+    config_path: str | Path | None = None,
+) -> None:
+    mode = policy.mode.upper()
+    lines = [
+        f"sproxy: guarding on 127.0.0.1:{port or policy.port}  mode={mode}  on_leak={policy.on_leak}",
+        # Which file is in force decides every rule below, and ./sproxy.toml
+        # quietly wins over the user-level config - so never leave it implicit.
+        f"sproxy: policy: {Path(config_path).resolve() if config_path else '(built-in monitor default - no policy file found)'}",
+        f"sproxy: {len(policy.secrets)} secret(s) managed, audit -> {policy.audit_log or 'disabled'}",
+    ]
+    replacements = _replacement_tokens(policy)
+    if replacements:
+        lines.append("sproxy: replacements:")
+        lines.extend(f"sproxy:   {token}" for token in replacements)
+    else:
+        lines.append("sproxy: replacements: (none)")
+    if session_secrets:
+        lines.append("sproxy: temporary secret environment variables:")
+        lines.extend(
+            f"sproxy:   {name} (session-only handle)"
+            for name in sorted(session_secrets)
+        )
+    if gateway is not None:
+        for endpoint in gateway.gateway.endpoints:
+            profile = endpoint.profile
+            lines.append(
+                f"sproxy: postgres {profile.name} ({profile.host}) -> "
+                f"127.0.0.1:{endpoint.bound_port}  connect: psql \"${profile.env_var}\""
+            )
+    print("\n".join(lines), file=stream or sys.stderr, flush=True)