hermes/README.md

Hermes

Hermes is a minimal HTTP/1.1 forward proxy written in Rust. It supports streaming plain HTTP requests, HTTPS tunneling with CONNECT, YAML-configured ACLs, and OpenTelemetry traces, metrics, and logs exported over OTLP/HTTP.

Features

• Absolute-form HTTP forwarding (GET http://host/path)
• HTTPS and arbitrary TCP tunneling with CONNECT host:port
• Optional SOCKS5 CONNECT listener with no-auth and username/password authentication
• SOCKS5 IPv4, IPv6, and domain destinations with shared ACL enforcement
• Streaming request and response bodies
• Upstream connection pooling and configurable timeouts
• Ordered allow/deny ACLs using Basic authentication, client IP networks, destination domains, and destination ports
• Fast salted SHA-256 password hashes; plaintext passwords are never stored in YAML
• Removal of standard and Connection-nominated hop-by-hop headers
• W3C Trace Context extraction and injection for plain HTTP traffic
• Structured, trace-correlated logs on stdout and through OTLP
• Bounded-cardinality HTTP, tunnel, and ACL metrics
• Localhost-only binding by default

TLS is not terminated or inspected. HTTPS remains end-to-end encrypted between the client and destination.

Build and run

cargo build
HERMES_CONFIG_PATH=examples/hermes.yaml cargo run

# The CLI flag takes precedence over HERMES_CONFIG_PATH:
cargo run -- --config examples/hermes.yaml

Configuration path precedence is --config, then HERMES_CONFIG_PATH, then hermes.yaml. This is the only environment variable read by Hermes; logging and OpenTelemetry are also configured in YAML. The included example listens on 127.0.0.1:8080 and allows only localhost clients.

# Plain HTTP
curl --proxy http://127.0.0.1:8080 http://example.com/

# HTTPS via CONNECT
curl --proxy http://127.0.0.1:8080 https://example.com/

Docker

The root Dockerfile builds a statically linked musl binary and packages it in a non-root scratch image with CA certificates. No configuration or credentials are included in the image.

docker build -t hermes:local .

Mount a configuration file read-only at /etc/hermes/hermes.yaml. Inside the container, set listen_addr to 0.0.0.0:8080 so the published port is reachable:

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -v "$PWD/hermes.yaml:/etc/hermes/hermes.yaml:ro" \
  hermes:local

The image sets HERMES_CONFIG_PATH to the mount location. Ensure the mounted file is readable by the numeric non-root container user. ACL networks rules see the container-network peer address, which may differ from the original host or external client address.

The scratch runtime contains no shell or healthcheck utility. Use docker run --rm hermes:local --version to verify the binary starts.

Publishing

The Gitea workflow in .gitea/workflows/build.yaml builds and publishes multi-architecture linux/amd64 and linux/arm64 images to gitea.woggioni.net/woggioni/hermes when a tag matching release/* is pushed. The ARM64 binary is cross-compiled on the AMD64 builder without emulation. For example, release/v0.2.0 publishes v0.2.0 and latest tags containing both architectures. The repository must define the PUBLISHER_TOKEN secret used for registry authentication.

YAML configuration

listen_addr: "127.0.0.1:8080"
socks5_listen_addr: "127.0.0.1:1080"
connect_timeout_ms: 10000
socks5_handshake_timeout_ms: 10000
upstream_timeout_ms: 30000

telemetry:
  service_name: "hermes"
  log_filter: "info"
  resource_attributes:
    deployment.environment.name: "development"
  otlp:
    endpoint: "http://127.0.0.1:4318"
    timeout_ms: 10000
    headers: {}
    traces:
      sample_ratio: 1.0
    metrics:
      export_interval_ms: 60000
      temporality: "cumulative"
    logs: {}

acl:
  default_action: deny

  users:
    alice:
      password_hash: "$hermes-sha256$v=1$..."

  rules:
    - name: alice
      action: allow
      users: ["alice"]

    - name: office-network
      action: allow
      networks: ["10.20.0.0/16", "2001:db8:20::/48"]

    - name: approved-domains
      action: allow
      domains: ["docs.example.com", "example.org", "*.rust-lang.org"]
      ports: [80, 443]

Field	Default	Description
listen_addr	127.0.0.1:8080	Downstream listen address
socks5_listen_addr	null	Optional SOCKS5 listen address; disabled when omitted
connect_timeout_ms	10000	TCP connection timeout for CONNECT and the HTTP connector
socks5_handshake_timeout_ms	10000	Timeout for SOCKS5 negotiation and CONNECT request parsing
upstream_timeout_ms	30000	Time limit for receiving upstream HTTP response headers
telemetry	see OpenTelemetry below	Logging, resource, and OTLP configuration
acl.default_action	deny	Action when no rule matches
acl.users	empty	Usernames and salted SHA-256 password hashes
acl.rules	empty	Ordered ACL rules

Configuration is loaded and validated at startup. Unknown fields, invalid CIDRs, domain patterns, or ports, duplicate or empty rules, references to unknown users, and unsupported password hashes prevent startup. Restart Hermes to apply configuration changes.

telemetry.log_filter controls log filtering and defaults to info, for example log_filter: "hermes=debug". RUST_LOG is not read.

ACL rules

• Rules are evaluated in order; the first match wins.
• Separate user, network, domain, and port rules provide Basic-auth, source-IP, destination-domain, or destination-port authorization.
• If a rule contains multiple selector types, every specified selector must match. Entries within each selector are ORed.
• A rule must contain at least one selector; accidental match-all rules are rejected.
• networks uses the actual client TCP peer address. X-Forwarded-For is never trusted.
• domains uses the request-target authority, never the downstream Host header, and works for both HTTP and CONNECT.
• ports matches the destination port. Plain HTTP defaults to port 80 when omitted; CONNECT and SOCKS5 provide an explicit port.
• Requests without required credentials receive 407 Proxy Authentication Required and a Basic Proxy-Authenticate challenge.
• Invalid credentials receive 407; clients denied by policy receive 403.
• ACLs are enforced before upstream HTTP requests or CONNECT connections are made.
• Proxy-Authorization is consumed by Hermes and is never forwarded upstream.

Destination domains and ports

Domain entries support exact names and leading-subdomain wildcards:

• example.com matches only that name.
• *.example.com matches www.example.com and a.b.example.com, but not the apex example.com or a lookalike such as evil-example.com.
• Domain matching is case-insensitive and normalizes one trailing DNS root dot. Use ports when port restrictions are also required.
• Single-label names such as localhost are supported. International domains must use ASCII/punycode form.
• IP literals never match domain patterns.

A domain whitelist uses default_action: deny with allow rules:

acl:
  default_action: deny
  rules:
    - name: approved-domains
      action: allow
      domains: ["example.com", "*.rust-lang.org"]
      ports: [80, 443]

A domain blacklist uses deny rules, typically with default_action: allow:

acl:
  default_action: allow
  rules:
    - name: blocked-domains
      action: deny
      domains: ["ads.example.net", "*.tracker.example"]

Domain and port selectors can be combined with users and/or networks when client and destination restrictions must both apply. A domain-only allow rule does not implicitly require authentication. Multiple ports are ORed; different selector types are ANDed. Ports must be in the range 1–65535, and omitting ports matches any destination port.

Domain matching is not destination-IP filtering. A hostname blacklist can be bypassed by connecting directly to an IP address. Hermes also does not inspect resolved addresses or provide DNS-rebinding protection. A domain-only whitelist with default_action: deny rejects IP-literal destinations unless another rule allows them.

Basic authentication

For Basic authentication, curl can supply proxy credentials with --proxy-user:

curl --proxy http://127.0.0.1:8080 \
  --proxy-user 'alice:your-password' \
  https://example.com/

Generate a password hash

cargo run -- hash-password

The helper prompts without echoing, confirms the password, and prints a versioned string in this format:

$hermes-sha256$v=1$<base64-salt>$<base64-digest>

Copy the complete string into the user's password_hash field. Hermes computes SHA-256(salt || password) using a cryptographically random 16-byte salt. No separate salt field is needed, and running the helper twice for the same password produces different salted hashes. Argon2id hashes from earlier configurations are not supported; regenerate them with the helper.

Password verification is synchronous and inexpensive, and digest comparisons are constant-time. Decoded password buffers are zeroized after use.

Fast password hashes can be brute-forced offline. Anyone who obtains the YAML can efficiently guess passwords and compare them with the stored salted SHA-256 digest. Use strong, unique passwords and protect the configuration file; this format deliberately trades password-cracking resistance for cheap request verification.

Basic authentication is not encrypted in transit. A client sending Basic credentials over cleartext HTTP exposes them to the network. Use Basic authentication only on localhost or a trusted private network unless downstream TLS is added. Do not expose Hermes publicly without appropriate network controls.

SOCKS5

Set socks5_listen_addr to enable a separate SOCKS5 listener alongside the HTTP proxy:

listen_addr: "127.0.0.1:8080"
socks5_listen_addr: "127.0.0.1:1080"
socks5_handshake_timeout_ms: 10000

The listener supports SOCKS5 CONNECT with IPv4, IPv6, and domain destinations. Domain destinations are resolved by Hermes; use --socks5-hostname with curl to request proxy-side DNS resolution:

# Client-side DNS with an IP destination
curl --socks5 127.0.0.1:1080 http://198.51.100.10/

# Proxy-side DNS with a domain destination
curl --socks5-hostname 127.0.0.1:1080 http://example.com/

# Username/password authentication using the configured ACL user
curl --socks5-hostname 127.0.0.1:1080 \
  --proxy-user 'alice:your-password' \
  http://example.com/

SOCKS5 reuses the ACL's salted password hashes and applies users, networks, domains, and ports before upstream dialing. Username/password negotiation is selected when required by the ACL; otherwise no-auth is used. Authentication is cleartext on the network, so restrict the listener to localhost or trusted networks. ACL denial returns SOCKS reply 0x02 before any upstream connection.

Only CONNECT is supported. SOCKS4, BIND, and UDP ASSOCIATE are not implemented. Docker users can publish the listener with -p 127.0.0.1:1080:1080 when it is enabled.

OpenTelemetry

Hermes exports traces, metrics, and logs independently to an OpenTelemetry Collector using OTLP/HTTP (protobuf). All settings come from telemetry in YAML; OTEL_* environment variables are not read.

telemetry:
  service_name: "hermes"
  log_filter: "info"
  resource_attributes:
    deployment.environment.name: "production"
  otlp:
    endpoint: "http://127.0.0.1:4318"
    timeout_ms: 10000
    headers: {}
    traces:
      sample_ratio: 1.0
    metrics:
      export_interval_ms: 60000
      temporality: "cumulative"
    logs: {}

The common otlp.endpoint is a base URL; Hermes appends /v1/traces, /v1/metrics, and /v1/logs. Set otlp.traces.endpoint, otlp.metrics.endpoint, or otlp.logs.endpoint to override a signal with an exact full URL. OTLP headers may contain credentials, so protect the configuration file and never log its contents.

Trace sample_ratio must be between 0 and 1. Metric temporality accepts cumulative or delta. Timeouts and export intervals must be greater than zero.

Traces and logs are batched, metrics are exported periodically, and all providers are flushed during shutdown. An unavailable collector does not prevent the proxy from forwarding traffic, although exporter errors may appear in stdout logs.

Local collector

examples/otel-collector.yaml receives OTLP/HTTP and prints telemetry to the collector log:

docker run --rm \
  -p 4318:4318 \
  -v "$PWD/examples/otel-collector.yaml:/etc/otelcol/config.yaml:ro" \
  otel/opentelemetry-collector:latest

In another terminal, run Hermes and send a request through it. The collector will print the exported resource spans, metrics, and log records.

Traces

• proxy.request: downstream plain HTTP server operation
• proxy.upstream: upstream HTTP client operation
• proxy.connect: CONNECT handshake and tunnel lifetime
• proxy.upstream_connect: upstream TCP connection establishment
• socks5.connect: SOCKS5 negotiation, authorization, upstream connection, and tunnel lifetime

For plain HTTP, incoming W3C traceparent and tracestate headers establish the parent context, and a new context is injected upstream. Trace context cannot be propagated inside an encrypted CONNECT tunnel. Request spans include the ACL decision, reason, and matched rule name without credentials.

Metrics

Hermes uses standard HTTP instrument names where applicable and adds proxy-specific instruments:

• hermes.proxy.requests
• http.server.request.duration
• http.server.active_requests
• http.client.request.duration
• hermes.proxy.errors
• hermes.proxy.tunnels.active
• hermes.proxy.tunnel.duration
• hermes.proxy.tunnel.bytes
• hermes.proxy.acl.decisions

Metric attributes are deliberately bounded. Tunnel and ACL metrics include proxy.protocol to distinguish HTTP, HTTP CONNECT, and SOCKS5. Raw URLs, destination hostnames, destination ports, usernames, rule names, and client addresses are not metric attributes.

Logs

Startup, shutdown, ACL decisions, request completion, request failures, and tunnel completion are emitted as structured tracing events. Logs emitted inside a trace span include its trace and span IDs in OTLP. Headers, bodies, passwords, authorization values, password hashes, and query strings are not logged by the proxy.

Limitations

• HTTP/1.1 downstream and upstream only; no HTTP/2 or gRPC proxying
• No downstream TLS, TLS interception, caching, rate limiting, or configuration hot reload
• No HTTP Upgrade forwarding other than CONNECT
• No dynamic configuration or Envoy xDS support

Development

cargo fmt --all -- --check
cargo test
cargo clippy --all-targets --all-features -- -D warnings