Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

feat(egress): make policy persistence REQUIRED in the fast-sandbox profile

高然9c710c940dc2
diff --git a/components/egress/fastsandbox.go b/components/egress/fastsandbox.go
index 8fdfd6337..ea5f6b2c2 100644
--- a/components/egress/fastsandbox.go
+++ b/components/egress/fastsandbox.go
@@ -129,22 +129,24 @@ func runFastSandboxProfile(ctx context.Context, upstreamSpec *mitmproxy.Upstream
log.Infof("fast-sandbox vault persistence enabled at %s (one file per subject, atomic commit protocol)", vaultDir)
}
- // Policy persistence: per-subject policy files under
- // OPENSANDBOX_EGRESS_POLICY_DIR so an egress restart recovers the
- // recorded policy locally at SET_BINDING replay (the committed file
- // supersedes the replayed binding input) and the POLICY_EXPORT /
- // POLICY_IMPORT snapshot transfer can carry it across pause/resume.
- // Empty/unset keeps the policy memory-only. Fail fast on an unusable
- // directory: silently serving memory-only would break the acked ⇒
- // durable contract.
- if policyDir := strings.TrimSpace(os.Getenv(constants.EnvEgressPolicyDir)); policyDir != "" {
- pp, err := newPolicyPersistence(policyDir)
- if err != nil {
- log.Fatalf("fast-sandbox policy persistence: %v", err)
- }
- fastSandboxSrv.SetPolicyFiles(pp)
- log.Infof("fast-sandbox policy persistence enabled at %s (one file per subject, atomic commit protocol)", policyDir)
+ // Policy persistence: REQUIRED for the fast-sandbox profile. Per-subject
+ // policy files under OPENSANDBOX_EGRESS_POLICY_DIR make the recorded
+ // policy egress-held state — an egress restart recovers it locally at
+ // SET_BINDING replay (the committed file supersedes the replayed binding
+ // input) and the POLICY_EXPORT / POLICY_IMPORT snapshot transfer carries
+ // it across pause/resume. There is no memory-only posture: the binding
+ // input must never become a policy recovery source, so an unusable
+ // directory fails startup.
+ policyDir := strings.TrimSpace(os.Getenv(constants.EnvEgressPolicyDir))
+ if policyDir == "" {
+ log.Fatalf("fast-sandbox policy persistence: OPENSANDBOX_EGRESS_POLICY_DIR is required (the recorded policy is egress-held state)")
+ }
+ pp, err := newPolicyPersistence(policyDir)
+ if err != nil {
+ log.Fatalf("fast-sandbox policy persistence: %v", err)
}
+ fastSandboxSrv.SetPolicyFiles(pp)
+ log.Infof("fast-sandbox policy persistence enabled at %s (one file per subject, atomic commit protocol)", policyDir)
// Shared mitmproxy (OSEP-0022 A1): one mitmdump in the Pod netns serving
// every sandbox. Started BEFORE the HTTP listener so subjects can never
diff --git a/components/egress/fastsandbox_policy.go b/components/egress/fastsandbox_policy.go
index 9f2b154ed..080e81d4f 100644
--- a/components/egress/fastsandbox_policy.go
+++ b/components/egress/fastsandbox_policy.go
@@ -320,16 +320,6 @@ func (s *fastSandboxPolicyServer) putRelayPolicy(w http.ResponseWriter, r *http.
return nil
}
- if s.policyFiles == nil {
- // Memory-only (persistence disabled): direct commit.
- if err := apply(); err != nil {
- log.Errorf("subject %s: policy relay write failed: %v", subj, err)
- http.Error(w, "policy commit failure", http.StatusInternalServerError)
- return
- }
- writeJSON(w, putResponseStatus(created), doc)
- return
- }
payload, err := policy.EncodePolicyFile(fence.RuntimeInstanceID, fence.AttachmentID, newRev, raw)
if err != nil {
log.Errorf("subject %s: policy file encode failed: %v", subj, err)
@@ -418,15 +408,6 @@ func (s *fastSandboxPolicyServer) deleteRelayPolicy(w http.ResponseWriter, subj
return nil
}
- if s.policyFiles == nil {
- if err := apply(); err != nil {
- log.Errorf("subject %s: policy relay delete failed: %v", subj, err)
- http.Error(w, "policy commit failure", http.StatusInternalServerError)
- return
- }
- w.WriteHeader(http.StatusNoContent)
- return
- }
raw, err := json.Marshal(deny)
if err != nil {
http.Error(w, "policy persistence failure", http.StatusInternalServerError)
diff --git a/components/egress/fastsandbox_policy_persist.go b/components/egress/fastsandbox_policy_persist.go
index e27ea92ce..e211a39a8 100644
--- a/components/egress/fastsandbox_policy_persist.go
+++ b/components/egress/fastsandbox_policy_persist.go
@@ -186,13 +186,12 @@ func (s *fastSandboxPolicyServer) SetPolicyFiles(pp *policyPersistence) {
// other kind's directory could clobber its state (the rehydrate would then
// quarantine the corrupted file).
func (s *fastSandboxPolicyServer) reservesStatePath(path string) bool {
- if s.vaultFiles != nil && s.vaultFiles.reservesPath(path) {
+ // Policy persistence is required in this profile; vault persistence
+ // stays optional.
+ if s.policyFiles.reservesPath(path) {
return true
}
- if s.policyFiles != nil && s.policyFiles.reservesPath(path) {
- return true
- }
- return false
+ return s.vaultFiles != nil && s.vaultFiles.reservesPath(path)
}
// purgePolicyFile removes the subject's persisted policy (rebind or terminal
@@ -331,9 +330,6 @@ func (s *fastSandboxPolicyServer) clearPolicyRecord(subj subject.Subject) {
// a failed registration leaves the reloaded pending policy on a denying
// subject, which the Fastlet's retry converges.
func (s *fastSandboxPolicyServer) rehydratePolicyReload(subj subject.Subject, fence subject.Fencing) {
- if s.policyFiles == nil {
- return
- }
s.mu.Lock()
defer s.mu.Unlock()
if e := s.policies[subj]; e != nil {
@@ -434,7 +430,6 @@ func (s *fastSandboxPolicyServer) applyBindingPolicy(subj subject.Subject, fence
s.mu.Lock()
entry = nil
}
- pp := s.policyFiles
s.mu.Unlock()
if entry != nil {
log.Infof("subject %s: binding input superseded by the recorded policy (revision %d)", subj, entry.revision)
@@ -463,10 +458,6 @@ func (s *fastSandboxPolicyServer) applyBindingPolicy(subj subject.Subject, fence
s.mu.Unlock()
return nil
}
- if pp == nil {
- // Memory-only: direct commit.
- return apply()
- }
payload, err := policy.EncodePolicyFile(fence.RuntimeInstanceID, fence.AttachmentID, rev, raw)
if err != nil {
return fmt.Errorf("policy file encode: %w", err)
diff --git a/components/egress/fastsandbox_policy_persist_test.go b/components/egress/fastsandbox_policy_persist_test.go
index 78d09cb30..72ce10a8f 100644
--- a/components/egress/fastsandbox_policy_persist_test.go
+++ b/components/egress/fastsandbox_policy_persist_test.go
@@ -552,13 +552,22 @@ func TestPolicyPersistStaleRecordNeverSupersedesFreshRegistration(t *testing.T)
// ---------------------------------------------------------------------------
func TestPolicyPersistCapabilityFlag(t *testing.T) {
+ // Policy persistence is required in the profile: every server advertises
+ // the capability.
h := newPolicyPersistHarness(t)
status := mustStatus(t, h.srv)
assert.True(t, status.PolicyTransfer, "policy persistence configured: the Fastlet's transfer capability")
srv, _, _ := fastSandboxTestServer(t)
+ status = mustStatus(t, srv)
+ assert.True(t, status.PolicyTransfer)
+ assert.NotContains(t, mustStatusBodyJSON(t, srv), "policyRecovery", "healthy posture omits the recovery flag")
+}
+
+// mustStatusBodyJSON returns the raw actions status body.
+func mustStatusBodyJSON(t *testing.T, srv *fastSandboxPolicyServer) string {
+ t.Helper()
rec := doRequest(t, srv, http.MethodGet, constants.ActionsStatusPath, "")
require.Equal(t, http.StatusOK, rec.Code)
- assert.NotContains(t, rec.Body.String(), "policyTransfer", "the capability stays omitted when false")
- assert.NotContains(t, rec.Body.String(), "policyRecovery")
+ return rec.Body.String()
}
diff --git a/components/egress/fastsandbox_policy_snapshot.go b/components/egress/fastsandbox_policy_snapshot.go
index df75732e7..6ce9b7c87 100644
--- a/components/egress/fastsandbox_policy_snapshot.go
+++ b/components/egress/fastsandbox_policy_snapshot.go
@@ -62,9 +62,6 @@ var errPolicySnapshotTooLarge = fmt.Errorf("policy bundle file exceeds %d bytes"
// the copy plus the teardown purge would make uncertain bytes the only
// surviving recorded policy.
func (s *fastSandboxPolicyServer) applyPolicyExport(env *actionhandler.Envelope) (int, error) {
- if s.policyFiles == nil {
- return http.StatusInternalServerError, errors.New("policy export requires policy persistence (OPENSANDBOX_EGRESS_POLICY_DIR)")
- }
subj := subject.FromSandboxUID(env.Sandbox.UID)
fence := subject.FromRevision(env)
target := strings.TrimSpace(env.Snapshot.Path)
@@ -224,9 +221,6 @@ func (s *fastSandboxPolicyServer) policyExportSourceImageLocked(subj subject.Sub
// fence, the policy installs into the live record and a rejected bundle is
// a 400 with last-good kept.
func (s *fastSandboxPolicyServer) applyPolicyImport(env *actionhandler.Envelope) (int, error) {
- if s.policyFiles == nil {
- return http.StatusInternalServerError, errors.New("policy import requires policy persistence (OPENSANDBOX_EGRESS_POLICY_DIR)")
- }
subj := subject.FromSandboxUID(env.Sandbox.UID)
fence := subject.FromRevision(env)
source := strings.TrimSpace(env.Snapshot.Path)
diff --git a/components/egress/fastsandbox_policy_snapshot_test.go b/components/egress/fastsandbox_policy_snapshot_test.go
index 21a938bd2..d7bc9c84f 100644
--- a/components/egress/fastsandbox_policy_snapshot_test.go
+++ b/components/egress/fastsandbox_policy_snapshot_test.go
@@ -98,14 +98,6 @@ func TestPolicySnapshotExportUnregisteredSubjectIsNoOp(t *testing.T) {
}
func TestPolicySnapshotExportGuards(t *testing.T) {
- t.Run("persistence disabled", func(t *testing.T) {
- srv, reg, _ := fastSandboxTestServer(t)
- setBindingAndReady(t, srv, reg, policyTestUID, vaultTestIP, strPtr(policyAllow()))
- rec := doAction(t, srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", "/tmp/bundle.json"))
- assert.Equal(t, http.StatusInternalServerError, rec.Code)
- rec = doAction(t, srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_IMPORT", "/tmp/bundle.json"))
- assert.Equal(t, http.StatusInternalServerError, rec.Code)
- })
t.Run("stale fence", func(t *testing.T) {
h := newPolicyPersistHarness(t)
h.readySubject(t, policyTestUID, vaultTestIP)
diff --git a/components/egress/fastsandbox_server_test.go b/components/egress/fastsandbox_server_test.go
index 5bc32f26c..cb1370bd9 100644
--- a/components/egress/fastsandbox_server_test.go
+++ b/components/egress/fastsandbox_server_test.go
@@ -95,9 +95,45 @@ func fastSandboxTestServer(t *testing.T) (*fastSandboxPolicyServer, *subject.Mem
// no-op the gateway DNS redirect (no iptables/nft in unit tests)
srv.dnsRedirectInstall = func(netip.Addr, int) error { return nil }
srv.dnsRedirectRemove = func() error { return nil }
+ // Policy persistence is REQUIRED in the fast-sandbox profile — every
+ // test server carries a store, mirroring the production posture (no
+ // memory-only mode). The file seam defaults to a cross-platform fake
+ // keyed by path (the atomic machinery itself is Linux-only); tests that
+ // need real files or outcome injection build their own harness.
+ pp, err := newPolicyPersistence(t.TempDir())
+ require.NoError(t, err)
+ files := make(map[string]*fakeVaultFile)
+ pp.newFile = func(path string) (vaultFileStore, error) {
+ f, ok := files[path]
+ if !ok {
+ f = newFakeVaultFile(path)
+ files[path] = f
+ }
+ return f, nil
+ }
+ srv.SetPolicyFiles(pp)
return srv, reg, nft
}
+// wireTestPolicyPersistence attaches the required temp-dir-backed policy
+// persistence to a server constructed directly (bypassing
+// fastSandboxTestServer).
+func wireTestPolicyPersistence(t *testing.T, srv *fastSandboxPolicyServer) {
+ t.Helper()
+ pp, err := newPolicyPersistence(t.TempDir())
+ require.NoError(t, err)
+ files := make(map[string]*fakeVaultFile)
+ pp.newFile = func(path string) (vaultFileStore, error) {
+ f, ok := files[path]
+ if !ok {
+ f = newFakeVaultFile(path)
+ files[path] = f
+ }
+ return f, nil
+ }
+ srv.SetPolicyFiles(pp)
+}
+
func doRequest(t *testing.T, srv *fastSandboxPolicyServer, method, path, body string) *httptest.ResponseRecorder {
t.Helper()
var rd *bytes.Reader
@@ -627,6 +663,7 @@ func TestActionsSetBindingTakeoverGatewayRefcountConsistent(t *testing.T) {
reg := subject.NewRegistry(nil, nil)
nft := &fakeNft{}
srv := newFastSandboxPolicyServer(context.Background(), reg, nft)
+ wireTestPolicyPersistence(t, srv)
var installs, removes int
srv.dnsRedirectInstall = func(netip.Addr, int) error { installs++; return nil }
srv.dnsRedirectRemove = func() error { removes++; return nil }
@@ -1022,6 +1059,7 @@ func TestFastSandboxServerAlwaysRulesReachNft(t *testing.T) {
reg := subject.NewRegistry([]policy.EgressRule{alwaysDeny}, []policy.EgressRule{alwaysAllow})
nft := &fakeNft{}
srv := newFastSandboxPolicyServer(context.Background(), reg, nft)
+ wireTestPolicyPersistence(t, srv)
srv.dnsRedirectInstall = func(netip.Addr, int) error { return nil }
srv.dnsRedirectRemove = func() error { return nil }
@@ -1089,6 +1127,7 @@ func TestFastSandboxServerGatewayRedirectRefcounted(t *testing.T) {
reg := subject.NewRegistry(nil, nil)
nft := &fakeNft{}
srv := newFastSandboxPolicyServer(context.Background(), reg, nft)
+ wireTestPolicyPersistence(t, srv)
var installs, removes int
srv.dnsRedirectInstall = func(netip.Addr, int) error { installs++; return nil }
srv.dnsRedirectRemove = func() error { removes++; return nil }
@@ -1218,6 +1257,7 @@ func TestFastSandboxServerGatewayRedirectDuplicateSetBindingIdempotent(t *testin
reg := subject.NewRegistry(nil, nil)
nft := &fakeNft{}
srv := newFastSandboxPolicyServer(context.Background(), reg, nft)
+ wireTestPolicyPersistence(t, srv)
var installs, removes int
srv.dnsRedirectInstall = func(netip.Addr, int) error { installs++; return nil }
srv.dnsRedirectRemove = func() error { removes++; return nil }
@@ -1238,6 +1278,7 @@ func TestFastSandboxServerGatewayRedirectRebindMovesGateway(t *testing.T) {
reg := subject.NewRegistry(nil, nil)
nft := &fakeNft{}
srv := newFastSandboxPolicyServer(context.Background(), reg, nft)
+ wireTestPolicyPersistence(t, srv)
var installs, removes int
srv.dnsRedirectInstall = func(netip.Addr, int) error { installs++; return nil }
srv.dnsRedirectRemove = func() error { removes++; return nil }
diff --git a/components/egress/pkg/constants/configuration.go b/components/egress/pkg/constants/configuration.go
index 0cbacd161..bc498d69d 100644
--- a/components/egress/pkg/constants/configuration.go
+++ b/components/egress/pkg/constants/configuration.go
@@ -77,9 +77,10 @@ const (
// vault files on the Pod-scoped emptyDir volume. Empty/unset keeps the vault
// memory-only; the sidecar profile never persists.
//
-// EnvEgressPolicyDir (fast-sandbox profile): directory for the per-subject
-// policy files with the same semantics. Persistence is required for the
-// POLICY_EXPORT / POLICY_IMPORT snapshot transfer.
+// EnvEgressPolicyDir (fast-sandbox profile): REQUIRED — directory for the
+// per-subject policy files. The recorded policy is egress-held state; there
+// is no memory-only posture (the profile fails startup without it), so the
+// binding input never becomes a policy recovery source.
const (
EnvEgressVaultDir = "OPENSANDBOX_EGRESS_VAULT_DIR"
EnvEgressPolicyDir = "OPENSANDBOX_EGRESS_POLICY_DIR"
diff --git a/components/egress/tests/smoke-fast-sandbox.sh b/components/egress/tests/smoke-fast-sandbox.sh
index 9267c899c..b620d3ec8 100755
--- a/components/egress/tests/smoke-fast-sandbox.sh
+++ b/components/egress/tests/smoke-fast-sandbox.sh
@@ -66,6 +66,12 @@ HOSTS_BACKUP=""
VAULT_DIR=""
VAULT_BODY=""
+# Per-subject policy files (egress-held policy): REQUIRED by the fast-sandbox
+# profile — the recorded policy is egress-held state, so a fresh directory
+# per run keeps the seeding assertions meaningful while surviving the in-run
+# restarts (Test 9/14 durability).
+POLICY_DIR=""
+
info() { echo "[$(date +%H:%M:%S)] $*"; }
pass() { info "PASS: $*"; }
fail() { echo "FAIL: $*" >&2; exit 1; }
@@ -104,6 +110,7 @@ cleanup() {
[ -n "${SSL_DIR:-}" ] && rm -rf "${SSL_DIR}" 2>/dev/null
[ -n "${CA_SEED_DIR}" ] && rm -rf "${CA_SEED_DIR}" 2>/dev/null
[ -n "${VAULT_DIR}" ] && rm -rf "${VAULT_DIR}" 2>/dev/null
+ [ -n "${POLICY_DIR}" ] && rm -rf "${POLICY_DIR}" 2>/dev/null
[ -n "${VAULT_BODY}" ] && rm -f "${VAULT_BODY}" 2>/dev/null
nft delete table inet opensandbox-fast-sandbox 2>/dev/null
}
@@ -272,6 +279,7 @@ start_egress() {
OPENSANDBOX_EGRESS_BLOCK_DOH_443="${block_doh}" \
OPENSANDBOX_EGRESS_DOH_BLOCKLIST="${doh_blocklist}" \
OPENSANDBOX_EGRESS_VAULT_DIR="${VAULT_DIR}" \
+ OPENSANDBOX_EGRESS_POLICY_DIR="${POLICY_DIR}" \
"${mitm_env[@]}" \
"${upstream_env[@]}" \
"${EGRESS_BIN}" >"${EGRESS_LOG}" 2>&1 &
@@ -338,6 +346,7 @@ printf '%s\n' '10.99.0.9' > "${ALWAYS_RULES_DIR}/deny.always"
# writes run the commit protocol and the ack means durable (exercised by the
# Test 14 restart reload).
VAULT_DIR="$(mktemp -d -t fast-sandbox-vault.XXXXXX)"
+POLICY_DIR="$(mktemp -d -t fast-sandbox-policy.XXXXXX)"
VAULT_BODY="$(mktemp -t fast-sandbox-vault-body.XXXXXX)"
info "Building egress binary"
@@ -1014,6 +1023,9 @@ else
# credential while a keeps a separate one.
VB_BODY='{"credentials":[{"name":"smoke-b-token","source":{"type":"inline","value":"smoke-b-secret"}}],"bindings":[{"name":"ext-bearer","match":{"hosts":["ext.test"],"schemes":["http"],"paths":["/private*"]},"auth":{"type":"bearer","credential":"smoke-b-token"}}]}'
set_binding b 10.10.0.6 3 runtime-b att-b "${VAULT_POLICY_B}"
+ # b's record survived the restarts (MITM section) and supersedes the
+ # binding input — the vault validation policy rides the relay.
+ relay_put_policy b "${VAULT_POLICY_B}"
code="$(vault_relay b POST "${VB_BODY}")"
[ "${code}" = "201" ] || fail "relay POST must accept a denying subject (pending-policy validation), got ${code}: $(cat "${VAULT_BODY}")"
lifecycle_hook b runtime-b att-b sandbox.runtime-ready