Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/changed-16785-proxy-override-docs.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
28 changes: 17 additions & 11 deletions src/docs/security-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading