diff --git a/changelog.d/changed-16785-proxy-override-docs.md b/changelog.d/changed-16785-proxy-override-docs.md new file mode 100644 index 0000000000..3386ec5d5f --- /dev/null +++ b/changelog.d/changed-16785-proxy-override-docs.md @@ -0,0 +1 @@ +- `src/docs/env-vars.md` and `src/docs/security-model.md` now describe `HIVE_PROXY_ALLOW_PRIVATE_FORWARD` as it behaves since [#16785](https://github.com/hivecommons/hive/pull/16785): the destination guard covers plain-HTTP forwards, uninspected CONNECT tunnels and transparent-TLS passthrough, and the override lifts it for all three legs at once. The docs previously described the guard and its override as plain-HTTP-only. diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index a7836b8463..3abd2bb8fa 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -218,7 +218,7 @@ new value at the same time. | `HIVE_STATIC_DIR` | No | `/opt/hive/proxy/public` | Static asset directory for the Node proxy. | | `HIVE_PROXY_EGRESS_MARK` | No | `0x1112` | Packet mark exempted from the MITM egress redirect. | | `HIVE_PROXY_ADVISORY_OK` | No | `false` | Allows the spoke to start when the forced-proxy egress redirect cannot be installed (no `CAP_NET_ADMIN`/iptables). Enforcement becomes advisory-only — agents can bypass the proxy. Also gates whether the Go proxy trusts a self-asserted `Proxy-Authorization` header as agent identity when its UID map is unavailable (N7, #3841) — off by default, an unidentified caller is treated as `ADVISORY` (writes blocked) rather than whatever name it claims. See [security-model.md](security-model.md#5-network-and-credentials). | -| `HIVE_PROXY_ALLOW_PRIVATE_FORWARD` | No | `false` | Lifts the plain-HTTP forward destination guard ([#14082](https://github.com/hivecommons/hive/issues/14082)). Off by default: a non-CONNECT request through the proxy is dialled only when the resolved address is globally routable, so an agent cannot use the proxy to reach loopback services beside it, the link-local cloud metadata endpoint (`169.254.169.254`), RFC 1918/CGNAT cluster addresses or multicast, and the refusal is a `403` naming the class. Only the exact string `true` turns it on, for deployments that genuinely egress to a private network over plain HTTP (a LAN mirror on a native install). Loopback refusals stay at `DEBUG` and are not counted as violations, because agents are already handed `NO_PROXY` for loopback (#14076). | +| `HIVE_PROXY_ALLOW_PRIVATE_FORWARD` | No | `false` | Lifts the proxy's destination guard ([#14082](https://github.com/hivecommons/hive/issues/14082), [#16785](https://github.com/hivecommons/hive/pull/16785)). Off by default: a plain-HTTP (non-CONNECT) forward, a CONNECT to a host the proxy does not inspect, and a transparent-TLS passthrough are each dialled only when the resolved address is globally routable, so an agent cannot use the proxy to reach loopback services beside it, the link-local cloud metadata endpoint (`169.254.169.254`), RFC 1918/CGNAT cluster addresses or multicast, and the refusal is a `403` naming the class. Only the exact string `true` turns it on, and it lifts the guard for all three legs at once, for deployments that genuinely egress to a private network through the proxy (a LAN mirror on a native install); the proxy logs a boot-time warning when it is set. Loopback refusals stay at `DEBUG` and are not counted as violations, because agents are already handed `NO_PROXY` for loopback (#14076). | | `HIVE_PROXY_INJECT_GH_AUTH` | No | unset (off on every hive, including hosted) | Exact `true` enables proxy-side App-token injection. **Requires GitHub App auth. Refuses startup (exit 19) with `HIVE_PROXY_ADVISORY_OK=true`.** Other spellings do not enable it. Read [behavior and exceptions](#proxy-credential-injection). | | `HIVE_DEPLOYMENT_RUNTIME` | No | none (config `deployment.runtime` fallback; hub-registered Kubernetes hives are auto-detected) | Declares the deployment runtime (`kubernetes`, `podman-quadlet`, or `docker-compose`) so the dashboard can offer standalone upgrades. Unset/unrecognized means `unknown` and the upgrade button stays hidden. See [dashboard-standalone-upgrades.md](dashboard-standalone-upgrades.md). | | `HIVE_DEPLOYMENT_PODMAN_MODE` | Only when runtime is `podman-quadlet` | none (config `deployment.podman_mode` fallback) | `rootless` (`systemctl --user`) or `rootful` (system manager). Without an explicit mode the Podman/Quadlet upgrade path stays disabled. | diff --git a/src/docs/security-model.md b/src/docs/security-model.md index 51128bc668..63002704d2 100644 --- a/src/docs/security-model.md +++ b/src/docs/security-model.md @@ -196,17 +196,23 @@ process cannot forge. Only `api.github.com` is inspected; other hosts are tunnelled without inspection. See [net-admin-requirement.md](net-admin-requirement.md). -**Plain-HTTP forwards.** The redirect covers port 443 only, so plain HTTP -reaches the proxy through its explicit proxy port. Those forwards are -identified like any other request and dialled only when the resolved address -is globally routable: loopback services beside the proxy, the link-local -metadata endpoint, RFC 1918/CGNAT cluster addresses and multicast are refused -with `403` and counted as violations (loopback excepted — agents are handed -`NO_PROXY` for it, so it is logged as the client misconfiguration it is). The -check runs at dial time on the resolved address, so a hostname pointed inward -is refused on the same evidence as a literal IP. Set -`HIVE_PROXY_ALLOW_PRIVATE_FORWARD=true` only where a private-network plain-HTTP -destination is intended. +**Plain-HTTP forwards and uninspected tunnels.** The redirect covers port 443 +only, so plain HTTP reaches the proxy through its explicit proxy port. Those +forwards are identified like any other request and dialled only when the +resolved address is globally routable: loopback services beside the proxy, the +link-local metadata endpoint, RFC 1918/CGNAT cluster addresses and multicast +are refused with `403` and counted as violations (loopback excepted — agents +are handed `NO_PROXY` for it, so it is logged as the client misconfiguration it +is). The same policy applies to the tunnels the proxy does not inspect: a +CONNECT to a host other than the inspected API and the transparent-TLS +passthrough for such a host are dialled through the same guarded dialer, so +`CONNECT 169.254.169.254:80` or an SNI naming a cluster address is refused on +the same terms rather than tunnelled from the proxy's own uid. The check runs +at dial time on the resolved address, so a hostname pointed inward is refused +on the same evidence as a literal IP. Set +`HIVE_PROXY_ALLOW_PRIVATE_FORWARD=true` only where a private-network +destination is intended; it lifts the guard for all three legs at once, and the +proxy warns at boot when it is set. **Hub-to-spoke channel.** Heartbeats carry a per-hive bearer key derived from the hub master secret and are compared in constant time. The payload is