Skip to content

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

chore(egress): trim T3b comments to repo terseness

高然dee6e49b3fec
diff --git a/components/egress/mitmscripts/system.py b/components/egress/mitmscripts/system.py
index ffa231766..8ce39a86c 100644
--- a/components/egress/mitmscripts/system.py
+++ b/components/egress/mitmscripts/system.py
@@ -28,13 +28,10 @@
# fail closed for all intercepted requests, including hosts outside any
# binding scope. Credential values are never logged; response header values
# containing them are redacted. Response bodies are not rewritten.
-# Exchange bindings (OSEP-0025) carry only an `exchange: {credential}`
-# marker in the snapshot: the async `requestheaders` hook resolves them
-# per request on the active socket `_resolve` endpoint (real I/O runs in
-# a worker thread behind a concurrency semaphore), injects the returned
-# headers, and fails closed — 407 for buffered requests, kill for
-# streamed ones — on any resolve failure. Static bindings keep running
-# fully inline inside the same hook and never suspend it.
+# Exchange bindings (OSEP-0025) carry only a marker in the snapshot:
+# the async `requestheaders` hook resolves them per request on the
+# active socket `_resolve` endpoint and fails closed (407/kill) on any
+# failure; static bindings stay inline and never suspend the hook.
# Processing is split across hooks because stream_large_bodies=1m streams
# bodies above 1 MiB upstream before the `request` hook fires: binding
# match, path/query/header rewrites and header injection run in
@@ -88,10 +85,8 @@ CREDENTIAL_PROXY_SOCKET_ENV = "OPENSANDBOX_CREDENTIAL_PROXY_SOCKET"
DEFAULT_CREDENTIAL_PROXY_SOCKET = "/run/opensandbox/credential-proxy/active.sock"
ACTIVE_VAULT_PATH = "/credential-vault/_active"
CREDENTIAL_RESOLVE_PATH = "/credential-vault/_resolve"
-# The Go egress owns the resolver budget (seconds, 1..120, default 2 — mirror
-# of pkg/constants + ResolverTimeoutFromEnv); the addon adds a fixed margin so
-# the egress can deliver its own timeout classification before the socket
-# deadline fires. Never hardcode the raw timeout.
+# Mirrors the Go resolver timeout env (seconds, 1..120, default 2); the fixed
+# margin lets the egress deliver its own timeout classification first.
CREDENTIAL_RESOLVER_TIMEOUT_ENV = "OPENSANDBOX_EGRESS_CREDENTIAL_RESOLVER_TIMEOUT"
CREDENTIAL_RESOLVER_MAX_CONCURRENCY_ENV = (
"OPENSANDBOX_EGRESS_CREDENTIAL_RESOLVER_MAX_CONCURRENCY"
@@ -1012,17 +1007,12 @@ def _validate_active_vault_etag(value: str | None) -> str:
class CredentialResolveError(Exception):
- """A resolve RPC failure carrying a fixed, log-safe reason token.
-
- Tokens: ``transport`` (socket/protocol error), ``invalid_response``
- (non-contract 200 body), ``http_<status>`` (non-200 endpoint reply).
- Resolve request/response content never reaches logs.
- """
+ """Resolve failure with a log-safe reason: transport | invalid_response
+ | http_<status>. Resolve content never reaches logs."""
def _env_int_range(name: str, default: int, bounds: tuple[int, int]) -> int:
- # Mirrors Go EnvIntRange: trimmed decimal integer inside bounds, any
- # other value keeps the default (no silent clamping of nonsense).
+ # Mirrors Go EnvIntRange: unparsable or out-of-bounds keeps the default.
raw = os.environ.get(name, "").strip()
if not raw or _ENV_INT_RE.fullmatch(raw) is None:
return default
@@ -1043,9 +1033,8 @@ def _resolve_budget_seconds() -> float:
)
-# Bounded concurrent resolves, aligned with the Go endpoint's semaphore. The
-# state is keyed by the running loop because tests and script reloads may
-# swap event loops while the module stays loaded.
+# Concurrency aligned with the Go endpoint's semaphore; keyed by loop
+# because tests and script reloads swap event loops.
_resolve_limiter_state: tuple[asyncio.AbstractEventLoop, asyncio.Semaphore] | None = None
@@ -1131,12 +1120,7 @@ def _parse_resolve_response(raw: bytes, binding_name: str) -> dict[str, Any]:
def _resolve_exchange_http(
socket_path: str, timeout: float, path: str, payload: dict[str, Any]
) -> dict[str, Any]:
- """One resolve RPC on the active socket; runs in a worker thread.
-
- Reuses the HTTP-over-unix-socket transport of `_fetch_active_vault`.
- Failures are normalized to CredentialResolveError so callers have a
- single fail-closed direction.
- """
+ """One resolve RPC; failures normalize to CredentialResolveError."""
connection = UnixSocketHTTPConnection(socket_path, timeout=timeout)
try:
body = json.dumps(payload).encode("utf-8")
@@ -1144,9 +1128,8 @@ def _resolve_exchange_http(
"POST", path, body=body, headers={"Content-Type": "application/json"}
)
response = connection.getresponse()
- # Bound the read itself — the size check must not run after an
- # unbounded buffer: a peer can otherwise force arbitrary bytes into
- # memory, multiplied by the concurrent per-request resolves.
+ # Bound the read itself; the size check must not follow an unbounded
+ # buffer, multiplied by concurrent per-request resolves.
raw = response.read(MAX_RESOLVE_RESPONSE_BYTES + 1)
if response.status != 200:
raise CredentialResolveError(f"http_{response.status}")
@@ -1914,10 +1897,9 @@ async def requestheaders(flow: http.HTTPFlow) -> None:
In live credential-bound mode the vault comes from the admitted decision
snapshot (see :func:`_requestheaders_live`) instead of the pull cache.
- The hook is async because mitmproxy awaits it to completion before the
- request continues; exchange bindings defer their resolve I/O through the
- single await below. Static bindings and the live path run fully inline
- and never suspend the hook.
+ The hook is async because mitmproxy awaits it before the request
+ continues: exchange bindings defer resolve I/O to the single await
+ below; static and live paths stay inline and never suspend.
"""
live = _live_runtime
if live is not None:
@@ -2063,14 +2045,9 @@ def _live_snapshot_vault(snapshot: Any) -> ActiveVault | None:
def _reject_ambiguous_binding_path(
flow: http.HTTPFlow, vault: ActiveVault
) -> bool:
- """Shared credential-path gate for static and exchange injection.
-
- Rejects dot-segments/backslashes and encodings whose percent-decoding
- would cross a binding boundary: only requests that would receive a
- credential are checked, and a resolved/inlined secret must never reach
- a scope the canonical path does not match. Returns True when the
- request was rejected.
- """
+ """Shared path gate for static and exchange injection: reject ambiguous
+ or boundary-crossing encodings so a secret never reaches a scope the
+ canonical path does not match. Returns True when rejected."""
raw_path = flow.request.path or "/"
if _path_is_ambiguous(raw_path, allow_encoded_slash=True):
_reject_request(flow, b"request path contains ambiguous segments\n")
@@ -2095,10 +2072,8 @@ def _apply_vault_binding(
) -> Any | None:
"""Shared binding selection, ambiguity checks and credential injection.
- Returns an awaitable when a pull-mode exchange binding defers its
- resolve I/O to the caller (the request must not continue before it
- completes); every other path returns None after handling the flow.
- """
+ Returns an awaitable only for pull-mode exchange bindings (their resolve
+ I/O must complete before the request continues)."""
# Requests outside credential binding scope are ordinary egress traffic.
# Leave them untouched, including paths whose encoding would be ambiguous
# for credential injection, because no secret is at risk.
@@ -2159,12 +2134,10 @@ def _apply_exchange_binding(
binding: dict[str, Any],
live: Any | None,
) -> Any | None:
- """Gate one exchange binding, then defer its resolve I/O to the caller.
+ """Gate one exchange binding, then defer its resolve I/O.
- Push-mode (live) snapshots never carry exchange bindings — the egress
- admission gate rejects them — so the defensive branch stays fail closed
- instead of resolving from the decision path.
- """
+ Live snapshots never carry exchange (the egress admission gate rejects
+ them); the defensive branch stays fail closed."""
if live is not None:
_reject_request(flow, b"credential exchange unavailable\n", status_code=503)
ctx.log.warn(
@@ -2172,14 +2145,11 @@ def _apply_exchange_binding(
f"{binding.get('name')}"
)
return None
- # Same path gate as static injection (shared helper): an ambiguous or
- # boundary-crossing encoding must never be handed a resolved credential.
if _reject_ambiguous_binding_path(flow, vault):
return None
sni = _connection_sni(flow)
if sni is None:
- # The egress SNI gate needs the verified TLS destination; without a
- # connection SNI no exchange binding can ever resolve.
+ # Without a connection SNI the egress SNI gate can never pass.
_reject_request(
flow, b"credential resolution unavailable\n", status_code=407
)
@@ -2196,13 +2166,11 @@ async def _resolve_exchange_binding(
binding: dict[str, Any],
sni: str,
) -> None:
- """Resolve one exchange binding on the active socket and inject headers.
+ """Resolve on the active socket and inject headers.
- Real I/O runs in a worker thread behind the concurrency semaphore so a
- slow resolver never blocks the event loop. Any failure fails closed:
- 407 for buffered requests, kill for streamed ones. Results live only in
- flow metadata — never a module-level cache.
- """
+ I/O runs in a worker thread behind the semaphore so a slow resolver
+ never blocks the loop; any failure fails closed (407/kill). Results
+ live only in flow metadata."""
name = binding.get("name")
path = CREDENTIAL_RESOLVE_PATH
client_ip = _flow_client_ip(flow)
@@ -2269,16 +2237,14 @@ def _install_exchange_headers(
) -> None:
"""Inject resolved headers and persist per-request redaction metadata.
- The redaction set re-derives every rendered variant of each injected
- value, so response redaction never depends on resolver output
- completeness (R9), and injected names always join the by-name suppress
- set (D7).
- """
+ Variants of every injected value are re-derived (R9) and injected names
+ always join the suppress set (D7), so redaction never depends on
+ resolver output completeness."""
injected_names: list[str] = []
for header in decision["headers"]:
name = header["name"]
- # Same delete-then-set as static injection: mitmproxy Headers is
- # case-insensitive and the resolved value must be the only one.
+ # Delete-then-set, as static injection: the resolved value must be
+ # the only one.
if name in flow.request.headers:
del flow.request.headers[name]
flow.request.headers[name] = header["value"]
@@ -2375,11 +2341,8 @@ def client_disconnected(client_conn: Any) -> None:
def _suppress_response_headers(flow: http.HTTPFlow) -> None:
- """Delete by-name suppressed response headers (exchange bindings).
-
- The suppress set was validated at resolve time; names are matched
- case-insensitively and every occurrence is removed.
- """
+ """Delete by-name suppressed response headers; the set was validated at
+ resolve time and every occurrence is removed."""
suppress = flow.metadata.get(FLOW_VAULT_SUPPRESS_KEY)
if not suppress or flow.response is None:
return
diff --git a/components/egress/tests/test_mitmscripts_system.py b/components/egress/tests/test_mitmscripts_system.py
index d87572503..696b44f8e 100644
--- a/components/egress/tests/test_mitmscripts_system.py
+++ b/components/egress/tests/test_mitmscripts_system.py
@@ -1474,9 +1474,9 @@ class SystemAddonActiveVaultStrictParseTest(unittest.TestCase):
self.assertIsNone(flow.response)
def test_selected_exchange_binding_fails_closed_buffered_and_streamed(self) -> None:
- # The T3a 503 placeholder was replaced by the T3b resolve branch;
- # without a connection SNI the resolve can never be built, so the
- # request still fails closed — 407 buffered, kill streamed.
+ # T3b replaced the 503 placeholder with the resolve branch; without
+ # a connection SNI the resolve cannot be built, so the request still
+ # fails closed — 407 buffered, kill streamed.
for streamed in (False, True):
with self.subTest(streamed=streamed):
system = _load_system_module()
diff --git a/components/egress/tests/test_system_resolve.py b/components/egress/tests/test_system_resolve.py
index 05d21b850..2a2b81571 100644
--- a/components/egress/tests/test_system_resolve.py
+++ b/components/egress/tests/test_system_resolve.py
@@ -482,8 +482,8 @@ class ExchangeResolveTest(unittest.TestCase):
def test_response_suppression_and_by_value_redaction(self) -> None:
self._install_vault()
- # Redactions deliberately miss every rendered variant: the addon must
- # re-derive them (R9) so echoes cannot leak the resolved value.
+ # Redactions deliberately miss every variant; the addon must
+ # re-derive them (R9).
self._install_transport(
lambda payload: _parsed_decision(redactions=[SECRET, SECOND_SECRET])
)
@@ -749,8 +749,8 @@ class ExchangeResolveTest(unittest.TestCase):
asyncio.run(self.system.requestheaders(flow))
- # The read itself is bounded to limit+1 bytes: an oversized body is
- # rejected without ever buffering more than the cap allows.
+ # The read itself is bounded; oversized bodies never buffer beyond
+ # the cap.
self.assertEqual(limit + 1, scripted.amt)
self.assertTrue(flow.metadata[self.system.FLOW_REJECTION_KEY])
self.assertEqual(407, flow.response.status_code)