docker_egress.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298
  1. """Egress-proxy (iron-proxy) plumbing for the Docker backend.
  2. Builds the mount/env/host args that route a sandbox through the host-side
  3. credential firewall, and guards the three config surfaces (docker_forward_env,
  4. docker_env, docker_extra_args) that could otherwise weaken or bypass it.
  5. """
  6. from __future__ import annotations
  7. import hashlib
  8. import json
  9. import logging
  10. logger = logging.getLogger("tools.environments.docker")
  11. _EGRESS_LABEL_KEY = "hermes-egress"
  12. _CONTAINER_CA = "/etc/ssl/certs/hermes-egress-ca.crt"
  13. _NODE_OPTIONS_SENTINEL = "_HERMES_EGRESS_NODE_OPTIONS_APPEND"
  14. _CA_MODE_FLAGS = {"--use-openssl-ca", "--use-bundled-ca"}
  15. # Env names whose override would weaken or bypass enforced egress.
  16. _PROXY_CONTROL_ENV = frozenset({
  17. "HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy",
  18. "NO_PROXY", "no_proxy",
  19. "REQUESTS_CA_BUNDLE", "SSL_CERT_FILE", "CURL_CA_BUNDLE",
  20. "NODE_EXTRA_CA_CERTS"})
  21. def _egress_proxy_args_for_docker() -> tuple[list[str], dict[str, str], list[str]]:
  22. """``(volume_args, env_overrides, host_args)`` for routing through iron-proxy; all empty
  23. when the proxy is disabled/unconfigured/not running. Under ``proxy.enforce_on_docker``
  24. (default) any half-configured state raises so the sandbox refuses to start unprotected;
  25. otherwise it warns and continues. Only ImportError is swallowed — a broken config must
  26. fail visibly rather than silently disable enforcement."""
  27. try:
  28. from hermes_cli.config import load_config
  29. from agent.proxy_sources import iron_proxy as ip
  30. except ImportError as exc:
  31. logger.debug("Egress proxy plumbing unavailable: %s", exc)
  32. return ([], {}, [])
  33. proxy_cfg = load_config().get("proxy") or {}
  34. if not proxy_cfg.get("enabled"):
  35. return ([], {}, [])
  36. status = ip.get_status()
  37. enforce = bool(proxy_cfg.get("enforce_on_docker", True))
  38. def _degraded(msg: str):
  39. if enforce:
  40. raise RuntimeError(msg)
  41. logger.warning("%s — continuing without proxy (enforce_on_docker=false).", msg)
  42. return ([], {}, [])
  43. if not status.configured:
  44. return _degraded(
  45. "proxy.enabled is true but iron-proxy is not configured. "
  46. "Run `hermes egress setup` to mint tokens and write proxy.yaml.")
  47. if not (status.pid and status.listening):
  48. return _degraded(
  49. f"iron-proxy is enabled but not running on port {status.tunnel_port}. "
  50. "Start it with `hermes egress start`.")
  51. if status.ca_cert_path is None or not status.ca_cert_path.exists():
  52. # Configured a moment ago but the trust anchor vanished: proxy env vars
  53. # without the CA would make every TLS handshake fail.
  54. return _degraded(
  55. f"iron-proxy CA cert vanished from {status.ca_cert_path}. "
  56. "Re-run `hermes egress setup` to regenerate it.")
  57. # Empty/corrupt mappings look like an upstream outage from inside the
  58. # sandbox (every request 403s); refuse rather than ship a broken sandbox.
  59. mappings = ip.load_mappings()
  60. if not mappings:
  61. return _degraded(
  62. "iron-proxy is configured but mappings.json is empty or "
  63. "corrupt. Re-run `hermes egress setup` to mint provider "
  64. "tokens before starting a sandbox.")
  65. volume_args = ["-v", f"{status.ca_cert_path}:{_CONTAINER_CA}:ro"]
  66. # tunnel_port serves CONNECT (HTTPS); the plain-HTTP forward listener is on +1.
  67. proxy_url = f"http://host.docker.internal:{status.tunnel_port}"
  68. plain_http_url = f"http://host.docker.internal:{status.tunnel_port + 1}"
  69. env_overrides: dict[str, str] = {
  70. # Both casings: some tools only read one.
  71. "HTTPS_PROXY": proxy_url,
  72. "https_proxy": proxy_url,
  73. "HTTP_PROXY": plain_http_url,
  74. "http_proxy": plain_http_url,
  75. # Loopback-only so in-sandbox dev servers/local LLMs bypass the proxy.
  76. "NO_PROXY": "127.0.0.1,localhost,::1",
  77. "no_proxy": "127.0.0.1,localhost,::1",
  78. # CA bundles: Python/curl vars REPLACE the system store, NODE_EXTRA_CA_CERTS
  79. # only ADDS to it. NODE_OPTIONS=--use-openssl-ca narrows that asymmetry
  80. # but must be APPENDED to the operator's NODE_OPTIONS, not clobber it —
  81. # so it travels in a sentinel key that merge_egress_env() resolves.
  82. "REQUESTS_CA_BUNDLE": _CONTAINER_CA,
  83. "SSL_CERT_FILE": _CONTAINER_CA,
  84. "CURL_CA_BUNDLE": _CONTAINER_CA,
  85. "NODE_EXTRA_CA_CERTS": _CONTAINER_CA,
  86. "HERMES_EGRESS_PROXY": "1", # lets the in-sandbox agent know it is proxy-aware
  87. _NODE_OPTIONS_SENTINEL: "--use-openssl-ca"}
  88. # Proxy tokens under the standard provider env names (and their aliases) so
  89. # SDKs work unchanged; HERMES_PROXY_TOKEN_* copies are for diagnostics.
  90. for m in mappings:
  91. env_overrides[m.real_env_name] = m.proxy_token
  92. env_overrides[f"HERMES_PROXY_TOKEN_{m.real_env_name}"] = m.proxy_token
  93. for alias in getattr(m, "alias_env_names", ()) or ():
  94. env_overrides[alias] = m.proxy_token
  95. # Linux needs an explicit host-gateway mapping; Docker Desktop already has it.
  96. host_args = ["--add-host", "host.docker.internal:host-gateway"]
  97. return (volume_args, env_overrides, host_args)
  98. def _egress_reuse_fingerprint(
  99. volume_args: list[str], env_overrides: dict[str, str], host_args: list[str]) -> str:
  100. """Stable Docker-label value for the egress posture of a container."""
  101. if not (volume_args or env_overrides or host_args):
  102. return "off"
  103. payload = json.dumps(
  104. {"volume_args": volume_args, "env_overrides": env_overrides, "host_args": host_args},
  105. sort_keys=True, separators=(",", ":"))
  106. return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:24]
  107. def _egress_enforce_on_docker(default: bool = True) -> bool:
  108. """Read proxy.enforce_on_docker; any config failure fails safe to *default*."""
  109. try:
  110. from hermes_cli.config import load_config
  111. return bool((load_config().get("proxy") or {}).get("enforce_on_docker", default))
  112. except (ImportError, OSError):
  113. return default
  114. except Exception as exc: # malformed config.yaml etc.
  115. logger.warning("Could not read proxy config for egress collision check: %s", exc)
  116. return default
  117. def _critical_egress_env_names(env_overrides: dict[str, str]) -> set[str]:
  118. """Env names that would weaken or bypass enforced egress if overridden.
  119. Every name the egress layer writes is critical: mapped tokens land under arbitrary
  120. ``real_env_name``/``alias_env_names`` entries from mappings.json, so a suffix
  121. heuristic would silently unprotect any mapped credential not ending in
  122. ``_API_KEY``/``_TOKEN`` (e.g. ``AWS_SECRET_ACCESS_KEY``)."""
  123. return set(_PROXY_CONTROL_ENV) | {"NODE_OPTIONS"} | set(env_overrides)
  124. # ``docker run`` boolean shorthands that may precede a value-taking shorthand
  125. # in a single-dash chain (pflag: "-iteNAME=v" parses as -i -t -e NAME=v).
  126. _DOCKER_RUN_BOOL_SHORTHANDS = frozenset("ditPq")
  127. def _env_flag_value(arg: str) -> tuple[str, str | None] | None:
  128. """``("env"|"env-file", inline_value)`` when ``arg`` spells a docker env flag
  129. under pflag parsing, else ``None``. ``inline_value`` is the joined value
  130. (``--env=N=v``, ``-eN=v``) or ``None`` when the flag consumes the next arg
  131. (``-e``, ``--env``, ``-ite``)."""
  132. if arg.startswith("--"):
  133. flag, sep, inline = arg.partition("=")
  134. if flag in ("--env", "--env-file"):
  135. return flag[2:], inline if sep else None
  136. return None
  137. if not arg.startswith("-"):
  138. return None # positional (image/command), never a flag
  139. # A single dash heads a shorthand chain: every letter before the last must
  140. # be a boolean shorthand, and the last takes the rest of the arg (or the
  141. # next arg when bare) as its value.
  142. for pos, ch in enumerate(arg[1:]):
  143. if ch in _DOCKER_RUN_BOOL_SHORTHANDS:
  144. continue
  145. if ch == "e":
  146. rest = arg[pos + 2:]
  147. rest = rest.removeprefix("=")
  148. return "env", rest or None
  149. return None
  150. return None
  151. def _extra_args_egress_collisions(extra_args: list[str], critical_names: set[str]) -> list[str]:
  152. """Return docker_extra_args entries that can override egress controls."""
  153. # Folded membership: ``-e NAME`` resolves NAME in the host env, which is
  154. # case-insensitive on Windows — ``-eopenai_api_key`` would inject the real
  155. # credential past the token swap.
  156. critical_folded = {n.upper() for n in critical_names}
  157. collisions: list[str] = []
  158. i = 0
  159. while i < len(extra_args):
  160. arg = extra_args[i]
  161. # pflag stops flag parsing at "--"; the rest is image/command. Bare
  162. # positionals keep being scanned: a preceding long flag may consume
  163. # them as its value, and over-scanning errs toward enforcement.
  164. if arg == "--":
  165. break
  166. parsed = _env_flag_value(arg)
  167. if parsed is not None:
  168. kind, inline_value = parsed
  169. if kind == "env-file":
  170. collisions.append("--env-file")
  171. else:
  172. value = inline_value if inline_value is not None else (
  173. extra_args[i + 1] if i + 1 < len(extra_args) else "")
  174. name = value.split("=", 1)[0]
  175. if name.upper() in critical_folded:
  176. collisions.append(name)
  177. i += 1 if inline_value is not None else 2
  178. continue
  179. if arg.partition("=")[0] in ("--network", "--net"):
  180. collisions.append(arg)
  181. i += 1
  182. return sorted(set(collisions))
  183. def _collision_guard(msg: str, *, enforce: bool, remedy: str, consequence: str) -> None:
  184. """Fail loud under enforcement, otherwise warn and let the user's config win."""
  185. msg = f"{msg}; enforce_on_docker is {'enabled' if enforce else 'disabled'}."
  186. if enforce:
  187. raise RuntimeError(f"{msg} {remedy}")
  188. logger.warning("%s %s", msg, consequence)
  189. def check_forward_env_collisions(forward_env: list[str], critical: set[str], enforce: bool) -> None:
  190. # Folded membership: forward_env names are resolved via os.getenv() on the
  191. # host, which is case-insensitive on Windows — ``openai_api_key`` would
  192. # inject the real credential into the container under a variant name.
  193. critical_folded = {k.upper() for k in critical}
  194. collisions = sorted(k for k in forward_env if k.upper() in critical_folded)
  195. if collisions:
  196. _collision_guard(
  197. f"docker_forward_env would inject real egress-protected variables {collisions}",
  198. enforce=enforce,
  199. remedy="Remove these names from docker_forward_env or disable enforce_on_docker "
  200. "to opt out of egress isolation.",
  201. consequence="Explicit docker_forward_env values will override egress tokens.")
  202. def check_docker_env_collisions(user_env: dict[str, str], egress_env: dict[str, str], enforce: bool) -> None:
  203. """Reject docker_env overrides of proxy-control vars or real provider keys (read from the
  204. live token mappings; for those ANY override collides since a real key bypasses the swap)."""
  205. provider_keys: set[str] = set()
  206. try:
  207. from agent.proxy_sources import iron_proxy as ip
  208. provider_keys = {m.real_env_name for m in ip.load_mappings()}
  209. except Exception: # best-effort
  210. pass
  211. def _collides(k: str) -> bool:
  212. if k not in user_env:
  213. return False
  214. if k in provider_keys:
  215. return k not in egress_env or user_env[k] != egress_env[k]
  216. return k in egress_env and user_env[k] != egress_env[k]
  217. collisions = sorted(k for k in (_PROXY_CONTROL_ENV | provider_keys) if _collides(k))
  218. if collisions:
  219. _collision_guard(
  220. f"docker_env in config.yaml overrides egress-proxy variables {collisions}",
  221. enforce=enforce,
  222. remedy="Remove these keys from docker_env or disable enforce_on_docker to opt out "
  223. "of egress isolation.",
  224. consequence="Falling back to docker_env values; sandbox traffic will NOT route "
  225. "through the proxy.")
  226. def check_extra_args_collisions(extra_args: list[str], critical: set[str], enforce: bool) -> None:
  227. collisions = _extra_args_egress_collisions(extra_args, critical)
  228. if collisions:
  229. _collision_guard(
  230. f"docker_extra_args would override egress-proxy controls {collisions}",
  231. enforce=enforce,
  232. remedy="Remove these args or disable enforce_on_docker to opt out of egress isolation.",
  233. consequence="Extra Docker args may bypass egress isolation.")
  234. def merge_egress_env(user_env: dict[str, str], egress_env: dict[str, str], enforce: bool) -> dict[str, str]:
  235. """Merge docker_env with egress overrides (egress wins under enforcement, docker_env
  236. otherwise) and resolve the NODE_OPTIONS sentinel: the flag is APPENDED to the operator's
  237. NODE_OPTIONS after stripping conflicting CA-mode flags so it wins deterministically."""
  238. merged = {**user_env, **egress_env} if enforce and egress_env else {**egress_env, **user_env}
  239. raw_append = merged.pop(_NODE_OPTIONS_SENTINEL, None)
  240. if raw_append:
  241. append_token = raw_append.strip()
  242. tokens = merged.get("NODE_OPTIONS", "").split()
  243. if append_token in _CA_MODE_FLAGS:
  244. dropped = [t for t in tokens if t in _CA_MODE_FLAGS and t != append_token]
  245. if dropped:
  246. logger.warning(
  247. "Overriding conflicting NODE_OPTIONS CA-mode flag(s) %s "
  248. "with egress-required %s to keep Node routed through the "
  249. "egress CA store.", dropped, append_token)
  250. tokens = [t for t in tokens if t not in _CA_MODE_FLAGS or t == append_token]
  251. if append_token not in tokens:
  252. tokens.append(append_token)
  253. merged["NODE_OPTIONS"] = " ".join(tokens).strip()
  254. if not merged["NODE_OPTIONS"]:
  255. merged.pop("NODE_OPTIONS", None)
  256. return merged