feat(sandbox): proxy_injection — route proxy-unaware JVM/Node tools through the omac proxy

[nhuelstng]

What

Adds a network.proxy_injection sandbox-profile option that routes proxy-unaware toolchains through omac's existing filtering proxy, so their traffic is subject to the network allowlist and interactive prompt like everything else.

// ~/.config/omac/sandbox-profiles/default.json
"network": {
  "mode": "filtered",
  "proxy_injection": ["jvm", "node"]
}

The option takes a list of tool families. Each family maps to a small env-injection that points that toolchain at the proxy. Two are supported today:

Family	What omac injects	Covers
jvm	a controlled JAVA_TOOL_OPTIONS (proxy sysprops + CONNECT-auth credentials)	Gradle & Maven (routed and authenticated); sbt, Kotlin, plain java are routed — proxy auth is tool-dependent, see the auth note below
node	NODE_USE_ENV_PROXY=1	Node's built-in fetch/http (undici); Node ≥ 24

Adding the next proxy-unaware family is a single entry in the sandboxrun injector registry — no changes to run.go or the profile schema.

Why

Most tools already work under a filtered sandbox — curl, git, pip, npm/yarn/pnpm, and go all honor HTTP_PROXY/HTTPS_PROXY, so their traffic already flows through the omac proxy and hits the allowlist + prompt. This PR is only for the families that ignore those env vars:

