Skip to content

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

feat(egress): add strict FastSandbox Actions v2 receiver

lihaopengba9d4167a7bc
diff --git a/components/egress/fastsandbox.go b/components/egress/fastsandbox.go
index 145aa5514..ad2aa6338 100644
--- a/components/egress/fastsandbox.go
+++ b/components/egress/fastsandbox.go
@@ -67,6 +67,10 @@ import (
// on the shared dnsproxy.
func runFastSandboxProfile(ctx context.Context, upstreamSpec *mitmproxy.UpstreamProxySpec) {
log.Infof("egress profile: fast-sandbox (multi-sandbox control plane)")
+ actionsAPIVersion, err := constants.ParseFastSandboxActionsAPIVersion(os.Getenv(constants.EnvFastSandboxActionsAPIVersion))
+ if err != nil {
+ log.Fatalf("fast-sandbox Actions protocol: %v", err)
+ }
otelShutdown, err := telemetry.Init(ctx)
if err != nil {
@@ -115,6 +119,7 @@ func runFastSandboxProfile(ctx context.Context, upstreamSpec *mitmproxy.Upstream
reg := subject.NewRegistry(alwaysDeny, alwaysAllow)
fastSandboxSrv := newFastSandboxPolicyServer(ctx, reg, podNft)
+ fastSandboxSrv.SetActionsAPIVersion(actionsAPIVersion)
// Register the configured state-directory basenames BEFORE either
// constructor runs: the volume-root restriction must recognize the
diff --git a/components/egress/fastsandbox_actions.go b/components/egress/fastsandbox_actions.go
index 8c1255374..0a3c48170 100644
--- a/components/egress/fastsandbox_actions.go
+++ b/components/egress/fastsandbox_actions.go
@@ -53,11 +53,14 @@ package main
import (
"context"
"crypto/rand"
+ "encoding/base64"
"encoding/hex"
+ "encoding/json"
"fmt"
"io"
"net/http"
"os"
+ "strings"
"time"
"github.com/alibaba/opensandbox/egress/pkg/actionhandler"
@@ -93,6 +96,10 @@ func (s *fastSandboxPolicyServer) handleActionsStatus(w http.ResponseWriter, r *
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
+ writeJSON(w, http.StatusOK, s.actionStatusResponse())
+}
+
+func (s *fastSandboxPolicyServer) actionStatusResponse() actionhandler.StatusResponse {
recovery := s.vaultRecoveryActive()
policyRecovery := s.policyRecoveryActive()
degraded := s.degradedVaultUIDs()
@@ -128,6 +135,18 @@ func (s *fastSandboxPolicyServer) handleActionsStatus(w http.ResponseWriter, r *
resp.MitmCaError = reason
}
}
+ return resp
+}
+
+func (s *fastSandboxPolicyServer) handleActionsV2Status(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet {
+ w.Header().Set("Allow", http.MethodGet)
+ http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+ return
+ }
+ resp := s.actionStatusResponse()
+ resp.APIVersion = constants.ActionsAPIVersionV2
+ resp.OwnerStatus = true
writeJSON(w, http.StatusOK, resp)
}
@@ -159,6 +178,215 @@ func (s *fastSandboxPolicyServer) handleActions(w http.ResponseWriter, r *http.R
writeJSON(w, http.StatusOK, struct{}{})
}
+func (s *fastSandboxPolicyServer) handleActionsV2(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost {
+ w.Header().Set("Allow", http.MethodPost)
+ http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+ return
+ }
+ body, err := io.ReadAll(io.LimitReader(r.Body, maxPolicyBodyBytes))
+ if err != nil {
+ http.Error(w, fmt.Sprintf("failed to read action body: %v", err), http.StatusBadRequest)
+ return
+ }
+ env, err := actionhandler.ParseEnvelopeV2(body)
+ if err != nil {
+ http.Error(w, fmt.Sprintf("invalid Actions v2 envelope: %v", err), http.StatusBadRequest)
+ return
+ }
+ subj := subject.FromSandboxUID(env.Sandbox.UID)
+ ownerLock := s.ownerLock(subj)
+ ownerLock.Lock()
+ defer ownerLock.Unlock()
+ if err := s.validateActionsV2Owner(subj, env); err != nil {
+ http.Error(w, err.Error(), http.StatusConflict)
+ return
+ }
+ switch env.Operation {
+ case actionhandler.OperationSetBinding, actionhandler.OperationLifecycleHook, actionhandler.OperationRemoveBinding:
+ default:
+ http.Error(w, "snapshot and state-transfer operations are not supported by Actions v2", http.StatusNotImplemented)
+ return
+ }
+ status, err := s.dispatchAction(r.Context(), env)
+ if err != nil {
+ logEgressUpdateFailedError(fmt.Sprintf("Actions v2 %s for sandbox %s failed: %v", env.Operation, env.Sandbox.UID, err))
+ http.Error(w, err.Error(), status)
+ return
+ }
+ s.mu.Lock()
+ switch env.Operation {
+ case actionhandler.OperationSetBinding:
+ s.actionOwners[subj] = *env.Owner
+ case actionhandler.OperationRemoveBinding:
+ if current, ok := s.actionOwners[subj]; ok && current.Matches(*env.Owner) {
+ delete(s.actionOwners, subj)
+ }
+ }
+ s.mu.Unlock()
+ writeJSON(w, http.StatusOK, struct{}{})
+}
+
+func (s *fastSandboxPolicyServer) validateActionsV2Owner(subj subject.Subject, env *actionhandler.Envelope) error {
+ if env.Owner == nil || !env.Owner.Valid() || env.Owner.SandboxUID != env.Sandbox.UID ||
+ env.Owner.RuntimeInstanceID != env.Revision.RuntimeInstanceID || env.Owner.AttachmentID != env.Revision.AttachmentID ||
+ uint64(env.Owner.RouteGeneration) != env.Revision.RouteGeneration {
+ return fmt.Errorf("Actions v2 owner does not match the Sandbox revision")
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ current, found := s.actionOwners[subj]
+ if !found {
+ if env.Operation != actionhandler.OperationSetBinding {
+ return fmt.Errorf("Actions v2 owner is not registered")
+ }
+ return nil
+ }
+ if current.Matches(*env.Owner) {
+ return nil
+ }
+ return fmt.Errorf("Actions v2 owner mismatch")
+}
+
+func (s *fastSandboxPolicyServer) handleActionsV2Owner(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet {
+ w.Header().Set("Allow", http.MethodGet)
+ http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+ return
+ }
+ uid := strings.TrimPrefix(r.URL.Path, constants.ActionsV2OwnerPathPrefix)
+ owner, err := ownerFromRequest(r)
+ if !validVaultSubjectID(uid) || err != nil || owner.SandboxUID != uid {
+ http.Error(w, "a valid owner matching the Sandbox UID is required", http.StatusBadRequest)
+ return
+ }
+ ownerLock := s.ownerLock(subject.FromSandboxUID(uid))
+ ownerLock.RLock()
+ defer ownerLock.RUnlock()
+ release, err := s.acquireAction(r.Context())
+ if err != nil {
+ http.Error(w, "owner observation canceled", http.StatusServiceUnavailable)
+ return
+ }
+ defer release()
+ subj := subject.FromSandboxUID(uid)
+ s.mu.Lock()
+ current, ownerFound := s.actionOwners[subj]
+ residual := s.subjectHasLiveStateLocked(subj)
+ s.mu.Unlock()
+ regFence, registered := s.reg.Fence(subj)
+ if ownerFound {
+ if !current.Matches(owner) {
+ http.Error(w, "owner status is unknown or belongs to another owner", http.StatusConflict)
+ return
+ }
+ if registered {
+ if !regFence.Matches(subject.Fencing{RuntimeInstanceID: owner.RuntimeInstanceID, AttachmentID: owner.AttachmentID}) {
+ http.Error(w, "registered fence disagrees with the Actions v2 owner", http.StatusConflict)
+ return
+ }
+ writeJSON(w, http.StatusOK, actionhandler.OwnerObservation{State: "current", Owner: owner})
+ return
+ }
+ }
+ if registered || residual {
+ http.Error(w, "owner status is unknown; residual subject state exists", http.StatusConflict)
+ return
+ }
+ residual, err = s.subjectHasPersistentState(subj)
+ if err != nil || residual {
+ http.Error(w, "owner retirement cannot be confirmed", http.StatusServiceUnavailable)
+ return
+ }
+ if ownerFound {
+ s.mu.Lock()
+ if currentOwner, ok := s.actionOwners[subj]; ok && currentOwner.Matches(owner) {
+ delete(s.actionOwners, subj)
+ }
+ s.mu.Unlock()
+ }
+ writeJSON(w, http.StatusOK, actionhandler.OwnerObservation{State: "retired", Owner: owner})
+}
+
+func (s *fastSandboxPolicyServer) subjectHasLiveStateLocked(subj subject.Subject) bool {
+ _, rebind := s.rebinds[subj]
+ _, vault := s.vaults[subj]
+ _, policy := s.policies[subj]
+ _, pending := s.pendingPolicies[subj]
+ _, attachment := s.subjAtt[subj]
+ _, fence := s.subjFence[subj]
+ return rebind || vault || policy || pending || attachment || fence
+}
+
+func (s *fastSandboxPolicyServer) subjectHasPersistentState(subj subject.Subject) (bool, error) {
+ if s.vaultFiles != nil {
+ fs, err := s.vaultFiles.storeFor(subj)
+ if err != nil {
+ return false, err
+ }
+ snapshot, err := fs.Snapshot()
+ if err != nil {
+ return false, err
+ }
+ if snapshot.Exists() || s.vaultFiles.isSealed(subj) {
+ return true, nil
+ }
+ }
+ if s.policyFiles != nil {
+ fs, err := s.policyFiles.storeFor(subj)
+ if err != nil {
+ return false, err
+ }
+ snapshot, err := fs.Snapshot()
+ if err != nil {
+ return false, err
+ }
+ if snapshot.Exists() || s.policyFiles.isSealed(subj) {
+ return true, nil
+ }
+ }
+ return false, nil
+}
+
+func ownerFromRequest(r *http.Request) (actionhandler.Owner, error) {
+ encoded := strings.TrimSpace(r.Header.Get(constants.EgressActionsOwnerHeader))
+ if encoded == "" {
+ return actionhandler.Owner{}, fmt.Errorf("owner header is required")
+ }
+ decoded, err := base64.RawURLEncoding.DecodeString(encoded)
+ if err != nil {
+ return actionhandler.Owner{}, err
+ }
+ var owner actionhandler.Owner
+ if err := json.Unmarshal(decoded, &owner); err != nil {
+ return owner, err
+ }
+ if !owner.Valid() || strings.TrimSpace(r.Header.Get(constants.EgressActionsSandboxUIDHeader)) != owner.SandboxUID {
+ return owner, fmt.Errorf("owner header is incomplete or disagrees with Sandbox UID header")
+ }
+ return owner, nil
+}
+
+func (s *fastSandboxPolicyServer) validateRelayOwner(w http.ResponseWriter, r *http.Request, uid string) bool {
+ if s.actionsAPIVersion != constants.ActionsAPIVersionV2 {
+ return true
+ }
+ owner, err := ownerFromRequest(r)
+ if err != nil || owner.SandboxUID != uid {
+ http.Error(w, "relay owner must match the path Sandbox UID", http.StatusBadRequest)
+ return false
+ }
+ subj := subject.FromSandboxUID(uid)
+ s.mu.Lock()
+ current, found := s.actionOwners[subj]
+ s.mu.Unlock()
+ if !found || !current.Matches(owner) {
+ http.Error(w, "relay owner is not the current registered owner", http.StatusPreconditionFailed)
+ return false
+ }
+ return true
+}
+
// dispatchAction validates effect-free input before entering the cancellable
// action gate. Every runtime registry writer is reached through this gate;
// snapshot transfers retain their own Vault transaction/guard semantics.
diff --git a/components/egress/fastsandbox_actions_v2_test.go b/components/egress/fastsandbox_actions_v2_test.go
new file mode 100644
index 000000000..25b9a1a72
--- /dev/null
+++ b/components/egress/fastsandbox_actions_v2_test.go
@@ -0,0 +1,200 @@
+package main
+
+import (
+ "encoding/base64"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "net/netip"
+ "strings"
+ "testing"
+
+ "github.com/alibaba/opensandbox/egress/pkg/actionhandler"
+ "github.com/alibaba/opensandbox/egress/pkg/constants"
+ "github.com/alibaba/opensandbox/egress/pkg/subject"
+ "github.com/stretchr/testify/require"
+)
+
+func actionsV2Owner(uid, runtimeID, attachmentID string, generation int64) actionhandler.Owner {
+ return actionhandler.Owner{
+ SandboxUID: uid, FastletPodUID: "fastlet-pod", RuntimeInstanceID: runtimeID,
+ InstanceGeneration: generation, AssignmentAttempt: 1, RouteGeneration: 1, AttachmentID: attachmentID,
+ }
+}
+
+func actionsV2Body(t *testing.T, operation actionhandler.Operation, owner actionhandler.Owner, input *string) string {
+ t.Helper()
+ env := actionhandler.Envelope{
+ APIVersion: actionhandler.APIVersionV2, Operation: operation, InvocationID: "v2-test",
+ Sandbox: actionhandler.SandboxRef{UID: owner.SandboxUID}, Owner: &owner,
+ Revision: actionhandler.Revision{SpecGeneration: 1, RuntimeInstanceID: owner.RuntimeInstanceID, AttachmentID: owner.AttachmentID, RouteGeneration: uint64(owner.RouteGeneration)},
+ }
+ if operation == actionhandler.OperationSetBinding {
+ env.Attachment = testAttachment()
+ if owner.SandboxUID == "b" {
+ env.Attachment.Network.IP = netip.MustParseAddr("10.0.0.6")
+ }
+ if input == nil {
+ null := []byte("null")
+ env.Binding = &actionhandler.Binding{Input: null}
+ } else {
+ encoded, err := json.Marshal(*input)
+ require.NoError(t, err)
+ env.Binding = &actionhandler.Binding{Input: encoded}
+ }
+ }
+ if operation == actionhandler.OperationLifecycleHook {
+ env.Hook = &actionhandler.Hook{Name: actionhandler.HookDataPlaneReady, Sequence: 2}
+ }
+ encoded, err := json.Marshal(env)
+ require.NoError(t, err)
+ return string(encoded)
+}
+
+func doActionsV2(t *testing.T, srv *fastSandboxPolicyServer, body string) *httptest.ResponseRecorder {
+ t.Helper()
+ return doRequest(t, srv, http.MethodPost, constants.ActionsV2DispatchPath, body)
+}
+
+func doActionsV2Relay(t *testing.T, srv *fastSandboxPolicyServer, method, path string, owner actionhandler.Owner, body string) *httptest.ResponseRecorder {
+ t.Helper()
+ req := httptest.NewRequest(method, path, strings.NewReader(body))
+ encoded, err := json.Marshal(owner)
+ require.NoError(t, err)
+ req.Header.Set(constants.EgressActionsOwnerHeader, base64.RawURLEncoding.EncodeToString(encoded))
+ req.Header.Set(constants.EgressActionsSandboxUIDHeader, owner.SandboxUID)
+ rec := httptest.NewRecorder()
+ srv.Handler().ServeHTTP(rec, req)
+ return rec
+}
+
+func TestActionsV2IsOptInAndDoesNotMountLegacyMutationRoutes(t *testing.T) {
+ srv, _, _ := fastSandboxTestServer(t)
+ legacy := srv.Handler()
+ for _, path := range []string{constants.ActionsV2StatusPath, constants.ActionsV2DispatchPath, constants.ActionsV2VaultRelayPathPrefix + "a"} {
+ rec := httptest.NewRecorder()
+ legacy.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))
+ require.Equal(t, http.StatusNotFound, rec.Code, path)
+ }
+
+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ strict := srv.Handler()
+ for _, path := range []string{constants.ActionsStatusPath, constants.ActionsDispatchPath, constants.VaultRelayPathPrefix + "a"} {
+ rec := httptest.NewRecorder()
+ strict.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))
+ require.Equal(t, http.StatusNotFound, rec.Code, path)
+ }
+ status := httptest.NewRecorder()
+ strict.ServeHTTP(status, httptest.NewRequest(http.MethodGet, constants.ActionsV2StatusPath, nil))
+ require.Equal(t, http.StatusOK, status.Code)
+ var response actionhandler.StatusResponse
+ require.NoError(t, json.Unmarshal(status.Body.Bytes(), &response))
+ require.Equal(t, actionhandler.APIVersionV2, response.APIVersion)
+ require.True(t, response.OwnerStatus)
+}
+
+func TestActionsV2SeparatesSubjectsAndFencesOwnerChanges(t *testing.T) {
+ srv, reg, nft := fastSandboxTestServer(t)
+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ policyInput := vaultAllowPolicy()
+ a := actionsV2Owner("a", "runtime-a", "attachment-a", 1)
+ b := actionsV2Owner("b", "runtime-b", "attachment-b", 1)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, a, policyInput)).Code)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, b, policyInput)).Code)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationLifecycleHook, a, nil)).Code)
+
+ subjA, subjB := subject.FromSandboxUID("a"), subject.FromSandboxUID("b")
+ beforeDeny, beforePolicy := len(nft.denyFirst), len(nft.policyApplied)
+ newOwnerA := actionsV2Owner("a", "runtime-a2", "attachment-a2", 2)
+ require.Equal(t, http.StatusConflict, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, newOwnerA, policyInput)).Code,
+ "a replacement owner must first retire the old exact owner")
+ require.Len(t, nft.denyFirst, beforeDeny)
+ require.Len(t, nft.policyApplied, beforePolicy)
+
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationRemoveBinding, a, nil)).Code)
+ _, foundA := reg.Fence(subjA)
+ _, foundB := reg.Fence(subjB)
+ require.False(t, foundA)
+ require.True(t, foundB, "retiring subject A must not affect B")
+ srv.mu.Lock()
+ gotB, foundB := srv.actionOwners[subjB]
+ srv.mu.Unlock()
+ require.True(t, foundB)
+ require.True(t, gotB.Matches(b))
+
+ newOwnerABody := actionsV2Body(t, actionhandler.OperationSetBinding, newOwnerA, policyInput)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, newOwnerABody).Code)
+}
+
+func TestActionsV2RejectsSnapshotAndRelayPathOwnerMismatchBeforeEffects(t *testing.T) {
+ srv, reg, nft := fastSandboxTestServer(t)
+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ owner := actionsV2Owner("a", "runtime-a", "attachment-a", 1)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, owner, vaultAllowPolicy())).Code)
+ fenceBefore, registeredBefore := reg.Fence(subject.FromSandboxUID("a"))
+ require.True(t, registeredBefore)
+ beforeDeny := len(nft.denyFirst)
+ snapshot, err := json.Marshal(actionhandler.Envelope{
+ APIVersion: actionhandler.APIVersionV2, Operation: actionhandler.OperationVaultExport, InvocationID: "snap",
+ Sandbox: actionhandler.SandboxRef{UID: "a"}, Revision: actionhandler.Revision{SpecGeneration: 1, RuntimeInstanceID: owner.RuntimeInstanceID, AttachmentID: owner.AttachmentID, RouteGeneration: 1},
+ Owner: &owner, Snapshot: &actionhandler.SnapshotTransfer{Path: "/tmp/state"},
+ })
+ require.NoError(t, err)
+ require.Equal(t, http.StatusNotImplemented, doActionsV2(t, srv, string(snapshot)).Code)
+ fenceAfter, registered := reg.Fence(subject.FromSandboxUID("a"))
+ require.True(t, registered)
+ require.True(t, fenceBefore.Matches(fenceAfter))
+ require.Len(t, nft.denyFirst, beforeDeny)
+
+ other := actionsV2Owner("b", "runtime-b", "attachment-b", 1)
+ rec := doActionsV2Relay(t, srv, http.MethodGet, constants.ActionsV2VaultRelayPathPrefix+"b", owner, "")
+ require.Equal(t, http.StatusBadRequest, rec.Code)
+ _, registered = reg.Fence(subject.FromSandboxUID("b"))
+ require.False(t, registered)
+ require.NotEqual(t, owner.SandboxUID, other.SandboxUID)
+}
+
+func TestActionsV2CarriesOwnerThroughVaultAndPolicyRelayCRUD(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ input := vaultAllowPolicy()
+ ownerA := actionsV2Owner("a", "runtime-a", "attachment-a", 1)
+ ownerB := actionsV2Owner("b", "runtime-b", "attachment-b", 1)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, ownerA, input)).Code)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationLifecycleHook, ownerA, nil)).Code)
+
+ created := doActionsV2Relay(t, srv, http.MethodPost, constants.ActionsV2VaultRelayPathPrefix+"a", ownerA, vaultCredential())
+ require.Equal(t, http.StatusCreated, created.Code, created.Body.String())
+ readVault := doActionsV2Relay(t, srv, http.MethodGet, constants.ActionsV2VaultRelayPathPrefix+"a", ownerA, "")
+ require.Equal(t, http.StatusOK, readVault.Code, readVault.Body.String())
+ require.Contains(t, readVault.Body.String(), `"name":"tok"`)
+
+ readPolicy := doActionsV2Relay(t, srv, http.MethodGet, constants.ActionsV2PolicyRelayPathPrefix+"a", ownerA, "")
+ require.Equal(t, http.StatusOK, readPolicy.Code, readPolicy.Body.String())
+ revision, current := mustPolicyRevision(t, readPolicy)
+ require.EqualValues(t, 1, revision)
+ updated := doActionsV2Relay(t, srv, http.MethodPut, constants.ActionsV2PolicyRelayPathPrefix+"a", ownerA,
+ policyPutDoc(policyAllowAlt(), revision, true, false))
+ require.Equal(t, http.StatusOK, updated.Code, updated.Body.String())
+ require.Contains(t, updated.Body.String(), "other.example.com")
+ _ = current
+
+ deleted := doActionsV2Relay(t, srv, http.MethodDelete, constants.ActionsV2VaultRelayPathPrefix+"a", ownerA, "")
+ require.Equal(t, http.StatusNoContent, deleted.Code, deleted.Body.String())
+
+ // A different, unbound Sandbox cannot use A's shared management routes.
+ for _, request := range []struct {
+ method string
+ path string
+ body string
+ }{
+ {http.MethodGet, constants.ActionsV2VaultRelayPathPrefix + "b", ""},
+ {http.MethodPost, constants.ActionsV2VaultRelayPathPrefix + "b", vaultCredential()},
+ {http.MethodGet, constants.ActionsV2PolicyRelayPathPrefix + "b", ""},
+ } {
+ rec := doActionsV2Relay(t, srv, request.method, request.path, ownerB, request.body)
+ require.Equal(t, http.StatusPreconditionFailed, rec.Code, rec.Body.String())
+ }
+ _, found := reg.Fence(subject.FromSandboxUID("b"))
+ require.False(t, found, "relay must not materialize an unbound subject")
+}
diff --git a/components/egress/fastsandbox_policy.go b/components/egress/fastsandbox_policy.go
index 7a3c0f9fd..9ad078b8c 100644
--- a/components/egress/fastsandbox_policy.go
+++ b/components/egress/fastsandbox_policy.go
@@ -66,11 +66,23 @@ const maxPolicyRelayBodyBytes = policy.MaxPolicyBodyBytes + 1<<10
// handlePolicyRelay serves /policy/{sandboxUid} for all relay verbs.
func (s *fastSandboxPolicyServer) handlePolicyRelay(w http.ResponseWriter, r *http.Request) {
- uid := strings.TrimPrefix(r.URL.Path, constants.PolicyRelayPathPrefix)
+ prefix := constants.PolicyRelayPathPrefix
+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {
+ prefix = constants.ActionsV2PolicyRelayPathPrefix
+ }
+ uid := strings.TrimPrefix(r.URL.Path, prefix)
if !validVaultSubjectID(uid) {
http.Error(w, "missing or invalid sandbox uid in path", http.StatusBadRequest)
return
}
+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {
+ ownerLock := s.ownerLock(subject.FromSandboxUID(uid))
+ ownerLock.RLock()
+ defer ownerLock.RUnlock()
+ }
+ if !s.validateRelayOwner(w, r, uid) {
+ return
+ }
subj := subject.FromSandboxUID(uid)
switch r.Method {
case http.MethodGet:
diff --git a/components/egress/fastsandbox_server.go b/components/egress/fastsandbox_server.go
index 6256a84c7..f2e892f9a 100644
--- a/components/egress/fastsandbox_server.go
+++ b/components/egress/fastsandbox_server.go
@@ -25,6 +25,7 @@ package main
import (
"context"
"fmt"
+ "hash/crc32"
"net/http"
"net/netip"
"strings"
@@ -135,27 +136,46 @@ type fastSandboxPolicyServer struct {
// makes the Fastlet invalidate Binding readiness and replay SET_BINDING
// followed by the reached Hooks (restart recovery).
instanceID string
+ // actionsAPIVersion is one protocol for the whole shared Fastlet domain.
+ // V2 is explicit and default-off; in that mode v1 action and relay routes
+ // are not mounted, so older senders fail closed.
+ actionsAPIVersion string
+ actionOwners map[subject.Subject]actionhandler.Owner
+ actionOwnerLocks [256]sync.RWMutex
}
func newFastSandboxPolicyServer(ctx context.Context, reg *subject.MemoryRegistry, nft fastSandboxNftApplier) *fastSandboxPolicyServer {
return &fastSandboxPolicyServer{
- ctx: ctx,
- reg: reg,
- nft: nft,
- actionGate: make(chan struct{}, 1),
- rebinds: make(map[subject.Subject]*subjectRebind),
- vaults: make(map[subject.Subject]vaultEntry),
- pendingPolicies: make(map[subject.Subject]*policy.NetworkPolicy),
- policies: make(map[subject.Subject]*policyEntry),
- subjAtt: make(map[subject.Subject]actionhandler.NetworkAttachment),
- subjFence: make(map[subject.Subject]subject.Fencing),
- gatewayDNSRefs: make(map[subject.Subject]netip.Addr),
- dnsRedirectApply: iptables.ReplaceGatewayDNSRedirects,
- mitmEntries: make(map[subject.Subject]iptables.MitmRedirectEntry),
- instanceID: newHandlerInstanceID(),
+ ctx: ctx,
+ reg: reg,
+ nft: nft,
+ actionGate: make(chan struct{}, 1),
+ rebinds: make(map[subject.Subject]*subjectRebind),
+ vaults: make(map[subject.Subject]vaultEntry),
+ pendingPolicies: make(map[subject.Subject]*policy.NetworkPolicy),
+ policies: make(map[subject.Subject]*policyEntry),
+ subjAtt: make(map[subject.Subject]actionhandler.NetworkAttachment),
+ subjFence: make(map[subject.Subject]subject.Fencing),
+ gatewayDNSRefs: make(map[subject.Subject]netip.Addr),
+ dnsRedirectApply: iptables.ReplaceGatewayDNSRedirects,
+ mitmEntries: make(map[subject.Subject]iptables.MitmRedirectEntry),
+ instanceID: newHandlerInstanceID(),
+ actionsAPIVersion: constants.ActionsAPIVersion,
+ actionOwners: make(map[subject.Subject]actionhandler.Owner),
}
}
+func (s *fastSandboxPolicyServer) SetActionsAPIVersion(version string) {
+ s.actionsAPIVersion = version
+}
+
+func (s *fastSandboxPolicyServer) ownerLock(subj subject.Subject) *sync.RWMutex {
+ // Subject names are caller-provided identifiers. A bounded stripe set
+ // prevents requests for arbitrary subjects from growing a lock map forever;
+ // hash collisions only serialize otherwise independent subjects.
+ return &s.actionOwnerLocks[crc32.ChecksumIEEE([]byte(subj))%uint32(len(s.actionOwnerLocks))]
+}
+
// SetMitm wires the shared mitmproxy into the control plane: the healthz gate
// and the per-subject interception redirect install/remove. Called once at
// assembly, before the controller starts; a nil gate (MITM disabled) leaves
@@ -259,10 +279,18 @@ func cloneGatewayDNSRefs(refs map[subject.Subject]netip.Addr) map[subject.Subjec
// the healthz probe. No proxy-route surface.
func (s *fastSandboxPolicyServer) Handler() http.Handler {
mux := http.NewServeMux()
- mux.HandleFunc(constants.ActionsStatusPath, s.handleActionsStatus)
- mux.HandleFunc(constants.ActionsDispatchPath, s.handleActions)
- mux.HandleFunc(constants.VaultRelayPathPrefix, s.handleVaultRelay)
- mux.HandleFunc(constants.PolicyRelayPathPrefix, s.handlePolicyRelay)
+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {
+ mux.HandleFunc(constants.ActionsV2StatusPath, s.handleActionsV2Status)
+ mux.HandleFunc(constants.ActionsV2DispatchPath, s.handleActionsV2)
+ mux.HandleFunc(constants.ActionsV2OwnerPathPrefix, s.handleActionsV2Owner)
+ mux.HandleFunc(constants.ActionsV2VaultRelayPathPrefix, s.handleVaultRelay)
+ mux.HandleFunc(constants.ActionsV2PolicyRelayPathPrefix, s.handlePolicyRelay)
+ } else {
+ mux.HandleFunc(constants.ActionsStatusPath, s.handleActionsStatus)
+ mux.HandleFunc(constants.ActionsDispatchPath, s.handleActions)
+ mux.HandleFunc(constants.VaultRelayPathPrefix, s.handleVaultRelay)
+ mux.HandleFunc(constants.PolicyRelayPathPrefix, s.handlePolicyRelay)
+ }
mux.HandleFunc("/healthz", s.handleHealthz)
return mux
}
diff --git a/components/egress/fastsandbox_vault.go b/components/egress/fastsandbox_vault.go
index 6a3c4dbf4..50adf95dc 100644
--- a/components/egress/fastsandbox_vault.go
+++ b/components/egress/fastsandbox_vault.go
@@ -59,11 +59,23 @@ func validVaultSubjectID(uid string) bool {
// handleVaultRelay serves /vault/{sandboxUid} for all four relay verbs.
func (s *fastSandboxPolicyServer) handleVaultRelay(w http.ResponseWriter, r *http.Request) {
- uid := strings.TrimPrefix(r.URL.Path, constants.VaultRelayPathPrefix)
+ prefix := constants.VaultRelayPathPrefix
+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {
+ prefix = constants.ActionsV2VaultRelayPathPrefix
+ }
+ uid := strings.TrimPrefix(r.URL.Path, prefix)
if !validVaultSubjectID(uid) {
http.Error(w, "missing or invalid sandbox uid in path", http.StatusBadRequest)
return
}
+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {
+ ownerLock := s.ownerLock(subject.FromSandboxUID(uid))
+ ownerLock.RLock()
+ defer ownerLock.RUnlock()
+ }
+ if !s.validateRelayOwner(w, r, uid) {
+ return
+ }
subj := subject.FromSandboxUID(uid)
switch r.Method {
case http.MethodGet:
diff --git a/components/egress/pkg/actionhandler/actionhandler.go b/components/egress/pkg/actionhandler/actionhandler.go
index 257cf2e6f..4a345e168 100644
--- a/components/egress/pkg/actionhandler/actionhandler.go
+++ b/components/egress/pkg/actionhandler/actionhandler.go
@@ -43,6 +43,7 @@ import (
// APIVersion is the only accepted protocol version.
const APIVersion = "sandbox.fast.io/actions/v1"
+const APIVersionV2 = "sandbox.fast.io/actions/v2"
// Operation is the action operation code.
type Operation string
@@ -91,6 +92,31 @@ type Revision struct {
RouteGeneration uint64 `json:"routeGeneration"`
}
+// Owner is the complete platform-validated runtime fence carried by Actions
+// v2. It prevents delayed operations from being reinterpreted for a new slot
+// occupant; it is not caller authentication.
+type Owner struct {
+ SandboxUID string `json:"sandboxUid"`
+ FastletPodUID string `json:"fastletPodUid"`
+ RuntimeInstanceID string `json:"runtimeInstanceId"`
+ InstanceGeneration int64 `json:"instanceGeneration"`
+ AssignmentAttempt int64 `json:"assignmentAttempt"`
+ RouteGeneration int64 `json:"routeGeneration"`
+ AttachmentID string `json:"attachmentId"`
+}
+
+func (o Owner) Valid() bool {
+ return o.SandboxUID != "" && o.FastletPodUID != "" && o.RuntimeInstanceID != "" &&
+ o.InstanceGeneration > 0 && o.AssignmentAttempt > 0 && o.RouteGeneration > 0 && o.AttachmentID != ""
+}
+
+func (o Owner) Matches(other Owner) bool { return o == other }
+
+type OwnerObservation struct {
+ State string `json:"state"`
+ Owner Owner `json:"owner"`
+}
+
// NetworkAttachment is the network identity material the egress consumes:
// the dispatch key (SourceIP), the DNS/MITM targets (Gateway), the UDP
// spoofing defense (HostVeth iifname), and sibling isolation (PrivateCIDR).
@@ -183,6 +209,7 @@ type Envelope struct {
InvocationID string `json:"invocationId"`
Sandbox SandboxRef `json:"sandbox"`
Revision Revision `json:"revision"`
+ Owner *Owner `json:"owner,omitempty"`
Attachment *Attachment `json:"attachment,omitempty"`
Hook *Hook `json:"hook,omitempty"`
Binding *Binding `json:"binding,omitempty"`
@@ -193,11 +220,19 @@ type Envelope struct {
// the message is not a well-formed, understood action; the caller must fail
// closed (HTTP 400).
func ParseEnvelope(body []byte) (*Envelope, error) {
+ return ParseEnvelopeVersion(body, APIVersion)
+}
+
+func ParseEnvelopeV2(body []byte) (*Envelope, error) {
+ return ParseEnvelopeVersion(body, APIVersionV2)
+}
+
+func ParseEnvelopeVersion(body []byte, version string) (*Envelope, error) {
var e Envelope
if err := json.Unmarshal(body, &e); err != nil {
return nil, fmt.Errorf("invalid action envelope: %w", err)
}
- if err := e.Validate(); err != nil {
+ if err := e.ValidateVersion(version); err != nil {
return nil, err
}
return &e, nil
@@ -206,12 +241,25 @@ func ParseEnvelope(body []byte) (*Envelope, error) {
// Validate checks the protocol-level invariants. Field-level semantics (fence
// matching, registration state) are the caller's responsibility.
func (e *Envelope) Validate() error {
- if e.APIVersion != APIVersion {
- return fmt.Errorf("unsupported apiVersion %q (want %q)", e.APIVersion, APIVersion)
+ return e.ValidateVersion(APIVersion)
+}
+
+func (e *Envelope) ValidateVersion(version string) error {
+ if e.APIVersion != version {
+ return fmt.Errorf("unsupported apiVersion %q (want %q)", e.APIVersion, version)
}
if e.Sandbox.UID == "" {
return fmt.Errorf("sandbox.uid is required")
}
+ if version == APIVersionV2 {
+ if e.Owner == nil || !e.Owner.Valid() || e.Owner.SandboxUID != e.Sandbox.UID ||
+ e.Owner.RuntimeInstanceID != e.Revision.RuntimeInstanceID || e.Owner.AttachmentID != e.Revision.AttachmentID ||
+ uint64(e.Owner.RouteGeneration) != e.Revision.RouteGeneration {
+ return fmt.Errorf("Actions v2 requires an owner matching the sandbox and revision")
+ }
+ } else if e.Owner != nil {
+ return fmt.Errorf("Actions v1 must not carry an Actions v2 owner")
+ }
switch e.Operation {
case OperationSetBinding:
if e.Binding == nil {
@@ -286,9 +334,10 @@ func (e *Envelope) Fencing() (runtimeInstanceID, attachmentID string) {
// The MitmCa* fields are additive observability (OSEP-0022 pinned CA):
// consumers unaware of them ignore the extra JSON keys.
type StatusResponse struct {
- APIVersion string `json:"apiVersion"`
- Ready bool `json:"ready"`
- InstanceID string `json:"instanceId"`
+ APIVersion string `json:"apiVersion"`
+ Ready bool `json:"ready"`
+ InstanceID string `json:"instanceId"`
+ OwnerStatus bool `json:"ownerStatus,omitempty"`
// MitmCaFingerprint is the pinned MITM CA's SHA-256 fingerprint
// (lowercase hex over the DER); empty when MITM is disabled or no CA is
// provisioned.
diff --git a/components/egress/pkg/constants/configuration.go b/components/egress/pkg/constants/configuration.go
index 3dc479a3a..2ce9d3f5d 100644
--- a/components/egress/pkg/constants/configuration.go
+++ b/components/egress/pkg/constants/configuration.go
@@ -15,11 +15,25 @@
package constants
import (
+ "fmt"
"os"
"strconv"
"strings"
)
+func ParseFastSandboxActionsAPIVersion(raw string) (string, error) {
+ version := strings.TrimSpace(raw)
+ if version == "" {
+ return ActionsAPIVersion, nil
+ }
+ switch version {
+ case ActionsAPIVersion, ActionsAPIVersionV2:
+ return version, nil
+ default:
+ return "", fmt.Errorf("unsupported Fast Sandbox Actions apiVersion %q", version)
+ }
+}
+
const (
EnvCredentialVaultTrustedProxyCIDRs = "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_TRUSTED_PROXY_CIDRS"
EnvCredentialVaultRequireScopedMatch = "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_REQUIRE_SCOPED_MATCH"
@@ -43,9 +57,19 @@ const (
// Lifecycle Hooks to the egress Handler over two Pod-loopback HTTP endpoints
// on the action target port.
const (
- ActionsAPIVersion = "sandbox.fast.io/actions/v1"
- ActionsStatusPath = "/_fastlet/v1/actions/status"
- ActionsDispatchPath = "/_fastlet/v1/actions"
+ ActionsAPIVersion = "sandbox.fast.io/actions/v1"
+ ActionsAPIVersionV2 = "sandbox.fast.io/actions/v2"
+ ActionsStatusPath = "/_fastlet/v1/actions/status"
+ ActionsDispatchPath = "/_fastlet/v1/actions"
+ ActionsV2StatusPath = "/_fastlet/v2/actions/status"
+ ActionsV2DispatchPath = "/_fastlet/v2/actions"
+ ActionsV2OwnerPathPrefix = "/_fastlet/v2/owners/"
+ ActionsV2RelayPathPrefix = "/_fastlet/v2/relay/"
+ ActionsV2VaultRelayPathPrefix = ActionsV2RelayPathPrefix + "vault/"
+ ActionsV2PolicyRelayPathPrefix = ActionsV2RelayPathPrefix + "policy/"
+ EnvFastSandboxActionsAPIVersion = "OPENSANDBOX_EGRESS_ACTIONS_API_VERSION"
+ EgressActionsOwnerHeader = "X-Fast-Sandbox-Owner"
+ EgressActionsSandboxUIDHeader = "X-Sandbox-Uid"
HookRuntimeReady = "sandbox.runtime-ready"
HookDataPlaneReady = "sandbox.data-plane-ready"
diff --git a/docs/architecture/network/egress.md b/docs/architecture/network/egress.md
index cf42da97a..deae0ad12 100644
--- a/docs/architecture/network/egress.md
+++ b/docs/architecture/network/egress.md
@@ -57,6 +57,8 @@ Layers 1 and 2 decide *whether* a connection may happen; the transparent MITM la
::: warning Internal OSEP-0023 revision runtime
`OPENSANDBOX_EGRESS_EXPERIMENTAL_REVISION_RUNTIME=true` is a development-only sidecar gate (default off) for the OSEP-0023 revision protocol. It adds no public configuration surface or supported `interceptionMode`, and does not enable Fast Sandbox.
+The Fast Sandbox management transport has a separate `OPENSANDBOX_EGRESS_ACTIONS_API_VERSION` switch (default v1). Its experimental v2 value only selects strict Actions/relay HTTP routes; it does not enable the OSEP-0023 revision runtime or TLS interception. A v2 Fastlet Pool and every egress Handler must use the same version. V2 supports legacy-mode binding and Vault/Policy relay operations for clean-base Firecracker sandboxes; snapshots, template state, pause/resume, and restore are unsupported. Owner metadata fences the Sandbox runtime but is not caller authentication. Because the listener is on Pod-netns loopback, verify management-port isolation for the exact Fastlet Pod composition before enabling v2; this code does not configure or test that isolation.
+
The internal sidecar experiment covers bound HTTPS/443 HTTP/1.1 traffic and experimental HTTP/2 admission and bounded-drain wiring on the fixed-dependency direct/lazy path. Configured chained upstream proxies remain rejected for live HTTP/2. Long-held responses can still cause Go retries to time out; full client migration and Linux acceptance remain follow-up work. Key properties:
- Admission is per connection and per request, from an immutable snapshot installed over an authenticated channel; unknown or mismatched state denies — the mode never falls back to decrypt-all.