Add enforcement-only egress mode and live egress policy updates

[hiroTamada]

Summary

Decouples host-side egress enforcement from the MITM proxy, so an instance can get TAP-level egress blocking while pointing its workload at an external proxy reachable at the network gateway (e.g. a host-side forward proxy on the bridge gateway).

• network.egress.proxy: mitm (default, existing behavior) or none. With none, hypeman applies the iptables FORWARD rules on the instance TAP but skips proxy registration, HTTP_PROXY/HTTPS_PROXY env injection, and guest CA install. Credentials still require mitm.
• network.egress.enforcement.mode: all_traffic: new mode that also rejects direct UDP egress (blocks QUIC and direct DNS; guests must resolve through their proxy). Existing all / http_https_only semantics unchanged.
• PATCH /instances/{id} accepts egress: enforcement-only policies can be set, changed, or cleared per instance at runtime — iptables rules are applied/removed live on running instances (with rollback if the metadata save fails), or picked up on next start/restore for stopped/standby instances. mitm policies remain create-only since their guest-visible config (env, CA) is fixed at boot.
• Enforcement-only instances are cleaned up on stop/standby/delete even when the proxy service was never started.
• Back-compat: persisted metadata without the new field resolves to mitm; the default all mode still permits any traffic to the gateway IP, so existing behavior is unchanged.

Test plan

• go build ./...
• go test ./lib/egressproxy/...
• Unit tests for create/update validation, proxy-mode normalization, and block-flag mapping (new tests in create_egress_proxy_test.go, update_test.go)
• make oapi-generate (pinned v2.5.1; regen is deterministic — the HealthCheckHTTPScheme const rename is codegen collision-resolution churn from the new enum, and nothing references the old names)
• KVM-dependent integration tests (TestEgressProxyRewritesHTTPSHeaders, TestCreateInstanceWithNetwork) could not run in this environment — verified they fail identically on main here (VM boot / Docker Hub rate limits), so not regressions. Should run on a KVM-capable host before merge.
• End-to-end on a host: create instance with egress: {enabled: true, proxy: none, enforcement: {mode: all_traffic}}, verify direct TCP/UDP egress rejected, gateway-destined traffic allowed, PATCH toggling applies/removes rules live.

🤖 Generated with Claude Code

---

Note

High Risk
Changes host iptables egress enforcement and instance network policy APIs on security-sensitive paths; misconfiguration could block guest egress or leave rules inconsistent until rollback.

Overview
Adds network.egress.proxy (mitm default, none for TAP iptables enforcement only—no MITM process, guest proxy env, or CA) and enforcement.mode: all_traffic (blocks direct TCP and UDP, including QUIC/DNS). Host enforcement is refactored around ApplyEnforcement / RemoveEnforcement with optional UDP rules; proxy=none instances get rules without registering the proxy service, and teardown still clears iptables when the proxy never started.

PATCH /instances/{id} can replace egress for proxy=none only: validation rejects mitm create-time policies and switching to mitm on update; running instances apply or remove enforcement immediately with rollback if metadata save fails. Create/update validation normalizes proxy mode and requires credentials to use mitm.

OpenAPI and API mapping (toDomainNetworkEgress) wire create and update; docs describe the new modes and live update behavior.

^{Reviewed by Cursor Bugbot for commit 67806b6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

✱ Stainless preview builds for hypeman

This PR will update the hypeman SDKs with the following commit message.

feat: Add enforcement-only egress mode and live egress policy updates

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ hypeman-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/ec4fb66b3e526b3da526f2de8ad649b44a5cdd1c/dist.tar.gz

✅ hypeman-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

✅ hypeman-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@b502aca16796b7a5a13121e321d08bfd69e9def8

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-07-08 03:27:17 UTC

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 67806b6. Configure here.}

[cursor]

Enforcement-only create rollback leak

High Severity

With network.egress.proxy=none, maybeRegisterEgressProxy installs host iptables rules but returns a nil guest config, preventing cleanup registration. If instance creation or startup fails, these rules are not removed, leaving stale FORWARD rules on the host's TAP interface.

 

^{Reviewed by Cursor Bugbot for commit 67806b6. Configure here.}