Understand Hermes Egress Proxy Internals

Hermes egress protection is designed to let a sandbox call approved provider hosts without placing the provider's real credential inside the sandbox. This page is a contributor-facing architecture map, not a substitute for the user setup guide.

Follow the request path

At a high level:

1. the sandbox receives a scoped proxy token rather than a provider key;
2. outbound traffic is directed through the egress proxy;
3. the proxy validates token scope and destination policy;
4. approved credentials are injected on the trusted side of the boundary; and
5. the request is forwarded only when the host and connection satisfy policy.

The security property depends on all layers working together: token validation, host allowlisting, DNS and connection checks, certificate handling, process ownership, and fail-closed startup behavior.

Treat mappings and audit data as sensitive

Provider mappings, proxy tokens, nonces, CA material, and raw audit records can reveal security-relevant details. Do not paste them into public issues, screenshots, wiki pages, or model prompts. Redact values while preserving the event type and failure stage needed for diagnosis.

Implementation paths, dependency versions, and test counts change over time. Verify them in the current source tree instead of copying a version-specific number into an operating promise.

Contributor review checklist

• Denied hosts fail before credential injection.
• Redirects cannot escape the approved destination policy.
• DNS resolution and connection targets are both checked.
• Startup fails closed when required policy or CA material is invalid.
• Tokens and nonces are scoped and validated.
• Audit logging cannot leak credential values.
• Process/PID ownership checks resist stale-state reuse.
• Unit, hermetic, and live tests cover different boundaries.

Common pitfalls

Testing only the happy path

A successful approved request does not prove blocked hosts, redirect escapes, malformed tokens, or startup failures are safe.

Logging transformed headers

Debug output captured after credential injection can leak the secret the proxy exists to protect. Log decision metadata, not injected values.

Assuming the sandbox is the only boundary

Host mounts, forwarded credentials, environment overrides, and extra runtime arguments can weaken isolation. Review the complete launch configuration.

Verification steps

1. Inspect the current official implementation and test documentation.
2. Run hermetic tests without real provider credentials.
3. Verify denied-host, redirect, malformed-token, and stale-state cases.
4. Run live tests only in a controlled environment with dedicated credentials.
5. Review logs and artifacts for secret values before sharing results.
6. Confirm an invalid security prerequisite prevents startup or forwarding.

Official reference

Read the official Egress proxy internals documentation and the user-facing Egress proxy guide.