Compare commits

...

2 Commits

Author SHA1 Message Date
diegosouzapw
ba4384c8ec chore(changelog): name the benchmark-range fragment after its PR 2026-11-18 23:58:16 -03:00
diegosouzapw
0bc92ffc16 fix(security): opt-in block of 198.18.0.0/15 in the strict outbound guard
isPrivateHost() treats the RFC 2544 benchmarking range as public, on purpose: fake-IP proxies (Clash, Mihomo, Surge TUN) answer every name with an address in it (#15039). OMNIROUTE_BLOCK_BENCHMARK_RANGE=true now lets an operator without such a proxy treat the whole /15 as private in every spelling the guard reads. Default unchanged.
2026-11-18 23:54:38 -03:00
5 changed files with 159 additions and 0 deletions

View File

@@ -662,6 +662,15 @@ ALLOW_API_KEY_REVEAL=false
# Used by: src/shared/network/outboundUrlGuardPolicy.ts
# OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS=false
# Treat 198.18.0.0/15 (the RFC 2544 benchmarking range) as private in the strict public-only
# checks (caller-supplied image/media URLs, public-only DNS and connect-time guards). Off by
# default because fake-IP proxies (Clash, Mihomo, Surge in TUN mode) answer every name with an
# address in that range; turn it on only when no such proxy is in use and the range holds
# internal services.
# Used by: src/shared/network/privateHost.ts
# Default: false
# OMNIROUTE_BLOCK_BENCHMARK_RANGE=true
# Legacy alias; its dashboard toggle (a DB override) is read before this environment value.
# "false", "0", "no", or "off" in either turns the host checks off the way
# OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true does, even when that flag's dashboard toggle

View File

@@ -0,0 +1 @@
- **fix(security):** `OMNIROUTE_BLOCK_BENCHMARK_RANGE=true` makes the strict public-only outbound checks treat 198.18.0.0/15 (RFC 2544 benchmarking) as private; the range stays public by default for fake-IP proxies

View File

@@ -254,6 +254,7 @@ OmniRoute uses **SQLite** (via `better-sqlite3`) for all persistence. These vari
| `OUTBOUND_SSRF_GUARD_ENABLED` | `true` | `src/shared/network/outboundUrlGuardPolicy.ts` | Legacy alias. Its dashboard toggle (a DB override) is read before this environment value; `false`, `0`, `no`, or `off` in either turns the host checks off the way `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true` does, even when that flag's dashboard toggle is saved off; other values leave the guard to the two flags below. |
| `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS` | `false` | `src/shared/network/outboundUrlGuardPolicy.ts` | Turns off the outbound URL guard's host checks, cloud-metadata block included (all of 169.254.0.0/16, metadata.google.internal), on the provider paths that follow the guard mode: URL validation, model discovery, provider-node base URLs (including remote rerank nodes), and the proxy-fallback test, among other provider-adjacent outbound paths such as remote image/media fetch. It also allows private webhook targets, except cloud-metadata/link-local endpoints, which stay blocked even with this flag on. Chat requests dispatched through `BaseExecutor.execute()` keep their cloud-metadata check. Local providers work with the defaults: `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` (default `true`) already allows local and LAN URLs on the validation, discovery, and provider-node paths; the proxy-fallback test and private webhook targets consult only this flag and block local/LAN hosts while it is off. Overrides `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS=false`. A value saved from the dashboard toggle takes precedence over this variable. |
| `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` | `true` | `src/shared/network/outboundUrlGuardPolicy.ts` | Allow provider URLs on local/private addresses (127.0.0.1, localhost, LAN, private ranges) for provider validation, model discovery, chat, and the other provider-adjacent outbound paths the guard mode governs. **Default `true`** (local-first): the guard then blocks cloud-metadata endpoints — all of 169.254.0.0/16 plus the known metadata hostnames (metadata.google.internal, metadata.goog, Alibaba/Azure/Oracle IMDS, fd00:ec2::254). Set `false` for public-only mode, which blocks private and loopback hosts too. The guard checks the hostname or IP literal as written, before any DNS lookup; in public-only mode the safe-fetch wrapper additionally resolves the hostname and refuses any private answer. `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true` turns these checks off on the paths its row lists. Built-in local providers, such as LM Studio, Ollama, vLLM, Llamafile, and Triton, skip all host checks for key validation and chat. A value saved from the dashboard toggle takes precedence over this variable. (#5066) |
| `OMNIROUTE_BLOCK_BENCHMARK_RANGE` | `false` | `src/shared/network/privateHost.ts` | Treat 198.18.0.0/15 (RFC 2544 benchmarking range) as private in the strict public-only checks: caller-supplied image and media URLs and the public-only DNS and connect-time guards. Off by default because fake-IP proxies (Clash, Mihomo, Surge in TUN mode) answer every hostname with an address in that range, so blocking it would refuse every guarded download behind such a proxy (#15039). Set `true` only when no fake-IP proxy is in use and the range holds internal services. |
| `AUDIO_REMOTE_PROVIDER_NODES` | `false` | `src/app/api/v1/_shared/audioProviderNodes.ts` | Let the `/v1/audio/*` routes (transcriptions, speech, translations) use an OpenAI-compatible provider node hosted outside localhost. Off by default — routing audio to a remote host changes egress identity and must be an explicit operator decision. Loopback/private nodes (localhost, 127.0.0.1, 172.16-31.x) are always allowed and unaffected. (#3963) |
| `RERANK_REMOTE_PROVIDER_NODES` | `false` | `src/app/api/v1/_shared/rerankProviderNodes.ts` | Let `POST /v1/rerank` (and the memory engine's loopback rerank step) use an OpenAI-compatible provider node hosted outside localhost — a LAN box or Tailscale peer running TEI, Infinity, vLLM, etc. Off by default — routing to a remote host changes egress identity and must be an explicit operator decision. Loopback nodes (localhost, 127.0.0.1, 172.16-31.x) are always allowed and unaffected. A remote node's base URL must also pass the provider outbound URL policy (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`). |
| `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` | _(empty)_ | `src/shared/network/localNodeHosts.ts` | Hostnames (comma or whitespace separated) that provider-node routing treats as local — typically the Docker/Compose service name of a reranker, TEI or audio sidecar on OmniRoute's own Docker network (`http://reranker:8080/v1`), so the node does not need a hard-coded container IP. Listed hosts are eligible for `/v1/rerank`, `/v1/audio/*` and the local health check without turning on `RERANK_REMOTE_PROVIDER_NODES` / `AUDIO_REMOTE_PROVIDER_NODES` for every remote node, and are called directly — never through `HTTP(S)_PROXY` or a connection's pinned proxy. They still send the connection's API key. Only single-label names and `.internal`/`.local` names are accepted; public FQDNs, IP literals and cloud-metadata names are ignored with a warning. (#14635) |

View File

@@ -115,6 +115,17 @@ export function isSameIpv6Address(a: string, b: string): boolean {
return !!first && !!second && first.every((value, index) => value === second[index]);
}
/**
* 198.18.0.0/15 (RFC 2544 benchmarking) is never routed publicly, but it stays public by default:
* fake-IP proxies (Clash, Mihomo, Surge in TUN mode) answer every name with an address in it, so
* blocking it would refuse every guarded download behind such a proxy (#15039). An operator whose
* network has real internal services in that range opts in with
* OMNIROUTE_BLOCK_BENCHMARK_RANGE=true. Read on every call so a change applies without a restart.
*/
function blocksBenchmarkRange(): boolean {
return typeof process !== "undefined" && process.env?.OMNIROUTE_BLOCK_BENCHMARK_RANGE === "true";
}
export function isPrivateHost(hostname: string) {
const normalized = normalizeHost(hostname);
if (!normalized) return true;
@@ -150,6 +161,7 @@ export function isPrivateHost(hostname: string) {
// 192.0.0.0/24 (IETF protocol assignments), 224.0.0.0/4 multicast, and the Azure host
// fabric address.
if (a === 192 && b === 0 && c === 0) return true;
if (a === 198 && (b === 18 || b === 19) && blocksBenchmarkRange()) return true;
if (a >= 224 && a <= 239) return true;
// 240.0.0.0/4 reserved ("Class E"), whose top address is the limited broadcast
// 255.255.255.255. Never a public destination; some cloud networks use it as private space.

View File

@@ -0,0 +1,136 @@
/**
* 198.18.0.0/15 is reserved for network benchmarking (RFC 2544) and is never routed publicly.
* It stays public by default, because fake-IP proxies (Clash, Mihomo, Surge in TUN mode) answer
* every name with an address in it (#15039). With OMNIROUTE_BLOCK_BENCHMARK_RANGE=true the strict
* outbound guard refuses it like the other non-public IPv4 blocks: as a dotted IPv4, as
* IPv4-mapped IPv6 (compressed and expanded), as NAT64, in a URL, and as a DNS answer to
* `safeOutboundFetch({ guard: "public-only" })`. The addresses right outside the /15 stay public
* in both modes.
*
* Run with:
* node --import tsx/esm --test tests/unit/private-host-benchmark-range.test.ts
*/
import { afterEach, beforeEach, describe, it } from "node:test";
import assert from "node:assert/strict";
import {
isPrivateHost,
parseAndValidatePublicUrl,
OutboundUrlGuardError,
} from "../../src/shared/network/outboundUrlGuard.ts";
const { safeOutboundFetch, SafeOutboundFetchError } =
await import("../../src/shared/network/safeOutboundFetch.ts");
const FLAG = "OMNIROUTE_BLOCK_BENCHMARK_RANGE";
// Each entry: [IPv4 address, the same address as expanded IPv4-mapped IPv6, as NAT64].
const BENCHMARK = [
["198.18.0.0", "0:0:0:0:0:ffff:c612:0", "64:ff9b::c612:0"],
["198.18.0.1", "0:0:0:0:0:ffff:c612:1", "64:ff9b::c612:1"],
["198.19.255.254", "0:0:0:0:0:ffff:c613:fffe", "64:ff9b::c613:fffe"],
["198.19.255.255", "0:0:0:0:0:ffff:c613:ffff", "64:ff9b::c613:ffff"],
] as const;
// The addresses right outside 198.18.0.0/15.
const NEIGHBOURS = ["198.17.255.255", "198.20.0.0", "0:0:0:0:0:ffff:c611:ffff"];
async function guardCode(address: string): Promise<string | null> {
try {
await safeOutboundFetch("http://bench.alias.test:9/", {
guard: "public-only",
retry: false,
timeoutMs: 500,
dnsLookup: async () => [{ address, family: address.includes(":") ? 6 : 4 }],
});
return null;
} catch (error) {
return error instanceof SafeOutboundFetchError ? error.code : "OTHER";
}
}
let saved: string | undefined;
function restoreFlag() {
if (saved === undefined) delete process.env[FLAG];
else process.env[FLAG] = saved;
}
describe("198.18.0.0/15 by default - public, for fake-IP proxies", () => {
beforeEach(() => {
saved = process.env[FLAG];
delete process.env[FLAG];
});
afterEach(restoreFlag);
it("isPrivateHost treats every spelling as public", () => {
for (const [ipv4, mapped, nat64] of BENCHMARK) {
assert.equal(isPrivateHost(ipv4), false, ipv4);
assert.equal(isPrivateHost(mapped), false, mapped);
assert.equal(isPrivateHost(nat64), false, nat64);
}
});
it("parseAndValidatePublicUrl accepts the range", () => {
for (const [ipv4] of BENCHMARK) {
assert.doesNotThrow(() => parseAndValidatePublicUrl(`http://${ipv4}/v1`), ipv4);
}
});
it("safeOutboundFetch public-only does not refuse a fake-IP answer", async () => {
assert.notEqual(await guardCode("198.18.0.1"), "URL_GUARD_BLOCKED");
});
it("any value other than true keeps the default", () => {
for (const value of ["false", "1", "TRUE", ""]) {
process.env[FLAG] = value;
assert.equal(isPrivateHost("198.18.0.1"), false, JSON.stringify(value));
}
});
});
describe("198.18.0.0/15 with OMNIROUTE_BLOCK_BENCHMARK_RANGE=true - private", () => {
beforeEach(() => {
saved = process.env[FLAG];
process.env[FLAG] = "true";
});
afterEach(restoreFlag);
for (const [ipv4, mapped, nat64] of BENCHMARK) {
it(`isPrivateHost treats ${ipv4}, ${mapped} and ${nat64} as private`, () => {
assert.equal(isPrivateHost(ipv4), true);
assert.equal(isPrivateHost(mapped), true);
assert.equal(isPrivateHost(`[${mapped}]`), true);
assert.equal(isPrivateHost(nat64), true);
});
for (const url of [`http://${ipv4}/v1`, `http://[::ffff:${ipv4}]/v1`, `http://[${mapped}]/`]) {
it(`parseAndValidatePublicUrl rejects ${url}`, () => {
assert.throws(
() => parseAndValidatePublicUrl(url),
(error: unknown) => error instanceof OutboundUrlGuardError
);
});
}
}
it("keeps the neighbours public", () => {
for (const host of NEIGHBOURS) {
assert.equal(isPrivateHost(host), false, host);
}
for (const url of ["http://198.17.255.255/", "http://198.20.0.0/"]) {
assert.doesNotThrow(() => parseAndValidatePublicUrl(url), url);
}
});
for (const address of ["198.18.0.1", "198.19.255.254", "0:0:0:0:0:ffff:c612:1"]) {
it(`safeOutboundFetch public-only refuses a name resolving to ${address}`, async () => {
assert.equal(await guardCode(address), "URL_GUARD_BLOCKED");
});
}
it("safeOutboundFetch public-only does not refuse a neighbour address", async () => {
assert.notEqual(await guardCode("198.20.0.1"), "URL_GUARD_BLOCKED");
});
});