Declarative JSON config for daemons the supervisor should spawn alongside
the workload with operator-declared ambient capabilities. Each listed
helper is forked by the supervisor before the workload, has its requested
caps raised into the inheritable and ambient sets via capset(2) and
prctl(PR_CAP_AMBIENT, PR_CAP_AMBIENT_RAISE, ...) in the pre-exec child,
and is then execve'd. After execve the ambient set becomes part of the
helper's permitted and effective sets, so it keeps its capabilities even
though the workload path still runs with PR_SET_NO_NEW_PRIVS=1.

Helpers run in the supervisor's context and do not inherit the per-workload
seccomp filter, PR_SET_NO_NEW_PRIVS, Landlock, or the uid drop. The
supervisor seccomp prelude added in NVIDIA#891 is applied after helpers spawn
and only blocks mount/fs*/pivot_root/bpf/kexec/module/userfaultfd syscalls,
so capset, prctl, clone, and execve remain available to the helper spawn
path.

Validation rejects empty names, duplicate names, empty commands,
non-absolute command[0], and unknown capability names. A cap outside the
supervisor's permitted set (which the pod's bounding set clamps) fails at
capset with EPERM and the supervisor exits before the workload starts.

The SSH handshake secret is scrubbed from the helper's inherited
environment, matching what the workload sees. Each helper start emits an
OCSF AppLifecycle Start event with the helper name and pid.

This generalizes the hardcoded DNS-proxy-shaped pattern into a public,
declarative API so operators can register audited daemons (capability
brokers, privileged IPC bridges) without patching the supervisor binary.

Intentionally out of scope for this v0 landing (tracked for follow-ups):
per-helper Landlock, workload rendezvous, restart policy, readiness fd,
stdio routing into OCSF JSONL, per-helper cgroup limits, and runAsUser
for dropping to non-root while retaining caps. All additive on the v0
schema.

Flag: --helpers-config <path> (env: OPENSHELL_HELPERS_CONFIG).
Architecture: architecture/supervisor-helpers.md.
User docs: docs/sandboxes/supervisor-helpers.mdx.

Signed-off-by: Serge Panev <[email protected]>
Signed-off-by: Serge Panev <[email protected]>

Helpers share the supervisor's network namespace by design, but that
netns was previously empty of iptables rules — anything spawned by a
helper that ignored HTTPS_PROXY (notably Node's built-in https.request,
which OpenClaw's web_fetch tool uses) could egress directly to any
host the pod could reach, with no policy check and no audit trail.

Install a small OUTPUT-chain rule set in the supervisor netns before
spawning the first helper:

  1. ACCEPT  -o lo                                     (mediator UDS, etc.)
  2. ACCEPT  -m conntrack --ctstate ESTABLISHED,RELATED
  3. ACCEPT  -d <proxy>/32 -p tcp --dport 3128         (proxy-aware path)
  4. ACCEPT  -m owner --uid-owner 0                    (supervisor + proxy
                                                        upstream forwarding)
  5. LOG     --log-prefix "openshell:helper-bypass:"   (bypass_monitor hook)
  6. REJECT  --reject-with icmp-port-unreachable       (fast-fail)

A helper that drops privileges (gosu, runner.c setresuid, etc.) and
then attempts a direct outbound TCP connection lands in the catch-all
REJECT and gets ECONNREFUSED plus a kernel LOG entry that
bypass_monitor parses into an OCSF DetectionFinding.

Trade-offs documented in the module-level comment block:

  * UID 0 ACCEPT covers the supervisor's own gRPC to control plane,
    log push, and the proxy's upstream forwarding (which would
    otherwise loop). Helpers haven't dropped privileges yet are also
    covered — a small bounded window between exec and uid switch.
  * Proxy IP/port hard-coded to 10.200.0.1:3128 to match
    sandbox::linux::netns::{SUBNET_PREFIX, HOST_IP_SUFFIX}; helpers
    spawn before policy load so the runtime address isn't available
    yet. A v1 refactor that moves spawn after policy load would replace
    these constants with the live values.
  * Degrades gracefully when iptables is missing (ConfigStateChange
    OCSF event with severity=Medium, helpers still spawn).

Verified end-to-end:
  - iptables -L OUTPUT in supervisor netns shows the 6 rules with
    matching packet counters.
  - `gosu gateway curl --noproxy '*' https://<ip>/` from inside the
    pod returns "Connection refused" (catch-all REJECT) where it
    previously connected directly.
  - Proxy-aware paths (sclaw → httpx, gateway → HTTPS_PROXY) continue
    to flow through the proxy and get attributed by OPA as before.

Signed-off-by: Serge Panev <[email protected]>