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.pyindex 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 decisionsnapshot (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_runtimeif 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 Nonesni = _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_PATHclient_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:returndiff --git a/components/egress/tests/test_mitmscripts_system.py b/components/egress/tests/test_mitmscripts_system.pyindex 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.pyindex 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)