Skip to content

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

fix(egress): fail closed on unknown active-snapshot fields

高然041d8082133c
diff --git a/components/egress/mitmscripts/system.py b/components/egress/mitmscripts/system.py
index 9126cc7d0..d58b5cab9 100644
--- a/components/egress/mitmscripts/system.py
+++ b/components/egress/mitmscripts/system.py
@@ -119,6 +119,23 @@ ACTIVE_VAULT_HEADER_RESERVED_NAMES = {
_ACTIVE_VAULT_HEADER_NAME_RE = re.compile(r"^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$")
_ACTIVE_VAULT_HOST_LABEL_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
_PERCENT_ESCAPE_RE = re.compile(r"%([0-9A-Fa-f]{2})")
+# Strict snapshot key sets (OSEP-0025 version-skew gate). The addon rejects
+# any snapshot carrying fields outside these sets instead of silently
+# dropping them, so a newer egress must never degrade to an empty static
+# binding on an older addon.
+_ACTIVE_VAULT_TOP_LEVEL_FIELDS = {"revision", "bindings", "redactions"}
+_ACTIVE_VAULT_BINDING_FIELDS = {
+ "name",
+ "match",
+ "headers",
+ "substitutions",
+ "exchange",
+}
+# `ports` is deprecated upstream (accepted but ignored) and still rendered by
+# the Go snapshot for legacy vaults; it stays allowed and ignored here.
+_ACTIVE_VAULT_MATCH_FIELDS = {"schemes", "ports", "hosts", "methods", "paths"}
+_ACTIVE_VAULT_HEADER_FIELDS = {"name", "value"}
+_ACTIVE_VAULT_SUBSTITUTION_FIELDS = {"placeholder", "value", "in"}
_REVISION_RUNTIME_ERROR = "credential proxy: invalid revision runtime configuration"
_REVISION_ENV = {
"socket": "OPENSANDBOX_EGRESS_REVISION_IPC_SOCKET",
@@ -649,6 +666,12 @@ def _fetch_active_vault(
def _parse_active_vault(payload: Any) -> ActiveVault:
if not isinstance(payload, dict):
raise ActiveVaultLookupError("active vault payload must be an object")
+ unexpected_fields = set(payload) - _ACTIVE_VAULT_TOP_LEVEL_FIELDS
+ if unexpected_fields:
+ raise ActiveVaultLookupError(
+ "active vault payload contains unsupported fields: "
+ + ",".join(sorted(unexpected_fields))
+ )
revision = payload.get("revision")
if isinstance(revision, bool) or not isinstance(revision, int) or revision <= 0:
raise ActiveVaultLookupError("active vault revision must be a positive integer")
@@ -664,17 +687,31 @@ def _parse_active_vault(payload: Any) -> ActiveVault:
redaction_set = set(redactions)
normalized_bindings: list[dict[str, Any]] = []
for index, binding in enumerate(bindings):
+ unexpected_fields = set(binding) - _ACTIVE_VAULT_BINDING_FIELDS
+ if unexpected_fields:
+ raise ActiveVaultLookupError(
+ f"active vault binding {index} contains unsupported fields: "
+ + ",".join(sorted(unexpected_fields))
+ )
name = binding.get("name")
if not isinstance(name, str) or not name.strip():
raise ActiveVaultLookupError(
f"active vault binding {index} name must be a non-empty string"
)
+ exchange = _parse_active_vault_exchange(binding, index)
+
match = binding.get("match")
if not isinstance(match, dict):
raise ActiveVaultLookupError(
f"active vault binding {index} match must be an object"
)
+ unexpected_fields = set(match) - _ACTIVE_VAULT_MATCH_FIELDS
+ if unexpected_fields:
+ raise ActiveVaultLookupError(
+ f"active vault binding {index} match contains unsupported fields: "
+ + ",".join(sorted(unexpected_fields))
+ )
host_field = f"binding {index} match.hosts"
hosts = [
_normalize_active_vault_host(host, host_field)
@@ -709,6 +746,13 @@ def _parse_active_vault(payload: Any) -> ActiveVault:
)
normalized_headers: list[dict[str, str]] = []
for header_index, header in enumerate(raw_headers):
+ unexpected_fields = set(header) - _ACTIVE_VAULT_HEADER_FIELDS
+ if unexpected_fields:
+ raise ActiveVaultLookupError(
+ f"active vault binding {index} header {header_index} "
+ "contains unsupported fields: "
+ + ",".join(sorted(unexpected_fields))
+ )
header_name = header.get("name")
header_value = header.get("value")
if not isinstance(header_name, str) or not header_name.strip():
@@ -750,6 +794,13 @@ def _parse_active_vault(payload: Any) -> ActiveVault:
)
normalized_substitutions: list[dict[str, Any]] = []
for substitution_index, substitution in enumerate(raw_substitutions):
+ unexpected_fields = set(substitution) - _ACTIVE_VAULT_SUBSTITUTION_FIELDS
+ if unexpected_fields:
+ raise ActiveVaultLookupError(
+ f"active vault binding {index} substitution {substitution_index} "
+ "contains unsupported fields: "
+ + ",".join(sorted(unexpected_fields))
+ )
placeholder = substitution.get("placeholder")
value = substitution.get("value")
if not isinstance(placeholder, str) or not placeholder.strip():
@@ -792,19 +843,20 @@ def _parse_active_vault(payload: Any) -> ActiveVault:
{"placeholder": placeholder, "value": value, "in": surfaces}
)
- normalized_bindings.append(
- {
- "name": name.strip(),
- "match": {
- "schemes": schemes,
- "hosts": hosts,
- "methods": methods,
- "paths": paths,
- },
- "headers": normalized_headers,
- "substitutions": normalized_substitutions,
- }
- )
+ normalized_binding: dict[str, Any] = {
+ "name": name.strip(),
+ "match": {
+ "schemes": schemes,
+ "hosts": hosts,
+ "methods": methods,
+ "paths": paths,
+ },
+ "headers": normalized_headers,
+ "substitutions": normalized_substitutions,
+ }
+ if exchange is not None:
+ normalized_binding["exchange"] = exchange
+ normalized_bindings.append(normalized_binding)
return ActiveVault(
revision=revision,
bindings=normalized_bindings,
@@ -812,6 +864,36 @@ def _parse_active_vault(payload: Any) -> ActiveVault:
)
+def _parse_active_vault_exchange(binding: dict[str, Any], index: int) -> dict[str, str] | None:
+ """Validate the optional exchange marker of one snapshot binding.
+
+ Exchange bindings carry no rendered material: ``headers`` and
+ ``substitutions`` must be explicitly present and empty, and the marker
+ itself must be exactly ``{"credential": <non-empty name>}``. Anything
+ else fails the snapshot closed instead of silently degrading to a static
+ binding that would forward the request uncredentialed.
+ """
+ raw_exchange = binding.get("exchange")
+ if raw_exchange is None:
+ return None
+ if not isinstance(raw_exchange, dict) or set(raw_exchange) != {"credential"}:
+ raise ActiveVaultLookupError(
+ f"active vault binding {index} exchange must contain only credential"
+ )
+ credential = raw_exchange["credential"]
+ if not isinstance(credential, str) or not credential.strip():
+ raise ActiveVaultLookupError(
+ f"active vault binding {index} exchange credential must be a non-empty string"
+ )
+ for field in ("headers", "substitutions"):
+ if binding.get(field) != []:
+ raise ActiveVaultLookupError(
+ f"active vault binding {index} with exchange must carry an "
+ f"empty {field} list"
+ )
+ return {"credential": credential}
+
+
def _normalize_active_vault_strings(
value: Any,
field: str,
@@ -1806,6 +1888,18 @@ def _apply_vault_binding(
if not binding:
return
+ # Exchange bindings resolve per request against the egress process; until
+ # that resolve path is wired in (OSEP-0025 T3b), a selected exchange
+ # binding must fail closed instead of forwarding the request without
+ # credentials.
+ if "exchange" in binding:
+ _reject_request(flow, b"credential exchange unavailable\n", status_code=503)
+ ctx.log.warn(
+ "credential proxy: exchange binding unavailable binding="
+ f"{binding.get('name')}"
+ )
+ return
+
# Reject ambiguous paths only for requests that would receive credentials:
# dot-segments or backslashes could redirect credentials to a scope the
# canonical path does not match. Encoded slashes (``%2f`` at any decoding
diff --git a/components/egress/tests/test_decision_snapshot.py b/components/egress/tests/test_decision_snapshot.py
index 7269dfd82..19274a856 100644
--- a/components/egress/tests/test_decision_snapshot.py
+++ b/components/egress/tests/test_decision_snapshot.py
@@ -166,6 +166,16 @@ class DecisionSnapshotTest(unittest.TestCase):
mutate(candidate)
self.assert_rejected(candidate)
+ def test_rejects_exchange_marker_from_newer_egress(self):
+ """Version-skew gate: this validator predates OSEP-0025 exchange
+ markers, so a snapshot emitted by a newer egress must fail closed
+ here instead of degrading to an empty static binding."""
+ candidate = self.active()
+ candidate["fullRenderedBindings"][0]["exchange"] = {
+ "credential": "spi-signer"
+ }
+ self.assert_rejected(candidate)
+
def test_accepts_empty_substitution_and_legacy_empty_wildcard_language(self):
candidate = self.active()
candidate["fullRenderedBindings"] = [
diff --git a/components/egress/tests/test_mitmscripts_system.py b/components/egress/tests/test_mitmscripts_system.py
index efc463ea8..b791d4d3d 100644
--- a/components/egress/tests/test_mitmscripts_system.py
+++ b/components/egress/tests/test_mitmscripts_system.py
@@ -1235,6 +1235,268 @@ class SystemAddonRedactionTest(unittest.TestCase):
self.assertEqual("prefix [REDACTED] suffix", flow.response.headers.get("x-token-echo"))
+def _static_binding_payload(**overrides: Any) -> dict[str, Any]:
+ payload: dict[str, Any] = {
+ "revision": 9,
+ "bindings": [
+ {
+ "name": "gitlab-api",
+ "match": {
+ "schemes": ["https"],
+ "hosts": ["code.example.com"],
+ "methods": ["GET"],
+ "paths": ["/api/v8/*"],
+ },
+ "headers": [{"name": "Private-Token", "value": "secret-token"}],
+ }
+ ],
+ "redactions": ["secret-token"],
+ }
+ for path, value in overrides.items():
+ target: Any = payload
+ keys = path.split("__")
+ for key in keys[:-1]:
+ target = target[int(key)] if key.isdigit() else target[key]
+ target[keys[-1]] = value
+ return payload
+
+
+class SystemAddonActiveVaultStrictParseTest(unittest.TestCase):
+ """OSEP-0025 version-skew gate: unknown snapshot fields fail closed."""
+
+ def test_legacy_static_snapshot_parses_unchanged(self) -> None:
+ system = _load_system_module()
+ vault = system._parse_active_vault(_static_binding_payload())
+
+ self.assertEqual(9, vault.revision)
+ self.assertEqual(["secret-token"], vault.redactions)
+ self.assertEqual(
+ {
+ "name": "gitlab-api",
+ "match": {
+ "schemes": ["https"],
+ "hosts": ["code.example.com"],
+ "methods": ["GET"],
+ "paths": ["/api/v8/*"],
+ },
+ "headers": [{"name": "Private-Token", "value": "secret-token"}],
+ "substitutions": [],
+ },
+ vault.bindings[0],
+ )
+
+ def test_deprecated_match_ports_stay_allowed_and_ignored(self) -> None:
+ system = _load_system_module()
+ payload = _static_binding_payload()
+ payload["bindings"][0]["match"]["ports"] = [443]
+
+ vault = system._parse_active_vault(payload)
+
+ self.assertNotIn("ports", vault.bindings[0]["match"])
+ self.assertEqual(["code.example.com"], vault.bindings[0]["match"]["hosts"])
+
+ def test_unknown_fields_reject_at_every_level(self) -> None:
+ cases = {
+ "top-level": lambda payload: payload.update({"decisionEpoch": 1}),
+ "binding": lambda payload: payload["bindings"][0].update({"source": "inline"}),
+ "match": lambda payload: payload["bindings"][0]["match"].update({"regions": ["us"]}),
+ "header": lambda payload: payload["bindings"][0]["headers"][0].update({"foo": 1}),
+ }
+ for name, mutate in cases.items():
+ with self.subTest(name=name):
+ system = _load_system_module()
+ payload = _static_binding_payload()
+ mutate(payload)
+
+ with self.assertRaises(system.ActiveVaultLookupError):
+ system._parse_active_vault(payload)
+
+ def test_unknown_substitution_field_rejects(self) -> None:
+ system = _load_system_module()
+ payload = _static_binding_payload()
+ payload["bindings"][0]["substitutions"] = [
+ {"placeholder": "__p__", "value": "secret-token", "in": ["query"], "kind": "x"}
+ ]
+ payload["redactions"].append("__p__")
+
+ with self.assertRaises(system.ActiveVaultLookupError):
+ system._parse_active_vault(payload)
+
+ def test_exchange_binding_parses_with_marker(self) -> None:
+ system = _load_system_module()
+ payload = _static_binding_payload()
+ payload["bindings"] = [
+ {
+ "name": "internal-api",
+ "match": {
+ "schemes": ["https"],
+ "hosts": ["*.internal.example.com"],
+ "methods": ["GET"],
+ "paths": ["/*"],
+ },
+ "headers": [],
+ "substitutions": [],
+ "exchange": {"credential": "spi-signer"},
+ }
+ ]
+
+ vault = system._parse_active_vault(payload)
+
+ self.assertEqual(
+ {
+ "name": "internal-api",
+ "match": {
+ "schemes": ["https"],
+ "hosts": ["*.internal.example.com"],
+ "methods": ["GET"],
+ "paths": ["/*"],
+ },
+ "headers": [],
+ "substitutions": [],
+ "exchange": {"credential": "spi-signer"},
+ },
+ vault.bindings[0],
+ )
+
+ def test_exchange_binding_with_rendered_material_rejects(self) -> None:
+ def with_fields(**fields: Any) -> Any:
+ def mutate(payload: dict[str, Any]) -> None:
+ payload["bindings"][0].update(fields)
+
+ return mutate
+
+ def drop_headers(payload: dict[str, Any]) -> None:
+ del payload["bindings"][0]["headers"]
+
+ def drop_substitutions(payload: dict[str, Any]) -> None:
+ del payload["bindings"][0]["substitutions"]
+
+ def exchange_binding(payload: dict[str, Any]) -> None:
+ payload["bindings"] = [
+ {
+ "name": "internal-api",
+ "match": {
+ "schemes": ["https"],
+ "hosts": ["api.internal.example.com"],
+ "methods": ["GET"],
+ "paths": ["/*"],
+ },
+ "headers": [],
+ "substitutions": [],
+ "exchange": {"credential": "spi-signer"},
+ }
+ ]
+
+ cases = {
+ "non-empty headers": (exchange_binding, with_fields(
+ headers=[{"name": "x-a", "value": "b"}]
+ )),
+ "missing headers": (exchange_binding, drop_headers),
+ "null headers": (exchange_binding, with_fields(headers=None)),
+ "non-empty substitutions": (exchange_binding, with_fields(
+ substitutions=[
+ {"placeholder": "__p__", "value": "v", "in": ["query"]}
+ ]
+ )),
+ "missing substitutions": (exchange_binding, drop_substitutions),
+ }
+ for name, (build, mutate) in cases.items():
+ with self.subTest(name=name):
+ system = _load_system_module()
+ payload = _static_binding_payload()
+ build(payload)
+ mutate(payload)
+
+ with self.assertRaises(system.ActiveVaultLookupError):
+ system._parse_active_vault(payload)
+
+ def test_exchange_marker_shape_rejects(self) -> None:
+ markers = {
+ "non-object": "spi-signer",
+ "empty-object": {},
+ "extra-key": {"credential": "spi-signer", "endpoint": "unix:///run/x.sock"},
+ "missing-credential": {"endpoint": "unix:///run/x.sock"},
+ "empty-credential": {"credential": " "},
+ "non-string-credential": {"credential": 7},
+ }
+ for name, marker in markers.items():
+ with self.subTest(name=name):
+ system = _load_system_module()
+ payload = _static_binding_payload()
+ payload["bindings"][0]["headers"] = []
+ payload["bindings"][0]["exchange"] = marker
+
+ with self.assertRaises(system.ActiveVaultLookupError):
+ system._parse_active_vault(payload)
+
+ def test_static_binding_in_exchange_vault_still_injects(self) -> None:
+ system = _load_system_module()
+ vault = system.ActiveVault(
+ 12,
+ [
+ {
+ "name": "internal-api",
+ "match": {"hosts": ["api.internal.example.com"]},
+ "headers": [],
+ "substitutions": [],
+ "exchange": {"credential": "spi-signer"},
+ },
+ {
+ "name": "gitlab-api",
+ "match": {"hosts": ["code.example.com"]},
+ "headers": [{"name": "Private-Token", "value": "secret-token"}],
+ "substitutions": [],
+ },
+ ],
+ ["secret-token"],
+ )
+ system._load_active_vault = lambda _client_ip=None: vault
+ flow = _Flow()
+ flow.response = None
+ flow.request.headers["Content-Length"] = "0"
+
+ system.requestheaders(flow)
+
+ self.assertEqual("secret-token", flow.request.headers.get("Private-Token"))
+ self.assertFalse(flow.killed)
+ self.assertIsNone(flow.response)
+
+ def test_selected_exchange_binding_fails_closed_buffered_and_streamed(self) -> None:
+ for streamed in (False, True):
+ with self.subTest(streamed=streamed):
+ system = _load_system_module()
+ vault = system.ActiveVault(
+ 12,
+ [
+ {
+ "name": "internal-api",
+ "match": {"hosts": ["code.example.com"]},
+ "headers": [],
+ "substitutions": [],
+ "exchange": {"credential": "spi-signer"},
+ }
+ ],
+ [],
+ )
+ system._load_active_vault = lambda _client_ip=None: vault
+ flow = _Flow()
+ flow.response = None
+ flow.request.stream = streamed
+ if not streamed:
+ flow.request.headers["Content-Length"] = "0"
+
+ system.requestheaders(flow)
+
+ self.assertTrue(flow.metadata[system.FLOW_REJECTION_KEY])
+ self.assertNotIn(system.FLOW_BINDING_KEY, flow.metadata)
+ if streamed:
+ self.assertTrue(flow.killed)
+ self.assertIsNone(flow.response)
+ else:
+ self.assertFalse(flow.killed)
+ self.assertEqual(503, flow.response.status_code)
+
+
@unittest.skipUnless(
hasattr(socket, "AF_UNIX") and hasattr(socketserver, "UnixStreamServer"),
"Unix domain sockets are unavailable on this platform",