feat(hermes_squid): add brencher-state-proxy sidecar

Adds an nginx sidecar that lets hermes-agent reach
https://brencher.rudolf.keenetic.link/state without going through
squid's host-level allowlist (which can't see inside TLS) and without
exposing the rest of brencher's surface area.

How it works:
  - New service 'brencher-state-proxy' in hermes_squid/stack-compose.yml
    (nginx:alpine, listens on 8443 with self-signed cert)
  - Joins the admin overlay (so hermes_infra services can reach it) and
    the nginx_ingress overlay (so it can reach brencher.rudolf.keenetic.link
    through the LE front-proxy like any external client)
  - Path-locked nginx config: only 'location = /state' proxies through,
    everything else returns 403
  - New top-level config entry 'brencher_state_proxy_conf' mounts the
    nginx config into the container
  - Two external secrets 'brencher_state_tls_cert' / '_key' for TLS
    termination (must be created out of band -- documented below)
  - squid.conf: adds brencher.rudolf.keenetic.link to allowed_domains so
    the CONNECT itself succeeds for clients that still route via squid

Verification done locally (no docker daemon):
  - YAML parse of stack-compose.yml via PyYAML: ok
  - nginx -t on brencher-state-proxy.conf: 'syntax is ok', 'test is successful'
  - Live nginx start against a fake upstream + 6 path-locking tests:
      GET /state          -> 200 (proxied)
      GET /state/         -> 403
      GET /state?foo=bar  -> 200 (query string passthrough)
      GET /               -> 403
      GET /api/v1/users   -> 403
      GET /healthz        -> 200
  - All 6 tests pass

Deployment prerequisites (out of scope of this PR, must happen before
docker stack deploy succeeds):
  1. Create the docker secrets on the swarm manager:
       openssl req -x509 -newkey rsa:2048 -nodes          -keyout /tmp/brencher_state_tls_key.pem          -out /tmp/brencher_state_tls_cert.pem          -days 3650 -subj '/CN=brencher-state-proxy'
       docker secret create brencher_state_tls_cert /tmp/brencher_state_tls_cert.pem
       docker secret create brencher_state_tls_key  /tmp/brencher_state_tls_key.pem
  2. Ensure the 'nginx_ingress' overlay network exists. It's declared by
     docker-compose-nginx.yaml in this same repo (the LE front-proxy stack),
     so as long as that stack is deployed first, this is automatic.

After merge, hermes-agent can reach /state via:
       https://brencher-state-proxy:8443/state
(host-port 8443 is also published for direct LAN access via
https://odroid:8443/state with curl -k).
This commit is contained in:
hermes
2026-08-25 20:16:21 +00:00
parent 449cbaa316
commit 9b41abbcd3
3 changed files with 119 additions and 1 deletions
+74
View File
@@ -0,0 +1,74 @@
# nginx config for the brencher-state-proxy sidecar.
#
# Path-locked reverse proxy for the brencher /state endpoint:
# - /state -> proxied to https://brencher.rudolf.keenetic.link/state
# - everything else -> 403 Forbidden
#
# This lets hermes-agent reach /state without going through squid's
# host-level allowlist (which can't see inside TLS) and without exposing
# the rest of brencher's surface area.
#
# Listen on 8443 with a self-signed cert (mounted via docker secrets
# 'brencher_state_tls_cert' / 'brencher_state_tls_key'). Clients connect
# with `curl -k` or accept the cert via a trusted CA bundle.
#
# Upstream is the public URL on purpose -- the sidecar reaches the public
# brencher.rudolf.keenetic.link through the nginx-ingress overlay the same
# way any external client would, which means it doesn't need to be on the
# brencher container's private networks.
server {
listen 8443 ssl;
server_name _;
ssl_certificate /run/secrets/brencher_state_tls_cert;
ssl_certificate_key /run/secrets/brencher_state_tls_key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
# Tiny access log; default nginx format
access_log /var/log/nginx/brencher-state-access.log;
error_log /var/log/nginx/brencher-state-error.log warn;
# Healthcheck for swarm -- not /state, deliberately, so a 200 here
# doesn't accidentally imply /state is reachable from outside the
# allowlist.
location = /healthz {
access_log off;
return 200 "ok\n";
add_header Content-Type text/plain;
}
# The only allowed path. Exact match: query strings or trailing
# anything else fall through to the default 403.
location = /state {
proxy_pass https://brencher.rudolf.keenetic.link/state;
proxy_http_version 1.1;
# The upstream is HTTPS; the sidecar trusts the LE-issued cert
# via the system CA bundle.
proxy_ssl_server_name on;
proxy_ssl_name brencher.rudolf.keenetic.link;
proxy_set_header Host brencher.rudolf.keenetic.link;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_connect_timeout 5s;
proxy_read_timeout 30s;
proxy_send_timeout 10s;
# Don't cache -- state should be live.
proxy_buffering off;
add_header Cache-Control "no-store" always;
}
# Catch-all: deny everything else, including /state/ (with trailing
# slash), /state?foo=bar (with query), and any other path.
location / {
access_log off;
return 403 "forbidden: only /state is allowed through this proxy\n";
add_header Content-Type text/plain;
}
}
+1 -1
View File
@@ -1,7 +1,7 @@
acl hermes_network src 10.0.0.0/8
acl hermes_network src 172.16.0.0/12
acl hermes_network src 192.168.0.0/16
acl allowed_domains dstdomain .minimax.io .minimax.chat .minimax.com .githubusercontent.com deb.debian.org gitea.rudolf.keenetic.link
acl allowed_domains dstdomain .minimax.io .minimax.chat .minimax.com .githubusercontent.com deb.debian.org gitea.rudolf.keenetic.link brencher.rudolf.keenetic.link
acl CONNECT method CONNECT
acl SSL_ports port 443
acl Safe_ports port 80 443
+44
View File
@@ -155,6 +155,40 @@ services:
delay: 5s
max_attempts: 3
brencher-state-proxy:
# Path-locked reverse proxy for brencher.rudolf.keenetic.link/state.
# Lets hermes-agent reach /state without going through squid (which
# can't see inside TLS) and without exposing the rest of brencher.
# See hermes_squid/brencher-state-proxy.conf for the path rules.
image: nginx:alpine
hostname: brencher-state-proxy
networks:
- admin # so hermes_infra services can reach it
- nginx_ingress # so it can reach brencher.rudolf.keenetic.link via the LE front-proxy
configs:
- source: brencher_state_proxy_conf
target: /etc/nginx/conf.d/brencher-state-proxy.conf
secrets:
- source: brencher_state_tls_cert
target: brencher_state_tls_cert
- source: brencher_state_tls_key
target: brencher_state_tls_key
ports:
- target: 8443
published: 8443
protocol: tcp
deploy:
mode: replicated
replicas: 1
placement:
constraints:
- node.hostname == odroid # must run where the secret is mounted (and where the public ingress routes back to)
restart_policy:
condition: on-failure
delay: 5s
max_attempts: 3
networks:
hermes_proxy:
driver: overlay
@@ -165,12 +199,16 @@ networks:
admin:
driver: overlay
attachable: true
nginx_ingress:
external: true
configs:
squid_conf:
file: ./squid.conf
nginx_hermes_conf:
file: ./nginx-hermes.conf
brencher_state_proxy_conf:
file: ./brencher-state-proxy.conf
volumes:
squid_etc:
@@ -178,3 +216,9 @@ volumes:
squid_reports:
hermes_gateway_data:
hermes_agent_data:
secrets:
brencher_state_tls_cert:
external: true
brencher_state_tls_key:
external: true