diff --git a/CHANGELOG.md b/CHANGELOG.md index 4edf42b68..3d00e7319 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ Docs: https://docs.clawd.bot ### Changes - TBD. +### Fixes +- Gateway: harden reverse proxy handling for local-client detection and unauthenticated proxied connects. (#1795) Thanks @orlyjamie. + ## 2026.1.24-2 ### Fixes diff --git a/docs/gateway/security.md b/docs/gateway/security.md index ed0054411..05e1673c6 100644 --- a/docs/gateway/security.md +++ b/docs/gateway/security.md @@ -63,6 +63,23 @@ downgrade—prefer HTTPS (Tailscale Serve) or open the UI on `127.0.0.1`. `clawdbot security audit` warns when this setting is enabled. +## Reverse Proxy Configuration + +If you run the Gateway behind a reverse proxy (nginx, Caddy, Traefik, etc.), you should configure `gateway.trustedProxies` for proper client IP detection. + +When the Gateway detects proxy headers (`X-Forwarded-For` or `X-Real-IP`) from an address that is **not** in `trustedProxies`, it will **not** treat connections as local clients. If gateway auth is disabled, those connections are rejected. This prevents authentication bypass where proxied connections would otherwise appear to come from localhost and receive automatic trust. + +```yaml +gateway: + trustedProxies: + - "127.0.0.1" # if your proxy runs on localhost + auth: + mode: password + password: ${CLAWDBOT_GATEWAY_PASSWORD} +``` + +When `trustedProxies` is configured, the Gateway will use `X-Forwarded-For` headers to determine the real client IP for local client detection. Make sure your proxy overwrites (not appends to) incoming `X-Forwarded-For` headers to prevent spoofing. + ## Local session logs live on disk Clawdbot stores session transcripts on disk under `~/.clawdbot/agents//sessions/*.jsonl`. diff --git a/src/gateway/server.auth.e2e.test.ts b/src/gateway/server.auth.e2e.test.ts index a2645a75d..17a8802b2 100644 --- a/src/gateway/server.auth.e2e.test.ts +++ b/src/gateway/server.auth.e2e.test.ts @@ -351,6 +351,27 @@ describe("gateway server auth/connect", () => { } }); + test("rejects proxied connections without auth when proxy headers are untrusted", async () => { + const prevToken = process.env.CLAWDBOT_GATEWAY_TOKEN; + delete process.env.CLAWDBOT_GATEWAY_TOKEN; + const port = await getFreePort(); + const server = await startGatewayServer(port); + const ws = new WebSocket(`ws://127.0.0.1:${port}`, { + headers: { "x-forwarded-for": "203.0.113.10" }, + }); + await new Promise((resolve) => ws.once("open", resolve)); + const res = await connectReq(ws); + expect(res.ok).toBe(false); + expect(res.error?.message ?? "").toContain("gateway auth required"); + ws.close(); + await server.close(); + if (prevToken === undefined) { + delete process.env.CLAWDBOT_GATEWAY_TOKEN; + } else { + process.env.CLAWDBOT_GATEWAY_TOKEN = prevToken; + } + }); + test("accepts device token auth for paired device", async () => { const { loadOrCreateDeviceIdentity } = await import("../infra/device-identity.js"); const { approveDevicePairing, getPairedDevice, listDevicePairing } = diff --git a/src/gateway/server/ws-connection/message-handler.ts b/src/gateway/server/ws-connection/message-handler.ts index 5ef3f26e7..35265ce63 100644 --- a/src/gateway/server/ws-connection/message-handler.ts +++ b/src/gateway/server/ws-connection/message-handler.ts @@ -26,7 +26,7 @@ import type { ResolvedGatewayAuth } from "../../auth.js"; import { authorizeGatewayConnect } from "../../auth.js"; import { loadConfig } from "../../../config/config.js"; import { buildDeviceAuthPayload } from "../../device-auth.js"; -import { isLocalGatewayAddress, resolveGatewayClientIp } from "../../net.js"; +import { isLocalGatewayAddress, isTrustedProxyAddress, resolveGatewayClientIp } from "../../net.js"; import { resolveNodeCommandAllowlist } from "../../node-command-policy.js"; import { type ConnectParams, @@ -177,7 +177,24 @@ export function attachGatewayWsMessageHandler(params: { const configSnapshot = loadConfig(); const trustedProxies = configSnapshot.gateway?.trustedProxies ?? []; const clientIp = resolveGatewayClientIp({ remoteAddr, forwardedFor, realIp, trustedProxies }); - const isLocalClient = isLocalGatewayAddress(clientIp); + + // If proxy headers are present but the remote address isn't trusted, don't treat + // the connection as local. This prevents auth bypass when running behind a reverse + // proxy without proper configuration - the proxy's loopback connection would otherwise + // cause all external requests to be treated as trusted local clients. + const hasProxyHeaders = Boolean(forwardedFor || realIp); + const remoteIsTrustedProxy = isTrustedProxyAddress(remoteAddr, trustedProxies); + const hasUntrustedProxyHeaders = hasProxyHeaders && !remoteIsTrustedProxy; + const isLocalClient = !hasUntrustedProxyHeaders && isLocalGatewayAddress(clientIp); + const reportedClientIp = hasUntrustedProxyHeaders ? undefined : clientIp; + + if (hasUntrustedProxyHeaders) { + logWsControl.warn( + "Proxy headers detected from untrusted address. " + + "Connection will not be treated as local. " + + "Configure gateway.trustedProxies to restore local client detection behind your proxy.", + ); + } const isWebchatConnect = (p: ConnectParams | null | undefined) => isWebchatClient(p?.client); @@ -322,6 +339,31 @@ export function attachGatewayWsMessageHandler(params: { const isControlUi = connectParams.client.id === GATEWAY_CLIENT_IDS.CONTROL_UI; const allowInsecureControlUi = isControlUi && configSnapshot.gateway?.controlUi?.allowInsecureAuth === true; + if (hasUntrustedProxyHeaders && resolvedAuth.mode === "none") { + setHandshakeState("failed"); + setCloseCause("proxy-auth-required", { + client: connectParams.client.id, + clientDisplayName: connectParams.client.displayName, + mode: connectParams.client.mode, + version: connectParams.client.version, + }); + send({ + type: "res", + id: frame.id, + ok: false, + error: errorShape( + ErrorCodes.INVALID_REQUEST, + "gateway auth required behind reverse proxy", + { + details: { + hint: "set gateway.auth or configure gateway.trustedProxies", + }, + }, + ), + }); + close(1008, "gateway auth required"); + return; + } if (!device) { const canSkipDevice = allowInsecureControlUi ? hasSharedAuth : hasTokenAuth; @@ -581,7 +623,7 @@ export function attachGatewayWsMessageHandler(params: { clientMode: connectParams.client.mode, role, scopes, - remoteIp: clientIp, + remoteIp: reportedClientIp, silent: isLocalClient, }); const context = buildRequestContext(); @@ -665,7 +707,7 @@ export function attachGatewayWsMessageHandler(params: { clientMode: connectParams.client.mode, role, scopes, - remoteIp: clientIp, + remoteIp: reportedClientIp, }); } } @@ -714,7 +756,7 @@ export function attachGatewayWsMessageHandler(params: { if (presenceKey) { upsertPresence(presenceKey, { host: connectParams.client.displayName ?? connectParams.client.id ?? os.hostname(), - ip: isLocalClient ? undefined : clientIp, + ip: isLocalClient ? undefined : reportedClientIp, version: connectParams.client.version, platform: connectParams.client.platform, deviceFamily: connectParams.client.deviceFamily, @@ -773,7 +815,9 @@ export function attachGatewayWsMessageHandler(params: { setHandshakeState("connected"); if (role === "node") { const context = buildRequestContext(); - const nodeSession = context.nodeRegistry.register(nextClient, { remoteIp: clientIp }); + const nodeSession = context.nodeRegistry.register(nextClient, { + remoteIp: reportedClientIp, + }); const instanceIdRaw = connectParams.client.instanceId; const instanceId = typeof instanceIdRaw === "string" ? instanceIdRaw.trim() : ""; const nodeIdsForPairing = new Set([nodeSession.nodeId]); diff --git a/src/security/audit.test.ts b/src/security/audit.test.ts index cd7df057e..0051b753f 100644 --- a/src/security/audit.test.ts +++ b/src/security/audit.test.ts @@ -53,6 +53,30 @@ describe("security audit", () => { ).toBe(true); }); + it("warns when loopback control UI lacks trusted proxies", async () => { + const cfg: ClawdbotConfig = { + gateway: { + bind: "loopback", + controlUi: { enabled: true }, + }, + }; + + const res = await runSecurityAudit({ + config: cfg, + includeFilesystem: false, + includeChannelSecurity: false, + }); + + expect(res.findings).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + checkId: "gateway.trusted_proxies_missing", + severity: "warn", + }), + ]), + ); + }); + it("flags logging.redactSensitive=off", async () => { const cfg: ClawdbotConfig = { logging: { redactSensitive: "off" }, diff --git a/src/security/audit.ts b/src/security/audit.ts index 87e6e3397..db51d576f 100644 --- a/src/security/audit.ts +++ b/src/security/audit.ts @@ -207,6 +207,10 @@ function collectGatewayConfigFindings(cfg: ClawdbotConfig): SecurityAuditFinding const bind = typeof cfg.gateway?.bind === "string" ? cfg.gateway.bind : "loopback"; const tailscaleMode = cfg.gateway?.tailscale?.mode ?? "off"; const auth = resolveGatewayAuth({ authConfig: cfg.gateway?.auth, tailscaleMode }); + const controlUiEnabled = cfg.gateway?.controlUi?.enabled !== false; + const trustedProxies = Array.isArray(cfg.gateway?.trustedProxies) + ? cfg.gateway.trustedProxies + : []; if (bind !== "loopback" && auth.mode === "none") { findings.push({ @@ -218,6 +222,20 @@ function collectGatewayConfigFindings(cfg: ClawdbotConfig): SecurityAuditFinding }); } + if (bind === "loopback" && controlUiEnabled && trustedProxies.length === 0) { + findings.push({ + checkId: "gateway.trusted_proxies_missing", + severity: "warn", + title: "Reverse proxy headers are not trusted", + detail: + "gateway.bind is loopback and gateway.trustedProxies is empty. " + + "If you expose the Control UI through a reverse proxy, configure trusted proxies " + + "so local-client checks cannot be spoofed.", + remediation: + "Set gateway.trustedProxies to your proxy IPs or keep the Control UI local-only.", + }); + } + if (tailscaleMode === "funnel") { findings.push({ checkId: "gateway.tailscale_funnel",