iron_proxy.py 48 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966
  1. """iron-proxy (``ironsh/iron-proxy``) integration for credential-injecting egress control.
  2. Sandboxes (Docker/Modal/SSH) hold only opaque proxy tokens; iron-proxy — a TLS-intercepting,
  3. default-deny egress firewall — swaps them for real credentials on the way out, so a leaked
  4. token is useless outside the trusted proxy boundary. The pinned binary is auto-installed
  5. into the PM tool store; CA, ``proxy.yaml``, ``mappings.json``, pidfile and logs live in
  6. ``<hermes_home>/proxy``. Failures warn and never block agent startup.
  7. """
  8. from __future__ import annotations
  9. import hashlib
  10. import ipaddress
  11. import json
  12. import logging
  13. import os
  14. import platform
  15. import shutil
  16. import signal
  17. import subprocess
  18. import tempfile
  19. import threading
  20. import time
  21. import urllib.error
  22. import urllib.request
  23. from contextlib import contextmanager, suppress
  24. from dataclasses import dataclass, field, replace
  25. from pathlib import Path
  26. from typing import Dict, List, Optional, Tuple
  27. from utils import atomic_json_write, atomic_write_text
  28. logger = logging.getLogger(__name__)
  29. _RUN_TIMEOUT = 30
  30. _STARTUP_GRACE_SECONDS = 5
  31. # Management API (v0.39): loopback POST /v1/reload hot-swaps the ruleset. Bearer key minted at
  32. # setup (0600 at <proxy>/management.token), injected under this env name; empty => daemon refuses to start.
  33. _MGMT_API_KEY_ENV = "HERMES_IRON_PROXY_MGMT_KEY"
  34. _MGMT_PORT_OFFSET = 2 # tunnel_port is CONNECT/MITM, +1 is plain-HTTP forward, +2 is management
  35. _MGMT_RELOAD_TIMEOUT = 15
  36. # HTTPS_PROXY semantics use a single CONNECT tunnel, so only the tunnel listener is exposed.
  37. _DEFAULT_TUNNEL_PORT = 9090
  38. # Hosts allowed by default for AI inference traffic. Anything else is 403'd.
  39. _DEFAULT_ALLOWED_HOSTS: tuple[str, ...] = (
  40. "openrouter.ai", "*.openrouter.ai", "api.openai.com", "api.anthropic.com", "generativelanguage.googleapis.com",
  41. "api.x.ai", "api.mistral.ai", "api.groq.com", "api.together.xyz", "api.deepseek.com", "inference.nousresearch.com",
  42. )
  43. # Provider env-var name -> upstream hosts on which the Authorization Bearer token is swapped.
  44. _BEARER_PROVIDERS: dict[str, tuple[str, ...]] = {
  45. "OPENROUTER_API_KEY": ("openrouter.ai", "*.openrouter.ai"), "OPENAI_API_KEY": ("api.openai.com",),
  46. "GROQ_API_KEY": ("api.groq.com",), "TOGETHER_API_KEY": ("api.together.xyz",),
  47. "DEEPSEEK_API_KEY": ("api.deepseek.com",), "MISTRAL_API_KEY": ("api.mistral.ai",),
  48. "XAI_API_KEY": ("api.x.ai",), "NOUS_API_KEY": ("inference.nousresearch.com",),
  49. }
  50. # Non-Authorization-header providers (v0.39 ``match_headers`` is case-insensitive). ``aliases``
  51. # name the SAME credential and MUST collapse into one mapping: every rule is ``require: true`` and
  52. # two require-rules on one host would reject each other's requests; the sandbox gets the token
  53. # under every name. Authorization is also matched for Anthropic/Azure (SDKs may send Bearer);
  54. # Gemini's ``?key=<token>`` style is covered by match_query.
  55. # Providers whose API authenticates with a NON-Authorization header. iron-proxy v0.39's
  56. # ``secrets.replace.match_headers`` targets arbitrary header names (case-insensitive; confirmed by the
  57. # iron-proxy author on PR #30179 and verified in the pinned v0.39.0 source — ``swapHeaders`` +
  58. # ``parseHeaderMatchers``), so these are first-class swapped providers, not "uncovered". ``aliases`` are
  59. # interchangeable env-var names for the SAME upstream credential (Hermes' auth.py keys Google on both
  60. # GEMINI_API_KEY and GOOGLE_API_KEY). The sandbox receives the minted token under the canonical name AND
  61. # every alias so SDKs reading either work.
  62. _HEADER_AUTH_PROVIDERS: dict[str, dict[str, tuple[str, ...]]] = {
  63. "ANTHROPIC_API_KEY": {"hosts": ("api.anthropic.com",), "match_headers": ("x-api-key", "Authorization"), "aliases": ()},
  64. "AZURE_OPENAI_API_KEY": {"hosts": ("*.openai.azure.com", "*.cognitiveservices.azure.com", "*.services.ai.azure.com"),
  65. "match_headers": ("api-key", "Authorization"), "aliases": ()},
  66. "GEMINI_API_KEY": {"hosts": ("generativelanguage.googleapis.com",), "match_headers": ("x-goog-api-key",), "aliases": ("GOOGLE_API_KEY",)},
  67. }
  68. # Creds that static header replacement can't swap (SigV4, SDK-minted OAuth): warning only.
  69. _NON_BEARER_PROVIDERS: tuple[str, ...] = ("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "GOOGLE_APPLICATION_CREDENTIALS")
  70. # Default SSRF deny list (docs promise: cloud metadata IPs refused regardless of allowlist);
  71. # callers pass [] to disable (hermetic tests only).
  72. _DEFAULT_UPSTREAM_DENY_CIDRS: tuple[str, ...] = (
  73. "127.0.0.0/8", "::1/128", # loopback v4 / v6
  74. "169.254.0.0/16", "fe80::/10", # link-local incl. AWS/GCP/Azure IMDS
  75. "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "fc00::/7", # RFC1918 + IPv6 ULA
  76. "::ffff:0:0/96", # IPv4-mapped IPv6 — else ::ffff:169.254.169.254 bypasses IMDS deny
  77. "100.64.0.0/10", # RFC6598 CGNAT (AWS VPC shared services, k8s pod nets)
  78. "198.18.0.0/15", # RFC2544 benchmark range
  79. )
  80. # Minimal daemon env (SYSTEMROOT/USERPROFILE are Windows); everything else is stripped so
  81. # /proc/<pid>/environ never exposes operator secrets.
  82. _PROXY_SUBPROCESS_ENV_ALLOWLIST: tuple[str, ...] = (
  83. "PATH", "HOME", "TMPDIR", "TZ", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "SSL_CERT_DIR", "SSL_CERT_FILE", "SYSTEMROOT", "USERPROFILE",
  84. )
  85. # Always stripped — these would recurse the proxy through itself or a corporate proxy.
  86. _PROXY_SUBPROCESS_ENV_STRIP: tuple[str, ...] = ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy", "NO_PROXY", "no_proxy")
  87. # SIGKILL doesn't exist on Windows; SIGTERM there is TerminateProcess() — same semantics.
  88. _KILL_SIGNAL = getattr(signal, "SIGKILL", signal.SIGTERM)
  89. # O_NOFOLLOW is POSIX-only; 0 is a no-op flag elsewhere.
  90. _O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
  91. # ``--version`` output keyed by binary path (get_status runs per container create).
  92. _VERSION_CACHE: dict[str, str] = {}
  93. # Nonce planted in the daemon env so ``_pid_alive`` can prove a PID is still *our* binary across
  94. # PID recycling (a fresh process can't inherit our arbitrary env value).
  95. _HERMES_IRON_PROXY_NONCE_ENV = "HERMES_IRON_PROXY_NONCE"
  96. _proxy_nonce: Optional[str] = None
  97. @dataclass
  98. class ProxyStatus:
  99. enabled: bool = False
  100. binary_path: Optional[Path] = None
  101. binary_version: Optional[str] = None
  102. config_path: Optional[Path] = None
  103. ca_cert_path: Optional[Path] = None
  104. pid: Optional[int] = None
  105. listening: bool = False
  106. tunnel_port: int = _DEFAULT_TUNNEL_PORT
  107. warnings: list[str] = field(default_factory=list)
  108. @property
  109. def installed(self) -> bool:
  110. return self.binary_path is not None and self.binary_path.exists()
  111. @property
  112. def configured(self) -> bool:
  113. return bool(self.config_path and self.config_path.exists() and self.ca_cert_path and self.ca_cert_path.exists())
  114. @dataclass
  115. class TokenMapping:
  116. """Sandbox-visible proxy token -> upstream credential lookup. ``real_env_name`` is read from iron-proxy's
  117. OWN env at egress; ``alias_env_names`` are extra SANDBOX names for the same token."""
  118. proxy_token: str
  119. real_env_name: str
  120. upstream_hosts: tuple[str, ...]
  121. match_headers: tuple[str, ...] = ("Authorization",)
  122. alias_env_names: tuple[str, ...] = ()
  123. def _proxy_state_dir_ro() -> Path: # without creating it (status probes, pidfile reads)
  124. from hermes_constants import get_hermes_home
  125. return get_hermes_home() / "proxy"
  126. def _proxy_state_dir() -> Path:
  127. """Proxy state dir (CA key, pidfile, logs), created 0o700; unconditional chmod tightens a pre-existing slack-umask dir."""
  128. (d := _proxy_state_dir_ro()).mkdir(parents=True, exist_ok=True)
  129. with suppress(OSError): # Windows no-op / shared fs we don't own; files still get explicit perms
  130. d.chmod(0o700)
  131. return d
  132. def find_iron_proxy(*, install_if_missing: bool = False) -> Optional[Path]:
  133. """External tools do not require PM platform support; acquire only on a miss."""
  134. if system := shutil.which("iron-proxy"):
  135. return Path(system)
  136. import pm
  137. selected = pm.installed_package("iron-proxy")
  138. if selected is not None:
  139. return selected.binary
  140. if install_if_missing:
  141. try:
  142. pm.ensure("iron-proxy")
  143. return pm.installed_package("iron-proxy").binary
  144. except Exception as exc:
  145. logger.warning("iron-proxy auto-install failed: %s", exc)
  146. return None
  147. def install_iron_proxy(*, force: bool = False) -> Path:
  148. """Explicit setup/repair; PM verifies and repairs existing entries too."""
  149. import pm
  150. pm.ensure("iron-proxy", explicit=True)
  151. target = pm.installed_package("iron-proxy").binary
  152. _VERSION_CACHE.pop(str(target), None)
  153. return target
  154. def _verify_checksums_signature(tmp: Path, checksum_path: Path) -> bool:
  155. """Best-effort GPG check of checksums.txt in an ephemeral keyring. False (with a warning) when gpg or the signature
  156. assets are unavailable — SHA-256 stays enforced, gpg is never a hard dependency. Raises ONLY on a present-but-bad signature."""
  157. if not (gpg := shutil.which("gpg")):
  158. logger.warning("gpg not found on PATH — skipping iron-proxy release-signature verification (SHA-256 checksum check still enforced).")
  159. return False
  160. sig_path, pubkey_path = tmp / "checksums.txt.asc", tmp / "public-key.asc"
  161. if not sig_path.is_file() or not pubkey_path.is_file():
  162. logger.warning("iron-proxy release signature assets unavailable — skipping GPG verification (SHA-256 checksum check still enforced).")
  163. return False
  164. with tempfile.TemporaryDirectory(prefix="hermes-iron-signature-") as gnupg_home:
  165. gpg_base = [gpg, "--homedir", gnupg_home, "--batch", "--no-tty"]
  166. if (imp := _run([*gpg_base, "--import", str(pubkey_path)], timeout=60)).returncode != 0:
  167. logger.warning("Could not import iron-proxy signing key — skipping GPG verification (SHA-256 still enforced): %s", imp.stderr.decode("utf-8", "replace")[:200])
  168. return False
  169. if (verify := _run([*gpg_base, "--verify", str(sig_path), str(checksum_path)], timeout=60)).returncode != 0:
  170. raise RuntimeError(
  171. f"iron-proxy checksums.txt failed GPG signature verification — refusing to install (possible release-channel tampering). gpg: {verify.stderr.decode('utf-8', 'replace')[:300]}"
  172. )
  173. logger.info("Verified iron-proxy checksums.txt GPG signature.")
  174. return True
  175. def allowlisted_env() -> dict[str, str]:
  176. """Infrastructure-only env (PATH, HOME, locale) — never the operator's secrets."""
  177. return {n: os.environ[n] for n in _PROXY_SUBPROCESS_ENV_ALLOWLIST if n in os.environ}
  178. def _run(argv: list[str], *, timeout: int, text: bool = False, **kwargs) -> subprocess.CompletedProcess:
  179. if text:
  180. kwargs.update(text=True, encoding="utf-8", errors="replace")
  181. return subprocess.run(argv, capture_output=True, timeout=timeout, stdin=subprocess.DEVNULL, **kwargs) # noqa: PLW1510 -- forwarding wrapper: callers pass subprocess kwargs via **kwargs (check may arrive through it); an explicit check=False would raise TypeError
  182. def iron_proxy_version(binary: Path) -> str:
  183. """``iron-proxy --version`` output, stripped and cached by path. Empty on failure."""
  184. if (key := str(binary)) in _VERSION_CACHE:
  185. return _VERSION_CACHE[key]
  186. try:
  187. # Scrubbed env: a PATH-resolved binary must not see the host's API keys.
  188. res = _run([str(binary), "--version"], timeout=_RUN_TIMEOUT, text=True, env=allowlisted_env())
  189. except (OSError, subprocess.TimeoutExpired):
  190. return ""
  191. if out := (res.stdout or res.stderr or "").strip(): # never cache empty output — it would poison status for the process lifetime
  192. _VERSION_CACHE[key] = out
  193. return out
  194. def _write_private_file(path: Path, data: bytes) -> None:
  195. """Create/truncate ``path`` 0o600 from the first byte (no chmod-after TOCTOU), O_NOFOLLOW against a planted
  196. symlink, fchmod to tighten a pre-existing file."""
  197. fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC | _O_NOFOLLOW, 0o600)
  198. try:
  199. with suppress(OSError, AttributeError):
  200. os.fchmod(fd, 0o600)
  201. os.write(fd, data)
  202. finally:
  203. os.close(fd)
  204. def _fd_owned_by_us(fd: int) -> bool:
  205. """False iff the open file is owned by another uid (same threat model as the pidfile)."""
  206. try:
  207. st = os.fstat(fd)
  208. return not (hasattr(os, "getuid") and st.st_uid != os.getuid())
  209. except AttributeError:
  210. return True # Windows
  211. def ensure_ca_cert(*, force: bool = False) -> tuple[Path, Path]:
  212. """Generate (or return existing) 10-year CA cert + key via the host ``openssl``."""
  213. state = _proxy_state_dir()
  214. ca_crt, ca_key = state / "ca.crt", state / "ca.key"
  215. if ca_crt.exists() and ca_key.exists() and not force:
  216. return ca_crt, ca_key
  217. if shutil.which("openssl") is None:
  218. raise RuntimeError("openssl not found on PATH. Install OpenSSL (apt: `openssl`, brew: `openssl`) to generate the iron-proxy CA cert.")
  219. with tempfile.TemporaryDirectory(prefix="hermes-proxy-ca-") as tmpdir:
  220. tmp_key, tmp_crt = Path(tmpdir) / "ca.key", Path(tmpdir) / "ca.crt"
  221. _run(["openssl", "genrsa", "-out", str(tmp_key), "4096"], timeout=60, check=True)
  222. _run(["openssl", "req", "-x509", "-new", "-nodes", "-key", str(tmp_key), "-sha256", "-days", "3650", "-subj", "/CN=hermes iron-proxy CA",
  223. "-addext", "basicConstraints=critical,CA:TRUE", "-addext", "keyUsage=critical,keyCertSign", "-out", str(tmp_crt)], timeout=60, check=True)
  224. # Key: stage 0o600 against a fresh inode, then atomically rename into place.
  225. key_staged = ca_key.with_suffix(ca_key.suffix + ".staged")
  226. key_staged.unlink(missing_ok=True)
  227. _write_private_file(key_staged, tmp_key.read_bytes())
  228. os.replace(key_staged, ca_key)
  229. # Cert is public — 0o644 matches typical PEM layout.
  230. ca_crt.write_bytes(tmp_crt.read_bytes())
  231. os.chmod(ca_crt, 0o644)
  232. logger.info("Generated iron-proxy CA at %s", ca_crt)
  233. return ca_crt, ca_key
  234. def mint_proxy_token(prefix: str = "hermes-proxy") -> str:
  235. """Opaque token: recognizable prefix + 128-bit random hex suffix (iron-proxy matches exactly)."""
  236. return f"{prefix}-{hashlib.sha256(os.urandom(32)).hexdigest()[:32]}"
  237. def _read_text_or_none(p: Path) -> Optional[str]:
  238. """Stripped file contents, or None when missing/unreadable/empty."""
  239. try:
  240. return p.read_text(encoding="utf-8-sig").strip() or None
  241. except OSError:
  242. return None
  243. def _management_token_path() -> Path:
  244. """Management-token location; resolving it never creates or changes state."""
  245. return _proxy_state_dir_ro() / "management.token"
  246. def ensure_management_token(*, force: bool = False) -> str:
  247. """Return the management-API bearer key, minting it on first call.
  248. Stored at the path from :func:`_management_token_path` with 0600 perms.
  249. The daemon receives it via the ``HERMES_IRON_PROXY_MGMT_KEY`` env var
  250. (named in the generated config's ``management.api_key_env``);
  251. ``hermes egress reload`` reads the same file to authenticate.
  252. """
  253. _proxy_state_dir()
  254. p = _management_token_path()
  255. if not force and (existing := _read_text_or_none(p)):
  256. return existing
  257. token = mint_proxy_token(prefix="hermes-mgmt")
  258. _write_private_file(p, token.encode("utf-8"))
  259. return token
  260. def _yaml():
  261. """Shared YAML helpers or None (not a hard requirement for proxy discovery)."""
  262. try:
  263. import hermes_yaml as yaml
  264. return yaml
  265. except ImportError:
  266. return None
  267. def _parse_listen(listen) -> Optional[tuple[str, int]]:
  268. """``"host:port"`` -> ``(host, port)``; empty host means loopback."""
  269. if not isinstance(listen, str) or ":" not in listen:
  270. return None
  271. host, _, port_s = listen.rpartition(":")
  272. try:
  273. port = int(port_s)
  274. except ValueError:
  275. return None
  276. return (host or "127.0.0.1", port)
  277. def _config_listen(section: str, *keys: str, config_path: Optional[Path] = None) -> Optional[tuple[str, int]]:
  278. """``(host, port)`` from the first truthy ``proxy.yaml[section][key]``, or None (also when file/ruamel.yaml is missing)."""
  279. yaml, data = _yaml(), {}
  280. if yaml is not None:
  281. with suppress(OSError, yaml.YAMLError):
  282. data = yaml.safe_load((config_path or (_proxy_state_dir_ro() / "proxy.yaml")).read_text(encoding="utf-8-sig")) or {}
  283. block = data.get(section) or {}
  284. return _parse_listen(next((block[k] for k in keys if block.get(k)), ""))
  285. def _read_management_listen_from_config(config_path: Optional[Path] = None) -> Optional[tuple[str, int]]:
  286. return _config_listen("management", "listen", config_path=config_path)
  287. def _probe_target() -> tuple[str, int]:
  288. """Configured bind host/port to probe — on Linux the docker bridge, where a loopback connect would report a healthy
  289. daemon as down. ``tunnel_listen`` (CONNECT/MITM) falls back to ``http_listen`` for pre-listener-role-split configs."""
  290. return _config_listen("proxy", "tunnel_listen", "http_listen") or ("127.0.0.1", _DEFAULT_TUNNEL_PORT)
  291. # Management-API error status -> operator message (422 = validation rejected, ruleset unchanged; 401 = daemon started with another management.token).
  292. _RELOAD_HTTP_ERRORS = {
  293. 422: "iron-proxy rejected the new config (validation failed; the running ruleset is unchanged): {body}",
  294. 401: "management API rejected our key (401). The running daemon was started with a different management.token — run `hermes egress restart`.",
  295. }
  296. def reload_proxy() -> bool:
  297. """``POST /v1/reload`` (validation failures leave the running config untouched); actionable RuntimeError on any failure."""
  298. if not (pid := _read_pid()) or not _pid_alive(pid):
  299. raise RuntimeError("iron-proxy is not running — nothing to reload. Run `hermes egress start`.")
  300. if (mgmt := _read_management_listen_from_config()) is None:
  301. raise RuntimeError(
  302. "The generated proxy.yaml has no management listener (written before reload support). Re-run `hermes egress setup` and use `hermes egress restart` this one time."
  303. )
  304. if not (token := _read_text_or_none(_management_token_path())):
  305. raise RuntimeError("management.token is missing — re-run `hermes egress setup`, then `hermes egress restart`.")
  306. host, port = mgmt
  307. req = urllib.request.Request(f"http://{host}:{port}/v1/reload", method="POST", headers={"Authorization": f"Bearer {token}"}, data=b"")
  308. try:
  309. with urllib.request.urlopen(req, timeout=_MGMT_RELOAD_TIMEOUT) as resp:
  310. if resp.status == 200:
  311. return True
  312. raise RuntimeError(f"management API returned unexpected status {resp.status}")
  313. except urllib.error.HTTPError as exc:
  314. body = ""
  315. with suppress(OSError):
  316. body = exc.read().decode("utf-8", errors="replace")[:500]
  317. message = _RELOAD_HTTP_ERRORS.get(exc.code, "management reload failed (HTTP {code}): {body}")
  318. raise RuntimeError(message.format(code=exc.code, body=body)) from exc
  319. except (urllib.error.URLError, OSError) as exc:
  320. # A daemon started from a pre-management config is alive but has no listener.
  321. raise RuntimeError(
  322. f"could not reach the management API at {host}:{port} ({exc}). If the daemon was started before reload support, run `hermes egress restart` once."
  323. ) from exc
  324. def _default_http_listen(tunnel_port: int) -> list[str]:
  325. """Single bind (v0.39 allows one): docker bridge on Linux (what ``host.docker.internal`` resolves to; loopback is
  326. unreachable from containers), loopback on Docker Desktop (VPNkit). NEVER 0.0.0.0: a LAN peer with a leaked
  327. sandbox token could spend the operator's API quota."""
  328. if platform.system() == "Linux":
  329. if (bridge_ip := _detect_docker_bridge_ip()) and bridge_ip != "127.0.0.1":
  330. return [f"{bridge_ip}:{tunnel_port}"]
  331. logger.warning(
  332. "No docker bridge (docker0) detected — binding iron-proxy to loopback only. Docker sandboxes will NOT be able to reach the proxy until it is restarted with docker running."
  333. )
  334. return [f"127.0.0.1:{tunnel_port}"]
  335. def _detect_docker_bridge_ip() -> Optional[str]:
  336. """docker0 IPv4 via ``ip -4 addr show docker0``, or None. SECURITY: validated through
  337. :mod:`ipaddress` so a hostile ``ip`` shim can't inject 0.0.0.0/loopback/multicast/link-local/public."""
  338. try:
  339. res = _run(["ip", "-4", "-o", "addr", "show", "docker0"], timeout=2, text=True)
  340. except (OSError, subprocess.TimeoutExpired):
  341. return None
  342. # Expected: "<n>: docker0 inet 172.17.0.1/16 ..." — first inet token (per line) wins.
  343. lines = (line.split() for line in res.stdout.splitlines()) if res.returncode == 0 else ()
  344. candidate = next((parts[parts.index("inet") + 1].split("/")[0] for parts in lines if "inet" in parts[:-1]), None)
  345. try:
  346. addr = ipaddress.IPv4Address(candidate) # None/"" raise too
  347. except (ipaddress.AddressValueError, ValueError):
  348. return None
  349. if addr.is_unspecified or addr.is_loopback or addr.is_multicast or addr.is_reserved or addr.is_link_local or addr.is_global:
  350. logger.warning("Refusing suspicious docker bridge IP %s reported by `ip`; skipping bridge bind.", candidate)
  351. return None
  352. return str(addr)
  353. def build_proxy_config(
  354. *, mappings: list[TokenMapping], ca_cert: Path, ca_key: Path, tunnel_port: int = _DEFAULT_TUNNEL_PORT, audit_log: Optional[Path] = None,
  355. allowed_hosts: Optional[list[str]] = None, upstream_deny_cidrs: Optional[list[str]] = None, http_listen: Optional[list[str]] = None,
  356. ) -> dict:
  357. """iron-proxy YAML config dict (v0.39.0 schema). Real secrets come from iron-proxy's OWN env (``source: {type: env}``);
  358. the sandbox never sees them. ``upstream_deny_cidrs=None`` = default SSRF deny list, ``[]`` opts out.
  359. ``audit_log`` is forward-compat only (v0.39 rejects ``audit_path``)."""
  360. hosts: list[str] = list(allowed_hosts or _DEFAULT_ALLOWED_HOSTS)
  361. for h in (h for m in mappings for h in m.upstream_hosts):
  362. if h not in hosts:
  363. hosts.append(h)
  364. deny_cidrs = list(_DEFAULT_UPSTREAM_DENY_CIDRS if upstream_deny_cidrs is None else upstream_deny_cidrs)
  365. # Query scan covers ``?key=<token>`` SDKs; body inspection deliberately off. ``require`` fails
  366. # closed: an allowlisted-host request WITHOUT the proxy token is rejected, so a real key sent
  367. # directly can't cross the boundary.
  368. secrets_rules = [{
  369. "source": {"type": "env", "var": m.real_env_name},
  370. "replace": {
  371. "proxy_value": m.proxy_token, "match_headers": list(m.match_headers or ("Authorization",)),
  372. "match_query": True, "match_body": False, "require": True,
  373. },
  374. "rules": [{"host": h} for h in m.upstream_hosts],
  375. } for m in mappings]
  376. # ONE string per listener field. tunnel_listen is the CONNECT+MITM listener sandboxes reach via
  377. # HTTPS_PROXY (a CONNECT to http_listen is forwarded upstream and 400s); http_listen is plain-HTTP
  378. # forward on tunnel_port+1.
  379. primary_listen = (list(http_listen) if http_listen else _default_http_listen(tunnel_port) or [f"127.0.0.1:{tunnel_port}"])[0]
  380. bind_host = primary_listen.rsplit(":", 1)[0] or "127.0.0.1"
  381. return {
  382. # Required by the parser; tunnel-only mode never binds an exposed DNS port.
  383. "dns": {"listen": "127.0.0.1:0", "proxy_ip": "127.0.0.1"},
  384. "proxy": {
  385. # Both bind the docker bridge on Linux / loopback on Docker Desktop — NEVER 0.0.0.0.
  386. "tunnel_listen": primary_listen, "http_listen": f"{bind_host}:{tunnel_port + 1}",
  387. "https_listen": "127.0.0.1:0", # direct-TLS listener is not exposed
  388. "max_request_body_bytes": 16 * 1024 * 1024, "max_response_body_bytes": 0,
  389. "upstream_response_header_timeout": "120s", "upstream_deny_cidrs": deny_cidrs,
  390. },
  391. # v0.39 defaults metrics to :9090 (our default tunnel_port) — pin to an ephemeral loopback port.
  392. "metrics": {"listen": "127.0.0.1:0"},
  393. # Loopback only: sandboxes must never reach the management surface.
  394. "management": {"listen": f"127.0.0.1:{tunnel_port + _MGMT_PORT_OFFSET}", "api_key_env": _MGMT_API_KEY_ENV},
  395. "tls": {"ca_cert": str(ca_cert), "ca_key": str(ca_key), "cert_cache_size": 1000, "leaf_cert_expiry_hours": 168},
  396. "transforms": [{"name": "allowlist", "config": {"domains": hosts}}, {"name": "secrets", "config": {"secrets": secrets_rules}}],
  397. "log": {"level": "info"},
  398. }
  399. def _open_private_append(path: Path, *, strict_chmod: bool) -> int:
  400. """O_APPEND|O_CREAT 0o600 + O_NOFOLLOW (planted symlinks refused); fchmod tightens a pre-existing
  401. file (failure fatal iff ``strict_chmod``). Raises OSError; caller owns the fd."""
  402. fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_APPEND | _O_NOFOLLOW, 0o600)
  403. try:
  404. os.fchmod(fd, 0o600)
  405. except OSError:
  406. if strict_chmod:
  407. os.close(fd)
  408. raise
  409. return fd
  410. def ensure_audit_log(audit_path: Path) -> None:
  411. """Pre-create the audit log 0o600 (forward-compat: v0.39 never writes it); RuntimeError on any OSError."""
  412. try:
  413. os.close(_open_private_append(audit_path, strict_chmod=True))
  414. except OSError as exc:
  415. raise RuntimeError(
  416. f"Refusing to start: could not pre-create audit log {audit_path} with restrictive permissions ({exc}). Move or chmod any existing file at that path and retry."
  417. ) from exc
  418. def write_proxy_config(config: dict) -> Path:
  419. """Serialize the config dict to ``<hermes_home>/proxy/proxy.yaml`` (safe_dump, no Python tags).
  420. The file holds proxy tokens: written 0600 from creation, never at process umask."""
  421. if (yaml := _yaml()) is None:
  422. raise RuntimeError("ruamel.yaml is required to write the iron-proxy config but is not installed.")
  423. path = _proxy_state_dir() / "proxy.yaml"
  424. atomic_write_text(path, yaml.safe_dump(config, default_flow_style=False, sort_keys=False), mode=0o600)
  425. return path
  426. def write_mappings(mappings: list[TokenMapping]) -> Path:
  427. """Persist sandbox-visible tokens to ``mappings.json`` (read by the Docker backend, not iron-proxy)."""
  428. payload = {"version": 1, "tokens": [{
  429. "proxy_token": m.proxy_token, "env_name": m.real_env_name, "upstream_hosts": list(m.upstream_hosts),
  430. "match_headers": list(m.match_headers), "alias_env_names": list(m.alias_env_names),
  431. } for m in mappings]}
  432. path = _proxy_state_dir() / "mappings.json"
  433. atomic_json_write(path, payload, mode=0o600)
  434. return path
  435. def load_mappings() -> list[TokenMapping]:
  436. """Read mappings.json, if it exists. Empty list on any error."""
  437. if not (f := _proxy_state_dir() / "mappings.json").exists():
  438. return []
  439. try:
  440. payload = json.loads(f.read_text(encoding="utf-8-sig"))
  441. except (OSError, json.JSONDecodeError) as exc:
  442. logger.warning("Failed to read iron-proxy mappings.json: %s", exc)
  443. return []
  444. out: list[TokenMapping] = []
  445. for item in payload.get("tokens", []):
  446. with suppress(KeyError, TypeError): # pre-header-auth files load with the bearer defaults they were written under
  447. out.append(TokenMapping(item["proxy_token"], item["env_name"], tuple(item.get("upstream_hosts") or ()),
  448. tuple(item.get("match_headers") or ("Authorization",)), tuple(item.get("alias_env_names") or ())))
  449. return out
  450. def discover_provider_mappings(*, available_env_names: Optional[list[str]] = None) -> list[TokenMapping]:
  451. """One TokenMapping per known provider whose env var is set (bearer providers first). Canonical OR any alias
  452. present -> ONE mapping on the canonical name (the subprocess-env builder mirrors aliases).
  453. ``available_env_names`` (Bitwarden adapter) overrides the non-empty names in the host env."""
  454. names = set(available_env_names) if available_env_names is not None else {k for k, v in os.environ.items() if v}
  455. specs = [(n, h, ("Authorization",), ()) for n, h in _BEARER_PROVIDERS.items()] + [
  456. (n, tuple(s["hosts"]), tuple(s["match_headers"]), tuple(s.get("aliases") or ())) for n, s in _HEADER_AUTH_PROVIDERS.items()
  457. ]
  458. return [
  459. TokenMapping(mint_proxy_token(prefix=env_name.lower().replace("_api_key", "")), env_name, hosts, headers, aliases)
  460. for env_name, hosts, headers, aliases in specs
  461. if env_name in names or any(a in names for a in aliases)
  462. ]
  463. def discover_uncovered_providers(*, available_env_names: Optional[list[str]] = None) -> list[str]:
  464. """Env names of recognized providers the proxy can't swap (SigV4 / SDK-minted OAuth)."""
  465. names = set(available_env_names) if available_env_names is not None else {k for k, v in os.environ.items() if v}
  466. return [n for n in _NON_BEARER_PROVIDERS if n in names]
  467. def merge_mappings(*, existing: list[TokenMapping], discovered: list[TokenMapping], rotate: bool = False) -> list[TokenMapping]:
  468. """Existing tokens are preserved (containers baked with them keep working), hosts/headers/aliases refresh
  469. from ``discovered``; ``rotate=True`` re-mints; undiscovered providers drop."""
  470. by_name = {} if rotate else {m.real_env_name: m for m in existing}
  471. return [replace(d, proxy_token=by_name[d.real_env_name].proxy_token) if d.real_env_name in by_name else d for d in discovered]
  472. def _pidfile() -> Path:
  473. return _proxy_state_dir() / "iron-proxy.pid"
  474. def _read_pid() -> Optional[int]:
  475. try:
  476. pid = int((_proxy_state_dir_ro() / "iron-proxy.pid").read_text(encoding="utf-8-sig", errors="replace").strip())
  477. except (OSError, ValueError):
  478. return None
  479. return pid if pid > 0 else None
  480. def _pid_proc_starttime(pid: int) -> Optional[str]:
  481. """/proc/<pid>/stat starttime (field 22) on Linux, else None — cheap PID-recycling detector."""
  482. try:
  483. text = Path(f"/proc/{pid}/stat").read_text(encoding="utf-8")
  484. except OSError:
  485. return None
  486. # comm may contain spaces/parens, so split after the LAST ")"; field 22 -> tail index 19.
  487. fields = text[rparen + 1:].split() if (rparen := text.rfind(")")) >= 0 else []
  488. return fields[19] if len(fields) > 19 else None
  489. def _persisted_nonce_path() -> Path:
  490. """On-disk nonce sibling of the pidfile, so stop/status in a later CLI process can still defeat PID recycling."""
  491. return _proxy_state_dir_ro() / "iron-proxy.nonce"
  492. def _read_persisted_nonce() -> Optional[str]:
  493. """Nonce from disk, or None if missing/unreadable/empty/not owned by us (callers fall back to argv0
  494. matching). O_NOFOLLOW: this read decides whether stop_proxy SIGKILLs a PID."""
  495. try:
  496. fd = os.open(str(_persisted_nonce_path()), os.O_RDONLY | _O_NOFOLLOW)
  497. except OSError:
  498. return None
  499. try:
  500. if not _fd_owned_by_us(fd):
  501. return None
  502. return os.read(fd, 256).decode("utf-8", errors="ignore").strip() or None
  503. finally:
  504. os.close(fd)
  505. def _pid_alive(pid: int) -> bool:
  506. """True iff ``pid`` is alive AND an iron-proxy process. PID-reuse defense, in priority order: nonce in
  507. /proc/<pid>/environ, argv[0] basename in /proc/<pid>/cmdline, ``ps -o comm=`` basename (a loose
  508. ``"iron-proxy" in cmdline`` would hit ``tail iron-proxy.log``)."""
  509. if pid <= 0:
  510. return False
  511. try:
  512. # psutil when available: os.kill(pid, 0) on Windows is a HARD kill (bpo-14484).
  513. import psutil # type: ignore
  514. if not psutil.pid_exists(pid):
  515. return False
  516. except ImportError:
  517. if platform.system() != "Windows":
  518. try:
  519. os.kill(pid, 0) # windows-footgun: ok — POSIX-only branch
  520. except (ProcessLookupError, PermissionError, OSError):
  521. return False
  522. # Strong proof: nonce from this process's start_proxy and/or the on-disk sibling file.
  523. nonce_candidates = [n for n in dict.fromkeys((_proxy_nonce, _read_persisted_nonce())) if n]
  524. if nonce_candidates:
  525. with suppress(OSError):
  526. env_bytes = Path(f"/proc/{pid}/environ").read_bytes()
  527. if any(f"{_HERMES_IRON_PROXY_NONCE_ENV}={n}".encode() in env_bytes for n in nonce_candidates):
  528. return True
  529. if Path("/proc/self/cmdline").exists(): # Linux: /proc answers for every pid
  530. try:
  531. cmdline = Path(f"/proc/{pid}/cmdline").read_bytes()
  532. except (FileNotFoundError, ProcessLookupError):
  533. return False # exited since the liveness probe; `ps` would fail and read as alive below
  534. except OSError:
  535. cmdline = None
  536. if cmdline is not None:
  537. return os.path.basename(cmdline.split(b"\x00")[0].decode("utf-8", errors="ignore")).startswith("iron-proxy")
  538. with suppress(OSError, subprocess.TimeoutExpired): # macOS / non-Linux fallback
  539. res = _run(["ps", "-p", str(pid), "-o", "comm="], timeout=2, text=True)
  540. if res.returncode == 0:
  541. return os.path.basename((res.stdout or "").strip()).startswith("iron-proxy")
  542. # Exotic platforms: if the OS says alive, believe it.
  543. return True
  544. def start_proxy(
  545. *, binary: Optional[Path] = None, config_path: Optional[Path] = None, extra_env: Optional[dict[str, str]] = None,
  546. install_if_missing: bool = True, refresh_secrets_from_bitwarden: bool = False, bitwarden_config: Optional[dict] = None,
  547. ) -> ProxyStatus:
  548. """Spawn iron-proxy as a managed background subprocess (idempotent if already running). ``refresh_secrets_from_bitwarden``
  549. re-fetches secrets from BWS — the ``credential_source: bitwarden`` rotation promise."""
  550. global _proxy_nonce
  551. if (existing := _read_pid()) and _pid_alive(existing):
  552. return get_status()
  553. if (bin_path := binary or find_iron_proxy(install_if_missing=install_if_missing)) is None:
  554. raise RuntimeError("iron-proxy binary not available — run `hermes egress install`.")
  555. if not (cfg := config_path or (_proxy_state_dir() / "proxy.yaml")).exists():
  556. raise RuntimeError(f"iron-proxy config not found at {cfg}. Run `hermes egress setup` first.")
  557. # Minimal env: os.environ.copy() would expose every operator secret via /proc/<pid>/environ.
  558. env = _build_proxy_subprocess_env(extra_env=extra_env, refresh_from_bitwarden=refresh_secrets_from_bitwarden, bitwarden_config=bitwarden_config)
  559. # v0.39 validates api_key_env is non-empty when management.listen is set.
  560. if _read_management_listen_from_config(cfg) is not None:
  561. env[_MGMT_API_KEY_ENV] = ensure_management_token()
  562. # Per-start nonce for PID-recycling defense; module-global is fine (one proxy per process).
  563. _proxy_nonce = hashlib.sha256(os.urandom(16)).hexdigest()
  564. env[_HERMES_IRON_PROXY_NONCE_ENV] = _proxy_nonce
  565. log_path = _proxy_state_dir() / "iron-proxy.log"
  566. proc = _spawn_daemon(bin_path, cfg, env, log_path)
  567. # Pidfile BEFORE the listening poll so `hermes egress stop` can clean an orphan if the parent dies mid-poll.
  568. pidfile = _pidfile()
  569. try:
  570. _write_pidfile_safely(pidfile, proc.pid)
  571. except RuntimeError:
  572. _kill_and_wait(proc, grace_seconds=2)
  573. raise
  574. def _abort(msg: str, *, kill: bool) -> RuntimeError:
  575. tail = _tail_log(log_path, lines=20)
  576. if kill:
  577. _kill_and_wait(proc, grace_seconds=2)
  578. pidfile.unlink(missing_ok=True)
  579. return RuntimeError(f"{msg}Last log lines:\n{tail}")
  580. def _interrupt_handler(_signum, _frame): # pragma: no cover - signal path
  581. _kill_and_wait(proc, grace_seconds=2) # Ctrl-C while waiting must not leak an orphan holding the port
  582. pidfile.unlink(missing_ok=True)
  583. raise KeyboardInterrupt()
  584. _exited_error = lambda: _abort(f"iron-proxy exited immediately (code {proc.returncode}). ", kill=False)
  585. # Probe the CONFIGURED bind host (on Linux the docker bridge, where loopback never connects).
  586. probe_host, tunnel_port = _probe_target()
  587. with _interrupt_guard(_interrupt_handler):
  588. listening = _await_listening(proc, probe_host, tunnel_port, on_exit=_exited_error)
  589. # Process may have died right at deadline.
  590. if proc.poll() is not None:
  591. raise _exited_error()
  592. # Alive-but-not-listening is a failure: an orphan holding the port breaks every restart.
  593. if not listening:
  594. raise _abort(f"iron-proxy did not bind {probe_host}:{tunnel_port} within {_STARTUP_GRACE_SECONDS}s. Process was killed. ", kill=True)
  595. logger.info("Started iron-proxy pid=%s config=%s", proc.pid, cfg)
  596. return get_status()
  597. @contextmanager
  598. def _interrupt_guard(handler):
  599. """Route SIGINT/SIGTERM to ``handler`` for the block (POSIX main thread only); previous handlers restored after."""
  600. if platform.system() == "Windows" or threading.current_thread() is not threading.main_thread():
  601. yield
  602. return
  603. prev = [(sig, signal.signal(sig, handler)) for sig in (signal.SIGINT, signal.SIGTERM)]
  604. try:
  605. yield
  606. finally:
  607. for sig, old in prev:
  608. signal.signal(sig, old)
  609. def _spawn_daemon(bin_path: Path, cfg: Path, env: dict[str, str], log_path: Path) -> subprocess.Popen:
  610. """Popen with stdout/stderr appended to ``log_path`` (0o600 from the first byte, O_NOFOLLOW so a planted
  611. symlink e.g. to authorized_keys can't receive output, owner-checked). Our log fd closes after Popen — the child has its dup."""
  612. try:
  613. log_fd = _open_private_append(log_path, strict_chmod=False)
  614. except OSError as exc:
  615. raise RuntimeError(f"Refusing to write iron-proxy log {log_path}: {exc}. Remove that path manually and retry.") from exc
  616. if not _fd_owned_by_us(log_fd):
  617. uid = os.fstat(log_fd).st_uid
  618. os.close(log_fd)
  619. raise RuntimeError(f"iron-proxy log {log_path} has unexpected owner uid={uid}; refusing to write.")
  620. try:
  621. # start_new_session is POSIX-only (Windows isn't supported anyway — no upstream binary).
  622. return subprocess.Popen(
  623. [str(bin_path), "-config", str(cfg)], env=env, stdin=subprocess.DEVNULL, stdout=log_fd, stderr=subprocess.STDOUT,
  624. # detached-spawn: ok — a daemon meant to outlive the CLI that started it; `hermes egress stop` ends it (pidfile + nonce)
  625. **({} if platform.system() == "Windows" else {"start_new_session": True}),
  626. )
  627. except OSError as exc:
  628. raise RuntimeError(f"failed to spawn iron-proxy: {exc}") from exc
  629. finally:
  630. with suppress(OSError):
  631. os.close(log_fd)
  632. def _await_listening(proc: subprocess.Popen, host: str, port: int, *, on_exit) -> bool:
  633. """Poll until ``host:port`` accepts or the grace window lapses (do-while: >=1 check even at 0s); raises ``on_exit()`` if the child dies."""
  634. deadline = time.time() + _STARTUP_GRACE_SECONDS
  635. while True:
  636. if proc.poll() is not None:
  637. raise on_exit()
  638. if _port_listening(host, port):
  639. return True
  640. if time.time() >= deadline:
  641. return False
  642. time.sleep(0.1)
  643. def _write_pidfile_safely(pidfile: Path, pid: int) -> None:
  644. """O_EXCL + O_NOFOLLOW + ownership check, then persist the nonce. An existing pidfile is either a concurrent
  645. start (fail cleanly) or a stale crash leftover (unlink and retry once)."""
  646. open_flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_NOFOLLOW
  647. try:
  648. fd = os.open(str(pidfile), open_flags, 0o600)
  649. except FileExistsError:
  650. if (existing_pid := _read_pid()) and _pid_alive(existing_pid):
  651. raise RuntimeError(
  652. f"Another iron-proxy start appears to be in progress (pidfile {pidfile} -> pid {existing_pid}). Run `hermes egress stop` if that proxy is stuck."
  653. )
  654. pidfile.unlink(missing_ok=True)
  655. fd = os.open(str(pidfile), open_flags, 0o600)
  656. except OSError as exc:
  657. # ELOOP from a planted symlink at the pidfile path.
  658. raise RuntimeError(f"Refusing to write pidfile {pidfile}: {exc}. Remove that path manually and retry.") from exc
  659. try:
  660. if not _fd_owned_by_us(fd):
  661. raise RuntimeError(f"pidfile {pidfile} has unexpected owner uid={os.fstat(fd).st_uid}")
  662. os.write(fd, str(pid).encode("utf-8"))
  663. finally:
  664. os.close(fd)
  665. # Best-effort nonce sibling (0o600); without it stop falls back to argv0 matching.
  666. if _proxy_nonce:
  667. with suppress(OSError):
  668. _write_private_file(pidfile.with_suffix(".nonce"), _proxy_nonce.encode("utf-8"))
  669. def _kill_and_wait(proc: subprocess.Popen, *, grace_seconds: int = 2) -> None:
  670. try:
  671. proc.terminate()
  672. except OSError:
  673. return
  674. try:
  675. proc.wait(timeout=grace_seconds)
  676. except subprocess.TimeoutExpired:
  677. with suppress(OSError):
  678. proc.kill()
  679. with suppress(subprocess.TimeoutExpired):
  680. proc.wait(timeout=grace_seconds)
  681. def _build_proxy_subprocess_env(
  682. *, extra_env: Optional[dict[str, str]] = None, refresh_from_bitwarden: bool = False, bitwarden_config: Optional[dict] = None,
  683. ) -> dict[str, str]:
  684. """Allowlisted infra vars + the secrets named in mappings. With ``refresh_from_bitwarden`` and a populated
  685. ``bitwarden_config`` secrets come from BWS (the rotation guarantee); without ``allow_env_fallback`` any BWS
  686. shortfall fails closed instead of keeping stale host-env values."""
  687. env, parent = allowlisted_env(), os.environ
  688. # Forward ONLY mapped secrets; the rule is keyed on the canonical name, so mirror an alias value into it.
  689. mappings = load_mappings()
  690. needed = {m.real_env_name for m in mappings}
  691. alias_sources = {m.real_env_name: m.alias_env_names for m in mappings if m.alias_env_names}
  692. for name in needed:
  693. if (source := name if name in parent else next((a for a in alias_sources.get(name, ()) if parent.get(a)), None)) is not None:
  694. env[name] = parent[source]
  695. if refresh_from_bitwarden and bitwarden_config:
  696. _refresh_secrets_from_bitwarden(env, needed, bitwarden_config, bool(bitwarden_config.get("allow_env_fallback")))
  697. # Caller overrides win (wizard test secrets), then strip proxy-recursion vars regardless.
  698. if extra_env:
  699. env.update(extra_env)
  700. for name in _PROXY_SUBPROCESS_ENV_STRIP:
  701. env.pop(name, None)
  702. env.setdefault("NO_COLOR", "1")
  703. return env
  704. def _bitwarden_shortfall(allow_env_fallback: bool, error: str, warning: str, *args, cause: Optional[BaseException] = None) -> None:
  705. """Raise ``error`` (chained to ``cause`` when given) unless the operator opted into the legacy host-env fallback (then log ``warning``)."""
  706. if not allow_env_fallback:
  707. if cause is not None:
  708. raise RuntimeError(error) from cause
  709. raise RuntimeError(error)
  710. logger.warning(warning, *args)
  711. def _refresh_secrets_from_bitwarden(env: dict[str, str], needed: set, bitwarden_config: dict, allow_env_fallback: bool) -> None:
  712. """Overwrite ``env[needed]`` with fresh (uncached) BWS values; only mapped names are injected so unrelated BWS secrets never leak."""
  713. try:
  714. # Lazy: the bitwarden module isn't importable in every install.
  715. from agent.secret_sources import bitwarden as bw
  716. access_token = os.environ.get(bitwarden_config.get("access_token_env", "BWS_ACCESS_TOKEN"), "").strip()
  717. project_id = bitwarden_config.get("project_id", "")
  718. if not (access_token and project_id):
  719. # Don't interpolate access_token_name — CodeQL treats config values as tainted.
  720. _bitwarden_shortfall(
  721. allow_env_fallback,
  722. "credential_source=bitwarden but the access-token env or project_id is empty. Either set both, switch to "
  723. "credential_source: env, or set `proxy.allow_env_fallback: true` to opt into the legacy fallback behaviour.",
  724. "credential_source=bitwarden but access-token env or project_id is empty — proxy will fall back to parent env (allow_env_fallback=true).",
  725. )
  726. return
  727. secrets, warnings = bw.fetch_bitwarden_secrets(access_token=access_token, project_id=project_id, cache_ttl_seconds=0, use_cache=False)
  728. except ImportError as exc:
  729. # A dependency vanishing between setup and restart must not silently degrade.
  730. _bitwarden_shortfall(
  731. allow_env_fallback,
  732. "Bitwarden refresh module unavailable at proxy start (credential_source=bitwarden with "
  733. "proxy.allow_env_fallback: false). Either fix the import, switch to credential_source: env, or set "
  734. "`proxy.allow_env_fallback: true` to opt into the legacy fallback behaviour.",
  735. "Bitwarden refresh module unavailable at proxy start, falling back to parent env (allow_env_fallback=true): %s", exc, cause=exc,
  736. )
  737. return
  738. missing = sorted(needed - set(secrets))
  739. env.update((n, secrets[n]) for n in needed if n in secrets)
  740. if missing:
  741. _bitwarden_shortfall(
  742. allow_env_fallback,
  743. f"Bitwarden refresh did not return secrets for {missing}. Either add the secrets to your BWS project, switch to "
  744. f"credential_source: env via `hermes egress setup --no-bitwarden`, or set `proxy.allow_env_fallback: true` in "
  745. f"config.yaml to opt into the legacy host-env fallback.",
  746. "Bitwarden refresh did not return secrets for %s — falling back to host env for those names (allow_env_fallback=true).", missing,
  747. )
  748. if warnings: # log only the count: the taint analyzer can't tell bws status text is non-secret
  749. logger.warning("Bitwarden refresh produced %d warning(s); run `hermes secrets bitwarden status` for detail.", len(warnings))
  750. def _forget_daemon() -> None:
  751. global _proxy_nonce
  752. _pidfile().unlink(missing_ok=True)
  753. with suppress(OSError):
  754. _persisted_nonce_path().unlink()
  755. _proxy_nonce = None
  756. def stop_proxy() -> bool:
  757. """Returns True if it was running."""
  758. pid = _read_pid()
  759. if not pid or not _pid_alive(pid):
  760. _forget_daemon()
  761. return False
  762. # Capture starttime BEFORE signalling: if the pid is recycled mid-wait, abort the SIGKILL.
  763. starttime_before = _pid_proc_starttime(pid)
  764. try:
  765. os.kill(pid, signal.SIGTERM)
  766. except ProcessLookupError:
  767. _forget_daemon()
  768. return False
  769. # Up to 5s for graceful exit, then SIGKILL — unless the pid was recycled meanwhile.
  770. deadline = time.time() + 5.0
  771. while time.time() < deadline:
  772. if not _pid_alive(pid):
  773. break
  774. time.sleep(0.1)
  775. else:
  776. starttime_after = _pid_proc_starttime(pid)
  777. if (starttime_before is not None and starttime_after is not None and starttime_before != starttime_after) or not _pid_alive(pid):
  778. logger.warning("iron-proxy pid=%s appears recycled before SIGKILL; not killing.", pid)
  779. else:
  780. with suppress(ProcessLookupError):
  781. os.kill(pid, _KILL_SIGNAL)
  782. _forget_daemon()
  783. logger.info("Stopped iron-proxy pid=%s", pid)
  784. return True
  785. def get_status() -> ProxyStatus:
  786. """Snapshot the proxy state without side effects (called per Docker container create)."""
  787. status = ProxyStatus()
  788. probe_host, status.tunnel_port = _probe_target()
  789. if binary := find_iron_proxy(install_if_missing=False):
  790. status.binary_path, status.binary_version = binary, iron_proxy_version(binary)
  791. state = _proxy_state_dir_ro()
  792. cfg, ca = state / "proxy.yaml", state / "ca.crt"
  793. status.config_path, status.ca_cert_path = (cfg if cfg.exists() else None), (ca if ca.exists() else None)
  794. if (pid := _read_pid()) and _pid_alive(pid):
  795. status.pid, status.listening = pid, _port_listening(probe_host, status.tunnel_port)
  796. return status
  797. def _port_listening(host: str, port: int) -> bool:
  798. import socket
  799. try:
  800. with socket.create_connection((host, port), timeout=0.5):
  801. return True
  802. except OSError:
  803. return False
  804. def _tail_log(path: Path, *, lines: int = 20) -> str:
  805. if not path.exists():
  806. return "(no log file)"
  807. try:
  808. return "\n".join(path.read_bytes()[-8192:].decode("utf-8", errors="replace").splitlines()[-lines:])
  809. except OSError as exc:
  810. return f"(could not read log: {exc})"
  811. def _reset_for_tests() -> None:
  812. global _proxy_nonce
  813. _VERSION_CACHE.clear()
  814. _proxy_nonce = None
  815. __all__ = [
  816. "ProxyStatus", "TokenMapping", "allowlisted_env", "build_proxy_config", "discover_provider_mappings",
  817. "discover_uncovered_providers", "ensure_audit_log", "ensure_ca_cert", "ensure_management_token",
  818. "find_iron_proxy", "get_status", "install_iron_proxy", "iron_proxy_version", "load_mappings",
  819. "merge_mappings", "mint_proxy_token", "reload_proxy", "start_proxy", "stop_proxy",
  820. "write_mappings", "write_proxy_config",
  821. ]