ouyangbo/hermes-agent
1
0
Fork 0
Code Issues Pull Requests Actions 12 Packages Projects Releases Wiki Activity

refactor(agent): iron_proxy/monitoring/outbound_webhooks pass-2 structural cut (helpers unified, single-use helpers inlined, packed literals)

Browse Source
This commit is contained in:
Teknium
2026-09-02 22:44:07 -07:00
parent adb241dfc4
commit 575b54d457
4 changed files with 283 additions and 492 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agent/proxy_sources/iron_proxy.py
+162 -295
View File
@@ -54,9 +54,8 @@ _DEFAULT_TUNNEL_PORT = 9090
# Hosts allowed by default for AI inference traffic. Anything else is 403'd.
_DEFAULT_ALLOWED_HOSTS: Tuple[str, ...] = (
"openrouter.ai", "*.openrouter.ai", "api.openai.com", "api.anthropic.com",
"generativelanguage.googleapis.com", "api.x.ai", "api.mistral.ai", "api.groq.com",
"api.together.xyz", "api.deepseek.com", "inference.nousresearch.com",
"openrouter.ai", "*.openrouter.ai", "api.openai.com", "api.anthropic.com", "generativelanguage.googleapis.com",
"api.x.ai", "api.mistral.ai", "api.groq.com", "api.together.xyz", "api.deepseek.com", "inference.nousresearch.com",
)
# Provider env-var name -> upstream hosts on which the Authorization Bearer token is swapped.
@@ -74,10 +73,8 @@ _BEARER_PROVIDERS: Dict[str, Tuple[str, ...]] = {
# Gemini's ``?key=<token>`` style is covered by match_query.
_HEADER_AUTH_PROVIDERS: Dict[str, Dict[str, Tuple[str, ...]]] = {
"ANTHROPIC_API_KEY": {"hosts": ("api.anthropic.com",), "match_headers": ("x-api-key", "Authorization"), "aliases": ()},
"AZURE_OPENAI_API_KEY": {
"hosts": ("*.openai.azure.com", "*.cognitiveservices.azure.com", "*.services.ai.azure.com"),
"match_headers": ("api-key", "Authorization"), "aliases": (),
},
"AZURE_OPENAI_API_KEY": {"hosts": ("*.openai.azure.com", "*.cognitiveservices.azure.com", "*.services.ai.azure.com"),
"match_headers": ("api-key", "Authorization"), "aliases": ()},
"GEMINI_API_KEY": {"hosts": ("generativelanguage.googleapis.com",), "match_headers": ("x-goog-api-key",), "aliases": ("GOOGLE_API_KEY",)},
}
@@ -95,16 +92,14 @@ _DEFAULT_UPSTREAM_DENY_CIDRS: Tuple[str, ...] = (
"198.18.0.0/15", # RFC2544 benchmark range
)
# Minimal daemon env; everything else is stripped so /proc/<pid>/environ never exposes operator secrets.
# Minimal daemon env (SYSTEMROOT/USERPROFILE are Windows); everything else is stripped so
# /proc/<pid>/environ never exposes operator secrets.
_PROXY_SUBPROCESS_ENV_ALLOWLIST: Tuple[str, ...] = (
"PATH", "HOME", "TMPDIR", "TZ", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "SSL_CERT_DIR", "SSL_CERT_FILE",
"SYSTEMROOT", "USERPROFILE", # Windows
"PATH", "HOME", "TMPDIR", "TZ", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "SSL_CERT_DIR", "SSL_CERT_FILE", "SYSTEMROOT", "USERPROFILE",
)
# Always stripped — these would recurse the proxy through itself or a corporate proxy.
_PROXY_SUBPROCESS_ENV_STRIP: Tuple[str, ...] = (
"HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy", "NO_PROXY", "no_proxy",
)
_PROXY_SUBPROCESS_ENV_STRIP: Tuple[str, ...] = ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy", "NO_PROXY", "no_proxy")
# SIGKILL doesn't exist on Windows; SIGTERM there is TerminateProcess() — same semantics.
_KILL_SIGNAL = getattr(signal, "SIGKILL", signal.SIGTERM)
@@ -122,7 +117,6 @@ _proxy_nonce: Optional[str] = None
@dataclass
class ProxyStatus:
"""Snapshot of the iron-proxy installation + runtime state."""
enabled: bool = False
binary_path: Optional[Path] = None
binary_version: Optional[str] = None
@@ -144,8 +138,8 @@ class ProxyStatus:
@dataclass
class TokenMapping:
"""Sandbox-visible proxy token -> upstream credential lookup. ``real_env_name`` is read from
iron-proxy's OWN env at egress; ``alias_env_names`` are extra SANDBOX names for the same token."""
"""Sandbox-visible proxy token -> upstream credential lookup. ``real_env_name`` is read from iron-proxy's
OWN env at egress; ``alias_env_names`` are extra SANDBOX names for the same token."""
proxy_token: str
real_env_name: str
upstream_hosts: Tuple[str, ...]
@@ -158,17 +152,14 @@ def _hermes_bin_dir() -> Path:
return get_hermes_home() / "bin"
def _proxy_state_dir_ro() -> Path:
"""Proxy state dir without creating it (status probes, pidfile reads)."""
def _proxy_state_dir_ro() -> Path: # without creating it (status probes, pidfile reads)
from hermes_constants import get_hermes_home
return get_hermes_home() / "proxy"
def _proxy_state_dir() -> Path:
"""Proxy state dir (CA key, pidfile, logs), created 0o700; chmod is unconditional so a
pre-existing slack-umask dir gets tightened."""
d = _proxy_state_dir_ro()
d.mkdir(parents=True, exist_ok=True)
"""Proxy state dir (CA key, pidfile, logs), created 0o700; unconditional chmod tightens a pre-existing slack-umask dir."""
(d := _proxy_state_dir_ro()).mkdir(parents=True, exist_ok=True)
with suppress(OSError): # Windows no-op / shared fs we don't own; files still get explicit perms
d.chmod(0o700)
return d
@@ -180,16 +171,12 @@ def _platform_binary_name() -> str:
def _platform_asset_name() -> str:
"""Map (uname, arch) -> ``iron-proxy_<version>_<os>_<arch>.tar.gz``; no Windows builds upstream."""
system = platform.system()
machine = platform.machine().lower()
os_name = {"Linux": "linux", "Darwin": "darwin"}.get(system)
if os_name:
system, machine = platform.system(), platform.machine().lower()
if os_name := {"Linux": "linux", "Darwin": "darwin"}.get(system):
arch = "arm64" if machine in ("arm64", "aarch64") else "amd64"
return f"iron-proxy_{_IRON_PROXY_VERSION}_{os_name}_{arch}.tar.gz"
if system == "Windows":
raise RuntimeError(
f"iron-proxy does not ship native Windows binaries as of v{_IRON_PROXY_VERSION}. Run the proxy on a Linux/macOS host, or inside WSL."
)
raise RuntimeError(f"iron-proxy does not ship native Windows binaries as of v{_IRON_PROXY_VERSION}. Run the proxy on a Linux/macOS host, or inside WSL.")
raise RuntimeError(f"Unsupported platform for iron-proxy auto-install: {system} {machine}")
@@ -198,8 +185,7 @@ def find_iron_proxy(*, install_if_missing: bool = False) -> Optional[Path]:
managed = _hermes_bin_dir() / _platform_binary_name()
if managed.exists() and os.access(managed, os.X_OK):
return managed
system = shutil.which("iron-proxy")
if system:
if system := shutil.which("iron-proxy"):
return Path(system)
if not install_if_missing:
return None
@@ -212,23 +198,19 @@ def find_iron_proxy(*, install_if_missing: bool = False) -> Optional[Path]:
def install_iron_proxy(*, force: bool = False) -> Path:
"""Download, verify, and install the pinned binary; raises on any failure."""
bin_dir = _hermes_bin_dir()
bin_dir.mkdir(parents=True, exist_ok=True)
(bin_dir := _hermes_bin_dir()).mkdir(parents=True, exist_ok=True)
target = bin_dir / _platform_binary_name()
if target.exists() and not force:
return target
asset_name = _platform_asset_name()
with tempfile.TemporaryDirectory(prefix="hermes-iron-proxy-") as tmpdir:
tmp = Path(tmpdir)
archive_path = tmp / asset_name
checksum_path = tmp / _IRON_PROXY_CHECKSUM_NAME
archive_path, checksum_path = (tmp := Path(tmpdir)) / asset_name, tmp / _IRON_PROXY_CHECKSUM_NAME
logger.info("Downloading %s", f"{_IRON_PROXY_RELEASE_BASE}/{asset_name}")
_release_asset(asset_name, archive_path)
_release_asset(_IRON_PROXY_CHECKSUM_NAME, checksum_path)
# Best-effort GPG check of checksums.txt closes the release-channel tamper gap.
_verify_checksums_signature(tmp, checksum_path)
expected = _expected_sha256(checksum_path, asset_name)
actual = _sha256_file(archive_path)
expected, actual = _expected_sha256(checksum_path, asset_name), _sha256_file(archive_path)
if expected.lower() != actual.lower():
raise RuntimeError(f"Checksum mismatch for {asset_name}: expected {expected}, got {actual}")
with tarfile.open(archive_path, "r:gz") as tf:
@@ -254,8 +236,8 @@ def install_iron_proxy(*, force: bool = False) -> Path:
def _release_asset(name: str, dest: Path) -> None:
"""Download one pinned-release asset to ``dest``; RuntimeError on any URL error."""
url = f"{_IRON_PROXY_RELEASE_BASE}/{name}"
req = urllib.request.Request(url, headers={"User-Agent": "hermes-agent"})
try:
req = urllib.request.Request(url, headers={"User-Agent": "hermes-agent"})
with urllib.request.urlopen(req, timeout=_DOWNLOAD_TIMEOUT) as resp, open(dest, "wb") as f: # noqa: S310
shutil.copyfileobj(resp, f)
except urllib.error.URLError as exc:
@@ -263,11 +245,9 @@ def _release_asset(name: str, dest: Path) -> None:
def _verify_checksums_signature(tmp: Path, checksum_path: Path) -> bool:
"""Best-effort GPG check of checksums.txt in an ephemeral keyring. False (with a warning) when
gpg or the signature assets are unavailable — SHA-256 stays enforced, gpg is never a hard
dependency. Raises ONLY on a present-but-bad signature (tamper signal)."""
gpg = shutil.which("gpg")
if not gpg:
"""Best-effort GPG check of checksums.txt in an ephemeral keyring. False (with a warning) when gpg or the signature
assets are unavailable — SHA-256 stays enforced, gpg is never a hard dependency. Raises ONLY on a present-but-bad signature."""
if not (gpg := shutil.which("gpg")):
logger.warning("gpg not found on PATH — skipping iron-proxy release-signature verification (SHA-256 checksum check still enforced).")
return False
sig_path, pubkey_path = tmp / _IRON_PROXY_CHECKSUM_SIG_NAME, tmp / _IRON_PROXY_PUBKEY_NAME
@@ -275,25 +255,16 @@ def _verify_checksums_signature(tmp: Path, checksum_path: Path) -> bool:
_release_asset(_IRON_PROXY_CHECKSUM_SIG_NAME, sig_path)
_release_asset(_IRON_PROXY_PUBKEY_NAME, pubkey_path)
except RuntimeError as exc:
logger.warning(
"iron-proxy release signature assets unavailable (%s) — skipping GPG verification (SHA-256 checksum check still enforced).", exc,
)
logger.warning("iron-proxy release signature assets unavailable (%s) — skipping GPG verification (SHA-256 checksum check still enforced).", exc)
return False
gnupg_home = tmp / "gnupg"
gnupg_home.mkdir(mode=0o700, exist_ok=True)
(gnupg_home := tmp / "gnupg").mkdir(mode=0o700, exist_ok=True)
gpg_base = [gpg, "--homedir", str(gnupg_home), "--batch", "--no-tty"]
imp = _run([*gpg_base, "--import", str(pubkey_path)], timeout=60)
if imp.returncode != 0:
logger.warning(
"Could not import iron-proxy signing key — skipping GPG verification (SHA-256 still enforced): %s",
imp.stderr.decode("utf-8", "replace")[:200],
)
if (imp := _run([*gpg_base, "--import", str(pubkey_path)], timeout=60)).returncode != 0:
logger.warning("Could not import iron-proxy signing key — skipping GPG verification (SHA-256 still enforced): %s", imp.stderr.decode("utf-8", "replace")[:200])
return False
verify = _run([*gpg_base, "--verify", str(sig_path), str(checksum_path)], timeout=60)
if verify.returncode != 0:
if (verify := _run([*gpg_base, "--verify", str(sig_path), str(checksum_path)], timeout=60)).returncode != 0:
raise RuntimeError(
"iron-proxy checksums.txt failed GPG signature verification — refusing to install (possible release-channel "
f"tampering). gpg: {verify.stderr.decode('utf-8', 'replace')[:300]}"
f"iron-proxy checksums.txt failed GPG signature verification — refusing to install (possible release-channel tampering). gpg: {verify.stderr.decode('utf-8', 'replace')[:300]}"
)
logger.info("Verified iron-proxy checksums.txt GPG signature.")
return True
@@ -309,18 +280,14 @@ def _expected_sha256(checksum_file: Path, asset_name: str) -> str:
def _sha256_file(path: Path) -> str:
h = hashlib.sha256()
with open(path, "rb") as f:
for chunk in iter(lambda: f.read(65536), b""):
h.update(chunk)
return h.hexdigest()
return hashlib.file_digest(f, "sha256").hexdigest()
def _pick_tar_member(tf: tarfile.TarFile, binary_name: str) -> tarfile.TarInfo:
"""Find the binary in the archive (flat or one dir deep); reject abs paths and ``..``."""
candidates = [
m for m in tf.getmembers()
if m.isfile() and not m.name.startswith("/") and ".." not in Path(m.name).parts and Path(m.name).name == binary_name
m for m in tf.getmembers() if m.isfile() and not m.name.startswith("/") and ".." not in Path(m.name).parts and Path(m.name).name == binary_name
]
if not candidates:
raise RuntimeError(f"Could not find {binary_name} inside downloaded archive (members: {[m.name for m in tf.getmembers()[:5]]}...)")
@@ -333,7 +300,6 @@ def _allowlisted_env() -> Dict[str, str]:
def _run(argv: List[str], *, timeout: int, text: bool = False, **kwargs) -> "subprocess.CompletedProcess":
"""``subprocess.run`` with captured output; argv[0] is always a trusted PATH/system binary."""
if text:
kwargs.update(text=True, encoding="utf-8", errors="replace")
return subprocess.run(argv, capture_output=True, timeout=timeout, stdin=subprocess.DEVNULL, **kwargs) # noqa: S603
@@ -341,23 +307,21 @@ def _run(argv: List[str], *, timeout: int, text: bool = False, **kwargs) -> "sub
def iron_proxy_version(binary: Path) -> str:
"""``iron-proxy --version`` output, stripped and cached by path. Empty on failure."""
key = str(binary)
if key in _VERSION_CACHE:
if (key := str(binary)) in _VERSION_CACHE:
return _VERSION_CACHE[key]
try:
# Scrubbed env: a PATH-resolved binary must not see the host's API keys.
res = _run([str(binary), "--version"], timeout=_RUN_TIMEOUT, text=True, env=_allowlisted_env())
except (OSError, subprocess.TimeoutExpired):
return ""
out = (res.stdout or res.stderr or "").strip()
if out: # never cache empty output — it would poison status for the process lifetime
if out := (res.stdout or res.stderr or "").strip(): # never cache empty output — it would poison status for the process lifetime
_VERSION_CACHE[key] = out
return out
def _write_private_file(path: Path, data: bytes) -> None:
"""Create/truncate ``path`` 0o600 from the first byte (no chmod-after TOCTOU), O_NOFOLLOW
against a planted symlink, fchmod to tighten a pre-existing file."""
"""Create/truncate ``path`` 0o600 from the first byte (no chmod-after TOCTOU), O_NOFOLLOW against a planted
symlink, fchmod to tighten a pre-existing file."""
fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC | _O_NOFOLLOW, 0o600)
try:
with suppress(OSError, AttributeError):
@@ -387,11 +351,8 @@ def ensure_ca_cert(*, force: bool = False) -> Tuple[Path, Path]:
with tempfile.TemporaryDirectory(prefix="hermes-proxy-ca-") as tmpdir:
tmp_key, tmp_crt = Path(tmpdir) / "ca.key", Path(tmpdir) / "ca.crt"
_run(["openssl", "genrsa", "-out", str(tmp_key), "4096"], timeout=60, check=True)
_run([
"openssl", "req", "-x509", "-new", "-nodes", "-key", str(tmp_key), "-sha256", "-days", "3650",
"-subj", "/CN=hermes iron-proxy CA", "-addext", "basicConstraints=critical,CA:TRUE",
"-addext", "keyUsage=critical,keyCertSign", "-out", str(tmp_crt),
], timeout=60, check=True)
_run(["openssl", "req", "-x509", "-new", "-nodes", "-key", str(tmp_key), "-sha256", "-days", "3650", "-subj", "/CN=hermes iron-proxy CA",
"-addext", "basicConstraints=critical,CA:TRUE", "-addext", "keyUsage=critical,keyCertSign", "-out", str(tmp_crt)], timeout=60, check=True)
# Key: stage 0o600 against a fresh inode, then atomically rename into place.
key_staged = ca_key.with_suffix(ca_key.suffix + ".staged")
key_staged.unlink(missing_ok=True)
@@ -420,8 +381,7 @@ def _read_text_or_none(p: Path) -> Optional[str]:
def ensure_management_token(*, force: bool = False) -> str:
"""Return the management-API bearer key (0600 at <proxy>/management.token), minting on first call."""
p = _proxy_state_dir() / "management.token"
existing = None if force else _read_text_or_none(p)
if existing:
if not force and (existing := _read_text_or_none(p)):
return existing
token = mint_proxy_token(prefix="hermes-mgmt")
_write_private_file(p, token.encode("utf-8"))
@@ -437,17 +397,6 @@ def _yaml():
return None
def _load_proxy_yaml(cfg: Path):
"""Parsed proxy.yaml, or ``{}`` when missing/unreadable/PyYAML absent."""
yaml = _yaml()
if yaml is None:
return {}
try:
return yaml.safe_load(cfg.read_text(encoding="utf-8")) or {}
except (OSError, yaml.YAMLError):
return {}
def _parse_listen(listen) -> Optional[Tuple[str, int]]:
"""``"host:port"`` -> ``(host, port)``; empty host means loopback."""
if not isinstance(listen, str) or ":" not in listen:
@@ -461,8 +410,12 @@ def _parse_listen(listen) -> Optional[Tuple[str, int]]:
def _config_listen(section: str, *keys: str, config_path: Optional[Path] = None) -> Optional[Tuple[str, int]]:
"""``(host, port)`` from the first truthy ``proxy.yaml[section][key]``, or None."""
block = _load_proxy_yaml(config_path or (_proxy_state_dir_ro() / "proxy.yaml")).get(section) or {}
"""``(host, port)`` from the first truthy ``proxy.yaml[section][key]``, or None (also when file/PyYAML is missing)."""
yaml, data = _yaml(), {}
if yaml is not None:
with suppress(OSError, yaml.YAMLError):
data = yaml.safe_load((config_path or (_proxy_state_dir_ro() / "proxy.yaml")).read_text(encoding="utf-8")) or {}
block = data.get(section) or {}
return _parse_listen(next((block[k] for k in keys if block.get(k)), ""))
@@ -470,41 +423,28 @@ def _read_management_listen_from_config(config_path: Optional[Path] = None) -> O
return _config_listen("management", "listen", config_path=config_path)
def _read_http_listen_from_config() -> Optional[Tuple[str, int]]:
"""Sandbox-facing listener: ``tunnel_listen`` (CONNECT/MITM), falling back to ``http_listen``
for configs written before the listener-role split."""
return _config_listen("proxy", "tunnel_listen", "http_listen")
def _probe_target() -> Tuple[str, int]:
"""Configured bind host/port to probe — on Linux that's the docker bridge, where a loopback
connect would report a healthy daemon as down."""
return _read_http_listen_from_config() or ("127.0.0.1", _DEFAULT_TUNNEL_PORT)
"""Configured bind host/port to probe — on Linux the docker bridge, where a loopback connect would report a healthy
daemon as down. ``tunnel_listen`` (CONNECT/MITM) falls back to ``http_listen`` for pre-listener-role-split configs."""
return _config_listen("proxy", "tunnel_listen", "http_listen") or ("127.0.0.1", _DEFAULT_TUNNEL_PORT)
# Management-API error status -> operator message (422 = validation rejected, running ruleset
# unchanged; 401 = daemon started with a different management.token).
# Management-API error status -> operator message (422 = validation rejected, ruleset unchanged; 401 = daemon started with another management.token).
_RELOAD_HTTP_ERRORS = {
422: "iron-proxy rejected the new config (validation failed; the running ruleset is unchanged): {body}",
401: "management API rejected our key (401). The running daemon was started with a different management.token — "
"run `hermes egress restart`.",
401: "management API rejected our key (401). The running daemon was started with a different management.token — run `hermes egress restart`.",
}
def reload_proxy() -> bool:
"""``POST /v1/reload`` (validation failures leave the running config untouched); RuntimeError
with an actionable message on any failure."""
pid = _read_pid()
if not pid or not _pid_alive(pid):
"""``POST /v1/reload`` (validation failures leave the running config untouched); actionable RuntimeError on any failure."""
if not (pid := _read_pid()) or not _pid_alive(pid):
raise RuntimeError("iron-proxy is not running — nothing to reload. Run `hermes egress start`.")
mgmt = _read_management_listen_from_config()
if mgmt is None:
if (mgmt := _read_management_listen_from_config()) is None:
raise RuntimeError(
"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."
"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."
)
token = _read_text_or_none(_proxy_state_dir_ro() / "management.token")
if not token:
if not (token := _read_text_or_none(_proxy_state_dir_ro() / "management.token")):
raise RuntimeError("management.token is missing — re-run `hermes egress setup`, then `hermes egress restart`.")
host, port = mgmt
req = urllib.request.Request(f"http://{host}:{port}/v1/reload", method="POST", headers={"Authorization": f"Bearer {token}"}, data=b"")
@@ -522,22 +462,19 @@ def reload_proxy() -> bool:
except (urllib.error.URLError, OSError) as exc:
# A daemon started from a pre-management config is alive but has no listener.
raise RuntimeError(
f"could not reach the management API at {host}:{port} ({exc}). "
"If the daemon was started before reload support, run `hermes egress restart` once."
f"could not reach the management API at {host}:{port} ({exc}). If the daemon was started before reload support, run `hermes egress restart` once."
) from exc
def _default_http_listen(tunnel_port: int) -> List[str]:
"""Single bind (v0.39 allows one): docker bridge on Linux (what ``host.docker.internal``
resolves to; loopback is unreachable from containers), loopback on Docker Desktop (VPNkit).
NEVER 0.0.0.0: a LAN peer with a leaked sandbox token could spend the operator's API quota."""
"""Single bind (v0.39 allows one): docker bridge on Linux (what ``host.docker.internal`` resolves to; loopback is
unreachable from containers), loopback on Docker Desktop (VPNkit). NEVER 0.0.0.0: a LAN peer with a leaked
sandbox token could spend the operator's API quota."""
if platform.system() == "Linux":
bridge_ip = _detect_docker_bridge_ip()
if bridge_ip and bridge_ip != "127.0.0.1":
if (bridge_ip := _detect_docker_bridge_ip()) and bridge_ip != "127.0.0.1":
return [f"{bridge_ip}:{tunnel_port}"]
logger.warning(
"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."
"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."
)
return [f"127.0.0.1:{tunnel_port}"]
@@ -549,18 +486,11 @@ def _detect_docker_bridge_ip() -> Optional[str]:
res = _run(["ip", "-4", "-o", "addr", "show", "docker0"], timeout=2, text=True)
except (OSError, subprocess.TimeoutExpired):
return None
if res.returncode != 0:
return None
# Expected: "<n>: docker0 inet 172.17.0.1/16 ..." — first inet token (per line) wins.
candidate = None
for parts in (line.split() for line in res.stdout.splitlines()):
if "inet" in parts[:-1]:
candidate = parts[parts.index("inet") + 1].split("/")[0]
break
if not candidate:
return None
lines = (line.split() for line in res.stdout.splitlines()) if res.returncode == 0 else ()
candidate = next((parts[parts.index("inet") + 1].split("/")[0] for parts in lines if "inet" in parts[:-1]), None)
try:
addr = ipaddress.IPv4Address(candidate)
addr = ipaddress.IPv4Address(candidate) # None/"" raise too
except (ipaddress.AddressValueError, ValueError):
return None
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:
@@ -570,38 +500,32 @@ def _detect_docker_bridge_ip() -> Optional[str]:
def build_proxy_config(
*, mappings: List[TokenMapping], ca_cert: Path, ca_key: Path, tunnel_port: int = _DEFAULT_TUNNEL_PORT,
audit_log: Optional[Path] = None, allowed_hosts: Optional[List[str]] = None,
upstream_deny_cidrs: Optional[List[str]] = None, http_listen: Optional[List[str]] = None,
*, mappings: List[TokenMapping], ca_cert: Path, ca_key: Path, tunnel_port: int = _DEFAULT_TUNNEL_PORT, audit_log: Optional[Path] = None,
allowed_hosts: Optional[List[str]] = None, upstream_deny_cidrs: Optional[List[str]] = None, http_listen: Optional[List[str]] = None,
) -> Dict:
"""iron-proxy YAML config dict (v0.39.0 schema). Real secrets come from iron-proxy's OWN env
(``source: {type: env}``); the sandbox never sees them. ``upstream_deny_cidrs=None`` = default
SSRF deny list, ``[]`` opts out. ``audit_log`` is forward-compat only (v0.39 rejects ``audit_path``)."""
"""iron-proxy YAML config dict (v0.39.0 schema). Real secrets come from iron-proxy's OWN env (``source: {type: env}``);
the sandbox never sees them. ``upstream_deny_cidrs=None`` = default SSRF deny list, ``[]`` opts out.
``audit_log`` is forward-compat only (v0.39 rejects ``audit_path``)."""
hosts: List[str] = list(allowed_hosts or _DEFAULT_ALLOWED_HOSTS)
for m in mappings:
for h in m.upstream_hosts:
if h not in hosts:
hosts.append(h)
for h in (h for m in mappings for h in m.upstream_hosts):
if h not in hosts:
hosts.append(h)
deny_cidrs = list(_DEFAULT_UPSTREAM_DENY_CIDRS if upstream_deny_cidrs is None else upstream_deny_cidrs)
# Query scan covers ``?key=<token>`` SDKs; body inspection deliberately off. ``require`` fails
# closed: an allowlisted-host request WITHOUT the proxy token is rejected, so a real key sent
# directly can't cross the boundary.
secrets_rules = [
{
"source": {"type": "env", "var": m.real_env_name},
"replace": {
"proxy_value": m.proxy_token, "match_headers": list(m.match_headers or ("Authorization",)),
"match_query": True, "match_body": False, "require": True,
},
"rules": [{"host": h} for h in m.upstream_hosts],
}
for m in mappings
]
secrets_rules = [{
"source": {"type": "env", "var": m.real_env_name},
"replace": {
"proxy_value": m.proxy_token, "match_headers": list(m.match_headers or ("Authorization",)),
"match_query": True, "match_body": False, "require": True,
},
"rules": [{"host": h} for h in m.upstream_hosts],
} for m in mappings]
# ONE string per listener field. tunnel_listen is the CONNECT+MITM listener sandboxes reach via
# HTTPS_PROXY (a CONNECT to http_listen is forwarded upstream and 400s); http_listen is plain-HTTP
# forward on tunnel_port+1.
listens = list(http_listen) if http_listen else _default_http_listen(tunnel_port)
primary_listen = listens[0] if listens else f"127.0.0.1:{tunnel_port}"
primary_listen = (list(http_listen) if http_listen else _default_http_listen(tunnel_port) or [f"127.0.0.1:{tunnel_port}"])[0]
bind_host = primary_listen.rsplit(":", 1)[0] or "127.0.0.1"
return {
# Required by the parser; tunnel-only mode never binds an exposed DNS port.
@@ -618,17 +542,14 @@ def build_proxy_config(
# Loopback only: sandboxes must never reach the management surface.
"management": {"listen": f"127.0.0.1:{tunnel_port + _MGMT_PORT_OFFSET}", "api_key_env": _MGMT_API_KEY_ENV},
"tls": {"ca_cert": str(ca_cert), "ca_key": str(ca_key), "cert_cache_size": 1000, "leaf_cert_expiry_hours": 168},
"transforms": [
{"name": "allowlist", "config": {"domains": hosts}},
{"name": "secrets", "config": {"secrets": secrets_rules}},
],
"transforms": [{"name": "allowlist", "config": {"domains": hosts}}, {"name": "secrets", "config": {"secrets": secrets_rules}}],
"log": {"level": "info"},
}
def _open_private_append(path: Path, *, strict_chmod: bool) -> int:
"""Open ``path`` O_APPEND|O_CREAT 0o600 with O_NOFOLLOW (planted symlinks refused); fchmod
tightens a pre-existing file (failure fatal iff ``strict_chmod``). Raises OSError; caller owns the fd."""
"""O_APPEND|O_CREAT 0o600 + O_NOFOLLOW (planted symlinks refused); fchmod tightens a pre-existing
file (failure fatal iff ``strict_chmod``). Raises OSError; caller owns the fd."""
fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_APPEND | _O_NOFOLLOW, 0o600)
try:
os.fchmod(fd, 0o600)
@@ -640,20 +561,17 @@ def _open_private_append(path: Path, *, strict_chmod: bool) -> int:
def ensure_audit_log(audit_path: Path) -> None:
"""Pre-create the audit log 0o600 (forward-compat: v0.39 never writes it). RuntimeError on any
OSError (planted symlink, immutable dir, full disk)."""
"""Pre-create the audit log 0o600 (forward-compat: v0.39 never writes it); RuntimeError on any OSError."""
try:
os.close(_open_private_append(audit_path, strict_chmod=True))
except OSError as exc:
raise RuntimeError(
f"Refusing to start: could not pre-create audit log {audit_path} with restrictive permissions ({exc}). "
f"Move or chmod any existing file at that path and retry."
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."
) from exc
def _write_state_file_atomic(state: Path, name: str, dump) -> Path:
"""0600 temp file + atomic replace: the file holds proxy tokens, and chmod-after-replace would
leave a world-readable TOCTOU window."""
"""0600 temp file + atomic replace: the file holds proxy tokens; chmod-after-replace would be a world-readable TOCTOU window."""
tmp_path = state / f".{name}.tmp"
with open(tmp_path, "w", encoding="utf-8") as f:
dump(f)
@@ -664,33 +582,23 @@ def _write_state_file_atomic(state: Path, name: str, dump) -> Path:
def write_proxy_config(config: Dict) -> Path:
"""Serialize the config dict to ``<hermes_home>/proxy/proxy.yaml`` (safe_dump, no Python tags)."""
yaml = _yaml()
if yaml is None:
if (yaml := _yaml()) is None:
raise RuntimeError("PyYAML is required to write the iron-proxy config but is not installed.")
return _write_state_file_atomic(
_proxy_state_dir(), "proxy.yaml", lambda f: yaml.safe_dump(config, f, default_flow_style=False, sort_keys=False),
)
return _write_state_file_atomic(_proxy_state_dir(), "proxy.yaml", lambda f: yaml.safe_dump(config, f, default_flow_style=False, sort_keys=False))
def write_mappings(mappings: List[TokenMapping]) -> Path:
"""Persist sandbox-visible tokens to ``mappings.json`` (read by the Docker backend, not iron-proxy)."""
payload = {
"version": 1,
"tokens": [
{
"proxy_token": m.proxy_token, "env_name": m.real_env_name, "upstream_hosts": list(m.upstream_hosts),
"match_headers": list(m.match_headers), "alias_env_names": list(m.alias_env_names),
}
for m in mappings
],
}
payload = {"version": 1, "tokens": [{
"proxy_token": m.proxy_token, "env_name": m.real_env_name, "upstream_hosts": list(m.upstream_hosts),
"match_headers": list(m.match_headers), "alias_env_names": list(m.alias_env_names),
} for m in mappings]}
return _write_state_file_atomic(_proxy_state_dir(), "mappings.json", lambda f: json.dump(payload, f, indent=2))
def load_mappings() -> List[TokenMapping]:
"""Read mappings.json, if it exists. Empty list on any error."""
f = _proxy_state_dir() / "mappings.json"
if not f.exists():
if not (f := _proxy_state_dir() / "mappings.json").exists():
return []
try:
payload = json.loads(f.read_text(encoding="utf-8"))
@@ -699,28 +607,19 @@ def load_mappings() -> List[TokenMapping]:
return []
out: List[TokenMapping] = []
for item in payload.get("tokens", []):
try: # pre-header-auth files load with the bearer defaults they were written under
out.append(TokenMapping(
item["proxy_token"], item["env_name"], tuple(item.get("upstream_hosts") or ()),
tuple(item.get("match_headers") or ("Authorization",)), tuple(item.get("alias_env_names") or ()),
))
except (KeyError, TypeError):
continue
with suppress(KeyError, TypeError): # pre-header-auth files load with the bearer defaults they were written under
out.append(TokenMapping(item["proxy_token"], item["env_name"], tuple(item.get("upstream_hosts") or ()),
tuple(item.get("match_headers") or ("Authorization",)), tuple(item.get("alias_env_names") or ())))
return out
def _env_names(available_env_names: Optional[List[str]]) -> set:
"""Explicit override (Bitwarden adapter) or the non-empty names in the host env."""
return set(available_env_names) if available_env_names is not None else {k for k, v in os.environ.items() if v}
def discover_provider_mappings(*, available_env_names: Optional[List[str]] = None) -> List[TokenMapping]:
"""One TokenMapping per known provider whose env var is set (bearer providers first). Canonical
OR any alias present -> ONE mapping on the canonical name (the subprocess-env builder mirrors aliases)."""
names = _env_names(available_env_names)
"""One TokenMapping per known provider whose env var is set (bearer providers first). Canonical OR any alias
present -> ONE mapping on the canonical name (the subprocess-env builder mirrors aliases).
``available_env_names`` (Bitwarden adapter) overrides the non-empty names in the host env."""
names = set(available_env_names) if available_env_names is not None else {k for k, v in os.environ.items() if v}
specs = [(n, h, ("Authorization",), ()) for n, h in _BEARER_PROVIDERS.items()] + [
(n, tuple(s["hosts"]), tuple(s["match_headers"]), tuple(s.get("aliases") or ()))
for n, s in _HEADER_AUTH_PROVIDERS.items()
(n, tuple(s["hosts"]), tuple(s["match_headers"]), tuple(s.get("aliases") or ())) for n, s in _HEADER_AUTH_PROVIDERS.items()
]
return [
TokenMapping(mint_proxy_token(prefix=env_name.lower().replace("_api_key", "")), env_name, hosts, headers, aliases)
@@ -731,18 +630,15 @@ def discover_provider_mappings(*, available_env_names: Optional[List[str]] = Non
def discover_uncovered_providers(*, available_env_names: Optional[List[str]] = None) -> List[str]:
"""Env names of recognized providers the proxy can't swap (SigV4 / SDK-minted OAuth)."""
names = _env_names(available_env_names)
names = set(available_env_names) if available_env_names is not None else {k for k, v in os.environ.items() if v}
return [n for n in _NON_BEARER_PROVIDERS if n in names]
def merge_mappings(*, existing: List[TokenMapping], discovered: List[TokenMapping], rotate: bool = False) -> List[TokenMapping]:
"""Tokens already in ``existing`` are preserved (containers baked with them keep working) while
hosts/headers/aliases refresh from ``discovered``; ``rotate=True`` re-mints; undiscovered providers drop."""
"""Existing tokens are preserved (containers baked with them keep working), hosts/headers/aliases refresh
from ``discovered``; ``rotate=True`` re-mints; undiscovered providers drop."""
by_name = {} if rotate else {m.real_env_name: m for m in existing}
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
]
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]
def _pidfile() -> Path:
@@ -751,8 +647,8 @@ def _pidfile() -> Path:
def _read_pid() -> Optional[int]:
try:
pid = int((_proxy_state_dir_ro() / "iron-proxy.pid").read_text(encoding="utf-8").strip())
except (OSError, ValueError):
pid = int(_read_text_or_none(_proxy_state_dir_ro() / "iron-proxy.pid") or "")
except ValueError:
return None
return pid if pid > 0 else None
@@ -764,20 +660,18 @@ def _pid_proc_starttime(pid: int) -> Optional[str]:
except OSError:
return None
# comm may contain spaces/parens, so split after the LAST ")"; field 22 -> tail index 19.
rparen = text.rfind(")")
fields = text[rparen + 1:].split() if rparen >= 0 else []
fields = text[rparen + 1:].split() if (rparen := text.rfind(")")) >= 0 else []
return fields[19] if len(fields) > 19 else None
def _persisted_nonce_path() -> Path:
"""On-disk nonce sibling of the pidfile, so stop/status in a later CLI process can still
defeat PID recycling."""
"""On-disk nonce sibling of the pidfile, so stop/status in a later CLI process can still defeat PID recycling."""
return _proxy_state_dir_ro() / "iron-proxy.nonce"
def _read_persisted_nonce() -> Optional[str]:
"""Nonce from disk, or None if missing/unreadable/empty/not owned by us (callers fall back to
argv0 matching). O_NOFOLLOW: this read decides whether stop_proxy SIGKILLs a PID."""
"""Nonce from disk, or None if missing/unreadable/empty/not owned by us (callers fall back to argv0
matching). O_NOFOLLOW: this read decides whether stop_proxy SIGKILLs a PID."""
try:
fd = os.open(str(_persisted_nonce_path()), os.O_RDONLY | _O_NOFOLLOW)
except OSError:
@@ -791,9 +685,9 @@ def _read_persisted_nonce() -> Optional[str]:
def _pid_alive(pid: int) -> bool:
"""True iff ``pid`` is alive AND an iron-proxy process. PID-reuse defense, in priority order:
nonce in /proc/<pid>/environ, argv[0] basename in /proc/<pid>/cmdline, ``ps -o comm=`` basename
(a loose ``"iron-proxy" in cmdline`` would hit ``tail iron-proxy.log``)."""
"""True iff ``pid`` is alive AND an iron-proxy process. PID-reuse defense, in priority order: nonce in
/proc/<pid>/environ, argv[0] basename in /proc/<pid>/cmdline, ``ps -o comm=`` basename (a loose
``"iron-proxy" in cmdline`` would hit ``tail iron-proxy.log``)."""
if pid <= 0:
return False
try:
@@ -815,10 +709,8 @@ def _pid_alive(pid: int) -> bool:
if any(f"{_HERMES_IRON_PROXY_NONCE_ENV}={n}".encode() in env_bytes for n in nonce_candidates):
return True
with suppress(OSError):
cmdline_path = Path(f"/proc/{pid}/cmdline")
if cmdline_path.exists():
argv0 = cmdline_path.read_bytes().split(b"\x00")[0].decode("utf-8", errors="ignore")
return os.path.basename(argv0).startswith("iron-proxy")
if (cmdline_path := Path(f"/proc/{pid}/cmdline")).exists():
return os.path.basename(cmdline_path.read_bytes().split(b"\x00")[0].decode("utf-8", errors="ignore")).startswith("iron-proxy")
with suppress(OSError, subprocess.TimeoutExpired): # macOS / non-Linux fallback
res = _run(["ps", "-p", str(pid), "-o", "comm="], timeout=2, text=True)
if res.returncode == 0:
@@ -831,22 +723,17 @@ def start_proxy(
*, binary: Optional[Path] = None, config_path: Optional[Path] = None, extra_env: Optional[Dict[str, str]] = None,
install_if_missing: bool = True, refresh_secrets_from_bitwarden: bool = False, bitwarden_config: Optional[Dict] = None,
) -> ProxyStatus:
"""Spawn iron-proxy as a managed background subprocess (idempotent if already running).
``refresh_secrets_from_bitwarden`` re-fetches secrets from BWS — the ``credential_source: bitwarden`` rotation promise."""
"""Spawn iron-proxy as a managed background subprocess (idempotent if already running). ``refresh_secrets_from_bitwarden``
re-fetches secrets from BWS — the ``credential_source: bitwarden`` rotation promise."""
global _proxy_nonce
existing = _read_pid()
if existing and _pid_alive(existing):
if (existing := _read_pid()) and _pid_alive(existing):
return get_status()
bin_path = binary or find_iron_proxy(install_if_missing=install_if_missing)
if bin_path is None:
if (bin_path := binary or find_iron_proxy(install_if_missing=install_if_missing)) is None:
raise RuntimeError("iron-proxy binary not available — run `hermes egress install`.")
cfg = config_path or (_proxy_state_dir() / "proxy.yaml")
if not cfg.exists():
if not (cfg := config_path or (_proxy_state_dir() / "proxy.yaml")).exists():
raise RuntimeError(f"iron-proxy config not found at {cfg}. Run `hermes egress setup` first.")
# Minimal env: os.environ.copy() would expose every operator secret via /proc/<pid>/environ.
env = _build_proxy_subprocess_env(
extra_env=extra_env, refresh_from_bitwarden=refresh_secrets_from_bitwarden, bitwarden_config=bitwarden_config,
)
env = _build_proxy_subprocess_env(extra_env=extra_env, refresh_from_bitwarden=refresh_secrets_from_bitwarden, bitwarden_config=bitwarden_config)
# v0.39 validates api_key_env is non-empty when management.listen is set.
if _read_management_listen_from_config(cfg) is not None:
env[_MGMT_API_KEY_ENV] = ensure_management_token()
@@ -870,14 +757,12 @@ def start_proxy(
pidfile.unlink(missing_ok=True)
return RuntimeError(f"{msg}Last log lines:\n{tail}")
def _exited_error() -> RuntimeError:
return _abort(f"iron-proxy exited immediately (code {proc.returncode}). ", kill=False)
def _interrupt_handler(_signum, _frame): # pragma: no cover - signal path
_kill_and_wait(proc, grace_seconds=2) # Ctrl-C while waiting must not leak an orphan holding the port
pidfile.unlink(missing_ok=True)
raise KeyboardInterrupt()
_exited_error = lambda: _abort(f"iron-proxy exited immediately (code {proc.returncode}). ", kill=False) # noqa: E731
# Probe the CONFIGURED bind host (on Linux the docker bridge, where loopback never connects).
probe_host, tunnel_port = _probe_target()
with _interrupt_guard(_interrupt_handler):
@@ -894,7 +779,7 @@ def start_proxy(
@contextmanager
def _interrupt_guard(handler):
"""Route SIGINT/SIGTERM to ``handler`` for the block (POSIX main thread only), restoring the previous handlers after."""
"""Route SIGINT/SIGTERM to ``handler`` for the block (POSIX main thread only); previous handlers restored after."""
if platform.system() == "Windows" or threading.current_thread() is not threading.main_thread():
yield
return
@@ -907,22 +792,21 @@ def _interrupt_guard(handler):
def _spawn_daemon(bin_path: Path, cfg: Path, env: Dict[str, str], log_path: Path) -> "subprocess.Popen":
"""Popen with stdout/stderr appended to ``log_path`` (0o600 from the first byte, O_NOFOLLOW so a
planted symlink e.g. to authorized_keys can't receive output, owner-checked). Our log fd is
closed right after Popen — the child has its dup."""
"""Popen with stdout/stderr appended to ``log_path`` (0o600 from the first byte, O_NOFOLLOW so a planted
symlink e.g. to authorized_keys can't receive output, owner-checked). Our log fd closes after Popen — the child has its dup."""
try:
log_fd = _open_private_append(log_path, strict_chmod=False)
except OSError as exc:
raise RuntimeError(f"Refusing to write iron-proxy log {log_path}: {exc}. Remove that path manually and retry.") from exc
if not _fd_owned_by_us(log_fd):
st = os.fstat(log_fd)
uid = os.fstat(log_fd).st_uid
os.close(log_fd)
raise RuntimeError(f"iron-proxy log {log_path} has unexpected owner uid={st.st_uid}; refusing to write.")
raise RuntimeError(f"iron-proxy log {log_path} has unexpected owner uid={uid}; refusing to write.")
try:
# start_new_session is POSIX-only (Windows isn't supported anyway — no upstream binary).
session_kw = {} if platform.system() == "Windows" else {"start_new_session": True}
return subprocess.Popen( # noqa: S603
[str(bin_path), "-config", str(cfg)], env=env, stdin=subprocess.DEVNULL, stdout=log_fd, stderr=subprocess.STDOUT, **session_kw,
[str(bin_path), "-config", str(cfg)], env=env, stdin=subprocess.DEVNULL, stdout=log_fd, stderr=subprocess.STDOUT,
**({} if platform.system() == "Windows" else {"start_new_session": True}),
)
except OSError as exc:
raise RuntimeError(f"failed to spawn iron-proxy: {exc}") from exc
@@ -932,8 +816,7 @@ def _spawn_daemon(bin_path: Path, cfg: Path, env: Dict[str, str], log_path: Path
def _await_listening(proc: "subprocess.Popen", host: str, port: int, *, on_exit) -> bool:
"""Poll until ``host:port`` accepts or the grace window lapses (do-while: at least one check
even with a 0s window). Raises ``on_exit()`` if the child dies meanwhile."""
"""Poll until ``host:port`` accepts or the grace window lapses (do-while: >=1 check even at 0s); raises ``on_exit()`` if the child dies."""
deadline = time.time() + _STARTUP_GRACE_SECONDS
while True:
if proc.poll() is not None:
@@ -946,17 +829,15 @@ def _await_listening(proc: "subprocess.Popen", host: str, port: int, *, on_exit)
def _write_pidfile_safely(pidfile: Path, pid: int) -> None:
"""O_EXCL + O_NOFOLLOW + ownership check, then persist the nonce. An existing pidfile is either
a concurrent start (fail cleanly) or a stale crash leftover (unlink and retry once)."""
"""O_EXCL + O_NOFOLLOW + ownership check, then persist the nonce. An existing pidfile is either a concurrent
start (fail cleanly) or a stale crash leftover (unlink and retry once)."""
open_flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_NOFOLLOW
try:
fd = os.open(str(pidfile), open_flags, 0o600)
except FileExistsError:
existing_pid = _read_pid()
if existing_pid and _pid_alive(existing_pid):
if (existing_pid := _read_pid()) and _pid_alive(existing_pid):
raise RuntimeError(
f"Another iron-proxy start appears to be in progress (pidfile {pidfile} -> pid {existing_pid}). "
f"Run `hermes egress stop` if that proxy is stuck."
f"Another iron-proxy start appears to be in progress (pidfile {pidfile} -> pid {existing_pid}). Run `hermes egress stop` if that proxy is stuck."
)
pidfile.unlink(missing_ok=True)
fd = os.open(str(pidfile), open_flags, 0o600)
@@ -976,7 +857,6 @@ def _write_pidfile_safely(pidfile: Path, pid: int) -> None:
def _kill_and_wait(proc: "subprocess.Popen", *, grace_seconds: int = 2) -> None:
"""Best-effort SIGTERM → wait → SIGKILL for a child we own."""
try:
proc.terminate()
except OSError:
@@ -993,18 +873,16 @@ def _kill_and_wait(proc: "subprocess.Popen", *, grace_seconds: int = 2) -> None:
def _build_proxy_subprocess_env(
*, extra_env: Optional[Dict[str, str]] = None, refresh_from_bitwarden: bool = False, bitwarden_config: Optional[Dict] = None,
) -> Dict[str, str]:
"""Allowlisted infra vars + the secrets named in mappings. With ``refresh_from_bitwarden`` and a
populated ``bitwarden_config`` secrets come from BWS (the rotation guarantee); without
``allow_env_fallback`` any BWS shortfall fails closed instead of keeping stale host-env values."""
env = _allowlisted_env()
parent = os.environ
"""Allowlisted infra vars + the secrets named in mappings. With ``refresh_from_bitwarden`` and a populated
``bitwarden_config`` secrets come from BWS (the rotation guarantee); without ``allow_env_fallback`` any BWS
shortfall fails closed instead of keeping stale host-env values."""
env, parent = _allowlisted_env(), os.environ
# Forward ONLY mapped secrets; the rule is keyed on the canonical name, so mirror an alias value into it.
mappings = load_mappings()
needed = {m.real_env_name for m in mappings}
alias_sources = {m.real_env_name: m.alias_env_names for m in mappings if m.alias_env_names}
for name in needed:
source = name if name in parent else next((a for a in alias_sources.get(name, ()) if parent.get(a)), None)
if source is not None:
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:
env[name] = parent[source]
if refresh_from_bitwarden and bitwarden_config:
_refresh_secrets_from_bitwarden(env, needed, bitwarden_config, bool(bitwarden_config.get("allow_env_fallback")))
@@ -1017,16 +895,17 @@ def _build_proxy_subprocess_env(
return env
def _bitwarden_shortfall(allow_env_fallback: bool, error: str, warning: str, *args) -> None:
"""Raise ``error`` unless the operator opted into the legacy host-env fallback (then log ``warning``)."""
def _bitwarden_shortfall(allow_env_fallback: bool, error: str, warning: str, *args, cause: Optional[BaseException] = None) -> None:
"""Raise ``error`` (chained to ``cause`` when given) unless the operator opted into the legacy host-env fallback (then log ``warning``)."""
if not allow_env_fallback:
if cause is not None:
raise RuntimeError(error) from cause
raise RuntimeError(error)
logger.warning(warning, *args)
def _refresh_secrets_from_bitwarden(env: Dict[str, str], needed: set, bitwarden_config: Dict, allow_env_fallback: bool) -> None:
"""Overwrite ``env[needed]`` with fresh (uncached) BWS values; only mapped names are injected so
unrelated BWS secrets never leak into the daemon env."""
"""Overwrite ``env[needed]`` with fresh (uncached) BWS values; only mapped names are injected so unrelated BWS secrets never leak."""
try:
# Lazy: the bitwarden module isn't importable in every install.
from agent.secret_sources import bitwarden as bw
@@ -1038,40 +917,35 @@ def _refresh_secrets_from_bitwarden(env: Dict[str, str], needed: set, bitwarden_
allow_env_fallback,
"credential_source=bitwarden but the access-token env or project_id is empty. Either set both, switch to "
"credential_source: env, or set `proxy.allow_env_fallback: true` to opt into the legacy fallback behaviour.",
"credential_source=bitwarden but access-token env or project_id is empty — "
"proxy will fall back to parent env (allow_env_fallback=true).",
"credential_source=bitwarden but access-token env or project_id is empty — proxy will fall back to parent env (allow_env_fallback=true).",
)
return
secrets, warnings = bw.fetch_bitwarden_secrets(access_token=access_token, project_id=project_id, cache_ttl_seconds=0, use_cache=False)
except ImportError as exc:
# A dependency vanishing between setup and restart must not silently degrade.
if not allow_env_fallback:
raise RuntimeError(
"Bitwarden refresh module unavailable at proxy start (credential_source=bitwarden with "
"proxy.allow_env_fallback: false). Either fix the import, switch to credential_source: env, or set "
"`proxy.allow_env_fallback: true` to opt into the legacy fallback behaviour."
) from exc
logger.warning("Bitwarden refresh module unavailable at proxy start, falling back to parent env (allow_env_fallback=true): %s", exc)
_bitwarden_shortfall(
allow_env_fallback,
"Bitwarden refresh module unavailable at proxy start (credential_source=bitwarden with "
"proxy.allow_env_fallback: false). Either fix the import, switch to credential_source: env, or set "
"`proxy.allow_env_fallback: true` to opt into the legacy fallback behaviour.",
"Bitwarden refresh module unavailable at proxy start, falling back to parent env (allow_env_fallback=true): %s", exc, cause=exc,
)
return
missing = sorted(needed - set(secrets))
for n in needed:
if n in secrets:
env[n] = secrets[n]
env.update((n, secrets[n]) for n in needed if n in secrets)
if missing:
_bitwarden_shortfall(
allow_env_fallback,
f"Bitwarden refresh did not return secrets for {missing}. Either add the secrets to your BWS project, switch to "
f"credential_source: env via `hermes egress setup --no-bitwarden`, or set `proxy.allow_env_fallback: true` in "
f"config.yaml to opt into the legacy host-env fallback.",
"Bitwarden refresh did not return secrets for %s — falling back to host env for those names (allow_env_fallback=true).",
missing,
"Bitwarden refresh did not return secrets for %s — falling back to host env for those names (allow_env_fallback=true).", missing,
)
if warnings: # log only the count: the taint analyzer can't tell bws status text is non-secret
logger.warning("Bitwarden refresh produced %d warning(s); run `hermes secrets bitwarden status` for detail.", len(warnings))
def _forget_daemon() -> None:
"""Best-effort removal of pidfile + persisted nonce, and drop the in-process nonce."""
global _proxy_nonce
_pidfile().unlink(missing_ok=True)
with suppress(OSError):
@@ -1080,7 +954,7 @@ def _forget_daemon() -> None:
def stop_proxy() -> bool:
"""Stop the managed iron-proxy. Returns True if it was running."""
"""Returns True if it was running."""
pid = _read_pid()
if not pid or not _pid_alive(pid):
_forget_daemon()
@@ -1100,8 +974,7 @@ def stop_proxy() -> bool:
time.sleep(0.1)
else:
starttime_after = _pid_proc_starttime(pid)
recycled = (starttime_before is not None and starttime_after is not None and starttime_before != starttime_after) or not _pid_alive(pid)
if recycled:
if (starttime_before is not None and starttime_after is not None and starttime_before != starttime_after) or not _pid_alive(pid):
logger.warning("iron-proxy pid=%s appears recycled before SIGKILL; not killing.", pid)
else:
with suppress(ProcessLookupError):
@@ -1115,22 +988,17 @@ def get_status() -> ProxyStatus:
"""Snapshot the proxy state without side effects (called per Docker container create)."""
status = ProxyStatus()
probe_host, status.tunnel_port = _probe_target()
binary = find_iron_proxy(install_if_missing=False)
if binary:
status.binary_path = binary
status.binary_version = iron_proxy_version(binary)
if binary := find_iron_proxy(install_if_missing=False):
status.binary_path, status.binary_version = binary, iron_proxy_version(binary)
state = _proxy_state_dir_ro()
cfg, ca = state / "proxy.yaml", state / "ca.crt"
status.config_path = cfg if cfg.exists() else None
status.ca_cert_path = ca if ca.exists() else None
pid = _read_pid()
if pid and _pid_alive(pid):
status.config_path, status.ca_cert_path = (cfg if cfg.exists() else None), (ca if ca.exists() else None)
if (pid := _read_pid()) and _pid_alive(pid):
status.pid, status.listening = pid, _port_listening(probe_host, status.tunnel_port)
return status
def _port_listening(host: str, port: int) -> bool:
"""Cheap TCP connect probe — True iff something accepts on host:port."""
import socket
try:
with socket.create_connection((host, port), timeout=0.5):
@@ -1149,7 +1017,6 @@ def _tail_log(path: Path, *, lines: int = 20) -> str:
def _reset_for_tests() -> None:
"""Clear the module's mutable globals (``_VERSION_CACHE``, ``_proxy_nonce``)."""
global _proxy_nonce
_VERSION_CACHE.clear()
_proxy_nonce = None