mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-17 04:17:51 +00:00
154 lines
6.2 KiB
Markdown
154 lines
6.2 KiB
Markdown
# ADR-003: HTTP Warning for Non-Private Hosts
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
When connecting to a SearXNG instance over HTTP, search queries are transmitted
|
|
in clear text without encryption. This is a security concern for public networks
|
|
where queries could be intercepted by network observers.
|
|
|
|
The earlier version of this decision classified a host as "private" using a
|
|
hand-maintained TLD suffix list (`.lan`, `.internal`, `.local`, `.home`,
|
|
`.corp`, `.intranet`) on top of literal IP range checks. As of 2026 the IANA
|
|
root zone lists over 1,500 gTLDs and ccTLDs, and the private/internal TLD
|
|
landscape is similarly fragmented: `.home.arpa` is IETF-standardized by
|
|
RFC 7788 / RFC 8375, `.localhost` is reserved by RFC 6761, `.local` is the
|
|
mDNS namespace defined by RFC 6762 (link-local name resolution, not
|
|
"private network"), and the remaining suffixes on the old list are de-facto
|
|
conventions that vary by organization. A hardcoded suffix list is impossible
|
|
to keep complete, easy to bypass with an unlisted suffix, and cannot be
|
|
audited against any external standard.
|
|
|
|
## Decision
|
|
|
|
Warn (but do not block) when using HTTP for non-private hosts on every invocation.
|
|
This warning cannot be disabled - there is no opt-out mechanism.
|
|
|
|
`isPrivateHost()` returns `true` if and only if the host matches one of the
|
|
RFC-grounded criteria below. The check is purely syntactic — it does not
|
|
perform DNS resolution, does not consult any local suffix allowlist, and
|
|
returns `false` for any hostname that is not RFC 6761-special or a literal
|
|
address in one of the listed ranges.
|
|
|
|
### Hostname (RFC 6761 — Special-Use Domain Names)
|
|
|
|
| Form | Reference |
|
|
|------|-----------|
|
|
| `localhost` (case-insensitive exact match) | RFC 6761 §6.3 |
|
|
| `*.localhost` (suffix match) | RFC 6761 §6.3 |
|
|
|
|
### IPv4 address ranges
|
|
|
|
| Range | Reference |
|
|
|-------|-----------|
|
|
| `0.0.0.0/8` (current network) | RFC 1122 §3.2.1.3, RFC 6890 §2.1 |
|
|
| `10.0.0.0/8` (private) | RFC 1918 §3 |
|
|
| `100.64.0.0/10` (CGNAT / shared address space) | RFC 6598 |
|
|
| `127.0.0.0/8` (loopback) | RFC 1122 §3.2.1.3, RFC 6890 §2.2 |
|
|
| `169.254.0.0/16` (link-local) | RFC 3927, RFC 6890 §2.4 |
|
|
| `172.16.0.0/12` (private) | RFC 1918 §3 |
|
|
| `192.0.0.0/24` (IETF protocol assignments) | RFC 6890 §2.5 |
|
|
| `192.0.2.0/24` (TEST-NET-1) | RFC 5737 |
|
|
| `192.88.99.0/24` (6to4 anycast, RFC 7526 deprecated) | RFC 7526 |
|
|
| `192.168.0.0/16` (private) | RFC 1918 §3 |
|
|
| `198.18.0.0/15` (benchmarking) | RFC 2544, RFC 6890 §2.6 |
|
|
| `198.51.100.0/24` (TEST-NET-2) | RFC 5737 |
|
|
| `203.0.113.0/24` (TEST-NET-3) | RFC 5737 |
|
|
| `224.0.0.0/4` (multicast) | RFC 5771, RFC 6890 §2.7 |
|
|
| `255.255.255.255/32` (limited broadcast) | RFC 8190, RFC 6890 §2.8 |
|
|
|
|
### IPv6 address ranges
|
|
|
|
| Range | Reference |
|
|
|-------|-----------|
|
|
| `::` (unspecified) | RFC 4291 §2.5.2 |
|
|
| `::1` (loopback) | RFC 4291 §2.5.3 |
|
|
| `fc00::/7` (unique local) | RFC 4193 |
|
|
| `fe80::/10` (link-local) | RFC 4291 §2.5.6 |
|
|
| `ff00::/8` (multicast) | RFC 4291 §2.7 |
|
|
|
|
### Explicitly NOT considered private
|
|
|
|
The following suffixes were on the earlier hand-maintained list and are
|
|
**removed** because none of the cited RFCs reserves them for "private network"
|
|
use. Hosts matching these suffixes will now
|
|
trigger the HTTP warning:
|
|
|
|
- `*.lan` — no RFC reservation
|
|
- `*.internal` — no RFC reservation
|
|
- `*.local` — RFC 6762 (mDNS link-local name resolution); the suffix is for
|
|
local name resolution, not a "private network" indicator
|
|
- `*.home` — RFC 8375 §1 explicitly deprecates `.home` in favor of
|
|
`.home.arpa`; not reserved for arbitrary private use
|
|
- `*.corp` — no RFC reservation
|
|
- `*.intranet` — no RFC reservation
|
|
|
|
The check is intentionally literal — there is no DNS resolution and no
|
|
suffix allowlist. Users who need a private-network exception for a custom
|
|
suffix must use a literal RFC 1918/4193 address, an `localhost` hostname,
|
|
or terminate TLS in front of SearXNG.
|
|
|
|
## Warning Message
|
|
|
|
When HTTP is used for a non-private host:
|
|
"Using HTTP for non-private host. Search queries may be transmitted in clear text.
|
|
Search results could be intercepted and modified by a MITM attacker."
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- The "private" predicate is fully auditable: every accepted hostname
|
|
matches RFC 6761, and every accepted IP range is named in the published
|
|
RFCs above. There is no internal suffix list to drift out of date.
|
|
- Removing the speculative suffix list eliminates guessing based on
|
|
suffixes such as `.home.arpa`, organization-specific suffixes, or
|
|
public TLDs that happen to match previous conventions such as `*.corp`.
|
|
- Users running a SearXNG instance on `*.lan` / `*.local` will see the
|
|
HTTP warning and are nudged to either terminate TLS or bind the
|
|
instance to a literal RFC 1918/4193 address.
|
|
|
|
### Negative
|
|
|
|
- Users on private networks with HTTP and a non-RFC 6761 hostname
|
|
(e.g. `printer.local`) will see the warning. This is an intentional,
|
|
accepted behavior change — see "Accepted trade-offs" below.
|
|
- Warning fatigue may cause users to ignore real security issues.
|
|
- The HTTP warning is not a security control on its own; the real
|
|
defenses are redirect safety (ADR-008) and the user's choice of
|
|
URL.
|
|
|
|
### Accepted trade-offs
|
|
|
|
- Hosts matching the removed suffixes (`.lan`, `.local`, `.internal`,
|
|
`.home`, `.corp`, `.intranet`) are no longer classified as private.
|
|
This is accepted because the previous classification was ungrounded
|
|
and the user has agreed (in the issue thread) to surface the warning
|
|
for these hosts in exchange for a contract that is auditable
|
|
against published RFCs.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Block HTTP entirely
|
|
|
|
Rejected: Would break valid use cases for internal infrastructure testing.
|
|
|
|
### Allow opt-out via environment variable
|
|
|
|
Rejected: This is intentionally a no-opt-out decision. Organizations that need
|
|
HTTP-only setups should use private network detection or accept the warning.
|
|
|
|
### Keep the speculative TLD list and add `.home.arpa`
|
|
|
|
Rejected: any non-RFC suffix list inherits the maintenance and bypass
|
|
problems described in Context. The RFC 6761-only contract is the smallest
|
|
auditable set.
|
|
|
|
### Resolve the hostname and check the resulting IP
|
|
|
|
Rejected: introduces DNS resolution, TOCTOU windows, and resolver
|
|
behavior variance across environments. ADR-007 also decides that
|
|
DNS-rebinding-class defenses are out of scope for this codebase.
|