• JVM ignores HTTP_PROXY/HTTPS_PROXY entirely. Under a filtered sandbox a JVM build tool opens a direct connection, which the kernel (Landlock) blocks before the proxy filter runs — so the allow/deny prompt never fires and the build dies with an opaque java.net.BindException: Permission denied. (Full analysis in Network prompt unusable for proxy-unaware clients (JVM/gradle/maven): no popup, silent Landlock block; proxy-configured → 407; shown dialogs self-close #119.)
• Node's runtime HTTP client (undici, behind the built-in fetch) ignores proxy env unless opted in, so scripts/tools that use native fetch bypass the proxy the same way. (The npm/yarn/pnpm CLIs are not affected — they already honor the proxy env.)

proxy_injection makes that traffic flow through the existing proxy. Deliberately the simple fix:

• No new machinery — reuses the current proxy + filter + prompt.
• No new privilege — no netns/nftables/interception.
• No new secret exposure — the proxy token is already in the child's HTTP_PROXY env; the JVM just needs it in its own config to satisfy the proxy's CONNECT auth (a bare proxyHost/Port otherwise 407s). node reuses the injected HTTP_PROXY as-is.

How

• sandboxprofile: Network.ProxyInjection list + ProxyInjectionTools() (the single source of truth for valid family names) + validation.
• sandboxrun/proxyinject.go: a proxyInjectors registry mapping each family to a pure func(proxyURL) (map[string]string, error), plus ProxyInjectionEnv() that merges the env for all configured families.
  • jvm → JAVA_TOOL_OPTIONS (proxy host/port, userinfo credentials, and jdk.http.auth.tunneling.disabledSchemes= to re-enable Basic auth on HTTPS CONNECT).
  • node → NODE_USE_ENV_PROXY=1.
• run.go: on filtered runs, merges ProxyInjectionEnv() into the injected child env. FilterEnv's blocklist drops any ambient/attacker JAVA_TOOL_OPTIONS/NODE_*; omac's controlled values are then overlaid and win.

Verification

Automated (go test ./internal/sandboxrun/ ./internal/sandboxprofile/):

• JVMProxyToolOptions: with credentials, without, invalid-URL.
• ProxyInjectionEnv: jvm + node together; unknown family rejected.
• TestProxyInjectorsCoverProfileTools: guards against drift between the profile's valid set and the injector registry.
• Profile validation rejects unknown tools; HasProxyInjection accessor.

Manual — real Gradle 9.1 in omac sandbox run with proxy_injection: ["jvm"], no wrapper:

• omac logs proxy_injection: jvm routed through the omac proxy.
• Resolution flows through the proxy: net ALLOW repo.maven.apache.org:443 (allow_domain).
• A non-allowlisted repo raises the network prompt (previously: silent BindException, no prompt).

---

Guide — make JVM / Node builds work in the omac sandbox

Where this is configured: everything below lives in the sandbox profile — ~/.config/omac/sandbox-profiles/<profile>.json (default: default.json). It is not in the omac config.yaml; that file only selects which profile is active (--profile default). There is no --enforcement run flag — enforcement is a profile field.

1. Enable injection in your profile. Only list families that ignore HTTP_PROXY — npm, pip, git, go, curl need nothing here:

   // ~/.config/omac/sandbox-profiles/default.json
   {
     "network": {
       "mode": "filtered",
       "proxy_injection": ["jvm", "node"],
       "network_prompt": { "enabled": true },
       // pre-allow repos to skip the per-host prompt (optional):
       "allow_domain": [
         "repo.maven.apache.org", "repo1.maven.org",
         "plugins.gradle.org", "services.gradle.org",
         "registry.npmjs.org"
       ]
     }
   }

2. Run — no wrapper, no manual proxy config:

   omac start          # or: omac sandbox run -- ./gradlew build   (or: mvn verify, node build.js)
   

   Non-allowlisted hosts raise the usual network prompt; allowed ones resolve normally.

What each family covers

• jvm — one mechanism for the whole toolchain (no per-tool config files, no GRADLE_USER_HOME redirect). Host/port routing applies to every JVM: Gradle, Maven, sbt, Kotlin, plain java. Proxy authentication — the token the CONNECT tunnel requires — is only sent by tools that parse the proxyUser/proxyPassword sysprops themselves, i.e. Gradle and Maven. Tools that rely on the core JDK HTTP client (HttpURLConnection, java.net.http.HttpClient — e.g. a bare java) are routed through the proxy but won't authenticate and get a 407; bare-JDK proxy auth is out of scope here.
• node — Node's built-in fetch/http (undici). Requires Node ≥ 24; older runtimes silently ignore NODE_USE_ENV_PROXY (no-op, not an error). The npm/yarn/pnpm CLIs work without this family.
• Everything else (curl, git, pip, npm, go, …) already honors HTTP_PROXY and needs no entry.

Gradle specifics

Pick the enforcement row that matches how you invoke Gradle — the Gradle daemon is the only reason to relax it (see the daemon note under limitations):

You run	Set in profile	Why
./gradlew build (default = daemon)	"network": { "enforcement": "env-only" }	daemon uses a random loopback port Landlock can't allow selectively under kernel
./gradlew --no-daemon build (or org.gradle.daemon=false)	keep "enforcement": "kernel" (default)	no daemon port → full kernel guarantee retained (preferred)

Recommendation: prefer --no-daemon and keep kernel if you control the invocation; fall back to env-only only when you can't stop the daemon (the proxy filter + prompt still apply — you only lose the kernel bypass-guarantee).

JVM tuning must move to gradle.properties. With proxy_injection: ["jvm"] omac owns JAVA_TOOL_OPTIONS (it's on the always-drop env blocklist and omac overlays a proxy-only value), so heap/encoding/agent flags set via JAVA_TOOL_OPTIONS/_JAVA_OPTIONS won't reach the build. Use org.gradle.jvmargs=… instead.

Env not forwarded by default (base passthrough is PATH, HOME, USER, LANG, LC_ALL, LC_CTYPE, TMPDIR). Add only what your build needs:

"environment": { "allow_vars": ["JAVA_HOME", "GRADLE_USER_HOME", "GRADLE_OPTS"] }

• JAVA_HOME — single-JDK builds are fine via java on PATH; add it only for multi-JDK / toolchain-by-JAVA_HOME setups (and grant read access to the JDK dir).
• GRADLE_USER_HOME — unset → cache lands at the sandbox $HOME/.gradle; grant that path read-write or you get a cold cache (full re-download through the proxy) each run.
• Toolchain auto-download resolves through the proxy too — add the download host (e.g. api.foojay.io) to allow_domain.

Notes / limitations

• Token in stderr (jvm): the JVM prints a one-line Picked up JAVA_TOOL_OPTIONS: … notice containing the proxy token on each launch. The token is ephemeral (per session), proxy-scoped, and already present in HTTP_PROXY; avoid pasting raw build logs publicly.
• Kernel enforcement + Gradle daemon: the Gradle daemon talks to its client over a random loopback port. Landlock rules are port-based/address-blind, so they can't allow "any loopback port" without also allowing direct egress on those ports (which would defeat the guardrail). Under enforcement: "kernel" the Gradle daemon therefore can't connect — run Gradle under enforcement: "env-only" for now (the proxy filter and prompt still apply; only the kernel bypass-guarantee is relaxed — a "trusted build tool" posture). Non-daemon tools (Maven, plain java, Node) don't hit this and work under kernel.
• Private/authenticated registries are out of scope here. proxy_injection routes traffic through the proxy; it does not inject registry credentials. See the note below.

Private registry credentials (Maven/npm) — not solved by this PR

Getting the agent to install from an authenticated private registry is a separate concern. Because the build tool runs as the same uid as the agent inside the sandbox, any in-sandbox secret (env, .npmrc _authToken, settings.xml) is readable by the agent. Two paths:

• Today: forward a read-only, registry-scoped, short-lived deploy token via the profile env allowlist (or a mounted .npmrc/settings.xml) — accepting it is agent-readable, with bounded blast radius.
• Proper (follow-up): a host-side credential-lift reverse proxy that holds the token and injects Authorization upstream, so the sandbox only ever sees a loopback URL + throwaway session token — the same substrate as the Host-side LLM guard-proxy on the harness↔model path (content-level guardrails without TLS MITM) #89 harness↔model guard-proxy. Tracked as a second consumer of Host-side LLM guard-proxy on the harness↔model path (content-level guardrails without TLS MITM) #89, not a separate mechanism.

---

Closes part of #119 (the proxy-unaware-client gap for JVM + Node). Transparent, zero-config, kernel-enforced coverage for all proxy-unaware tools is the transparent-interception transport tracked in #119.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new sandbox-profile option, network.proxy_injection, to route selected proxy-unaware toolchains through omac’s existing filtering proxy so they participate in the allowlist + interactive network prompt under network.mode=filtered.

Changes:

• Extends the sandbox profile schema/validation with network.proxy_injection plus helpers/constants for supported families (jvm, node).
• Implements a sandboxrun injector registry that derives the required env vars for each family (notably JAVA_TOOL_OPTIONS for JVM and NODE_USE_ENV_PROXY=1 for Node).
• Wires proxy injection into sandboxrun.Run() for filtered runs and adds unit tests to prevent registry/profile drift.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
internal/sandboxrun/run.go	Merges per-family proxy injection env into the child env during filtered runs and emits a notice.
internal/sandboxrun/proxyinject.go	New injector registry + env merge helper; implements JVM/Node proxy injection logic.
internal/sandboxrun/proxyinject_test.go	Tests injector coverage, merged env output, and JVM tool options rendering/validation.
internal/sandboxprofile/profile.go	Adds network.proxy_injection field, supported-family constants, and validation.
internal/sandboxprofile/profile_test.go	Adds validation coverage and HasProxyInjection behavior tests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[NoRiceToday]

Reviewing

[NoRiceToday]

Adversarial review plus fresh empirical validation against an anonymized private Gradle build found three blocking gaps:

1. JVM injection routes the wrapper, plugin portal, Maven Central, and a private Maven registry through the omac proxy, but a cold Java toolchain download from Foojay fails at proxy authentication. That path uses a core-JDK client which does not send the injected proxy credentials, so a fresh build cannot provision its required toolchain.
2. On macOS, network.enforcement: env-only is not honored: Seatbelt still emits deny network* and permits only the proxy port. Gradle needs a random loopback socket for its file-lock handler, including with --no-daemon, so the documented fallback does not work. open_port: [0] permits the loopback IPC, but that is not the documented path.
3. Node <24 silently ignores NODE_USE_ENV_PROXY, while omac logs that the node family is routed through the proxy. The direct request then fails before the proxy/prompt; please detect and warn for unsupported versions rather than claiming routing.

The dependency-routing mechanism is demonstrably useful, but I recommend fixing these before calling Gradle/Node support complete. Would you prefer to address the three points in this PR, or ship the narrow routing improvement with corrected claims and track the unsupported paths as follow-ups?

[NoRiceToday]

Addendum to the review above:

4. macOS --workdir behavior differs from Linux. Linux changes the sandbox child CWD to the configured workdir, but the Seatbelt backend does not. Launching from another directory with --workdir <project> leaves relative commands such as ./gradlew unresolved.
5. network.proxy_injection is not documented in the shipped README or the OpenSpec sandbox-profile schema. The process-isolation spec also still says JAVA_TOOL_OPTIONS is always dropped, without documenting the deliberate supervisor-controlled injection exception.

These should be addressed in the implementation/documentation decision together with the three issues above.

[nhuelstng]

Thanks — addressed all five in this PR (rebased onto main, 1b7d9d0), each with a TDD red→green test.

1. Foojay toolchain auth — confirmed; out of scope as designed (core-JDK client can't authenticate the CONNECT tunnel → 407). Not code-fixed, but the README no longer implies it "just works" with an allowlist entry — it now states the toolchain download routes but 407s, and authenticated provisioning is deferred to the Host-side LLM guard-proxy on the harness↔model path (content-level guardrails without TLS MITM) #89-based credential-lift proxy.
2. macOS env-only not honored — fixed. generateSBPLNetwork now emits (allow network*) for filtered+env-only, mirroring the Linux no---enforce path (sbpl.go previously ignored Enforcement). Test: TestSBPLNetworkFilteredEnvOnly.
3. Node <24 overclaims routing — fixed. omac now probes node --version and, when unsupported/absent, warns and drops node from the "routed" log instead of claiming it. Tests: TestNodeProxyEnvSupported + wiring in run.go.
4. macOS --workdir no chdir — fixed. The child cwd is now set on the exec (ExecWithEnv(..., workdir, ...)); Linux got this via bwrap --chdir, Seatbelt had no equivalent. Tests: TestNewChildCmdSetsWorkdir, TestExecWithEnvRunsInWorkdir.
5. Docs gaps — fixed. network.proxy_injection documented in the README and the OpenSpec sandbox-profile schema; the process-isolation spec now notes the deliberate supervisor-controlled JAVA_TOOL_OPTIONS/NODE_USE_ENV_PROXY injection exception (ambient still dropped in layer 1, supervisor value overlaid in layer 3).

Re your question: went with addressing the points in-PR rather than deferring, except #1 which stays out of scope with corrected claims. go build/vet/test ./... green on Linux; cross-build+vet green for darwin.