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
6 changes: 6 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@
# Clients send it in the X-API-Key header; the web UI asks for it on first 401.
PATCHRADAR_API_KEY=

# Optional: names the web UI is reached by besides localhost, 127.0.0.1 and [::1]
# on port 8000, comma-separated; any other Host is refused with 421 (DNS
# rebinding). `name` for any port, `name:port` for that port only: a reverse
# proxy's name, or localhost:9000 when the port is published as 9000.
PATCHRADAR_ALLOWED_HOSTS=

# Optional: raises NVD's rate limit from 5 to 50 requests per 30 seconds.
# https://nvd.nist.gov/developers/request-an-api-key
NVD_API_KEY=
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,23 @@ what has already shipped, and for nothing else. See `RELEASING.md`.

### Security

- **The web UI answers only to its own names: DNS rebinding is refused.** The server never looked
at `Host`. A page on a name the attacker controls, made to resolve to 127.0.0.1, is the same origin
as `http://that-name:8000` for the browser, which therefore sends `Sec-Fetch-Site: same-origin`, an
`Origin` equal to `Host`, and lets the page read the answers: the bug hunt of 2026-11-17 added a
watchlist entry and read `GET /api/watchlist` — the software installed and its versions — with
`Host: rebind.evil.example:8000`, so "a page you visit cannot add to your watchlist" did not hold.
Every request, reads and `/static` included, is now refused with 421 Misdirected Request unless its
`Host` is `localhost`, `127.0.0.1` or `[::1]` on the port the server listens on (or with no port),
the address the connection arrived on, or a name in the new `PATCHRADAR_ALLOWED_HOSTS`
(comma-separated, `name` for any port, `name:port` for that one, no wildcard); a missing or
malformed `Host` is a 400. For a browser that sends no `Sec-Fetch-Site`, the write guard compares
`Origin` with those hosts, port included, instead of with the request's own `Host`, which the
rebinding page sets; an `Origin` with brackets around something that is not an IPv6 address, such
as `http://[1.2]`, is a 403 where it was a 500. Who reaches the UI through a reverse proxy that passes its own `Host`, a LAN
name or a Docker port other than 8000 adds that name to the variable; `docker-compose.yml` and
`.env.example` pass it through. `tests/test_host_check.py`.

- **opentelemetry-api 1.45.2** in `uv.lock`, from 1.45.1. The older release parses a `traceparent`
header in quadratic time, a denial of service (CVE-2026-126360, GHSA-mf5v-w3w3-f6cg, medium,
published 2026-11-13); 1.45.2, on PyPI since 2026-10-29, is the release the advisory names as fixed.
Expand Down
4 changes: 3 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,4 +77,6 @@ scansioni datate. Per una release già uscita:
(`_get_over_https`): Cellar risponde con un 303 verso `http://`.
- Chiavi lette dall'ambiente: `NVD_API_KEY` (facoltativa), `VULDB_API_KEY` (senza,
VulDB non viene interrogato), `PATCHRADAR_API_KEY` (protegge solo le scritture
dell'API), `PATCHRADAR_HOME` (sposta solo la cache dei testi di legge).
dell'API), `PATCHRADAR_ALLOWED_HOSTS` (nomi a cui l'interfaccia web risponde oltre
al loopback; ogni altro `Host` riceve 421), `PATCHRADAR_HOME` (sposta solo la cache
dei testi di legge).
18 changes: 16 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,8 +177,19 @@ meant for use on the same machine: `patchradar serve` listens on 127.0.0.1 and t
`docker-compose.yml` publishes the port on 127.0.0.1 only. Set the key (see
`.env.example`) before exposing it any further. Either way, a write that a browser
sends on behalf of another web site (`Sec-Fetch-Site: cross-site`, or an `Origin`
that is not this server) is refused with 403, so a page you visit cannot add to your
watchlist or start scans through your browser.
that is not this server) is refused with 403, and every request — reads and static
files included — whose `Host` is not a name the server answers to is refused with
421 Misdirected Request. So a page you visit cannot read your watchlist, add to it or
start scans through your browser, not even by making its own name resolve to
127.0.0.1 (DNS rebinding).

The server answers to `localhost`, `127.0.0.1` and `[::1]` on the port it listens on,
and to the address a connection arrived on (`http://192.168.1.10:8000` with
`--host 0.0.0.0`). Any other name — a reverse proxy that passes its own `Host`, a
LAN name, a port Docker remaps such as `-p 127.0.0.1:9000:8000` — goes in
`PATCHRADAR_ALLOWED_HOSTS`, comma-separated: `name` for any port, `name:port` for
that port only, for example `PATCHRADAR_ALLOWED_HOSTS=patchradar.lan,localhost:9000`.
There is no wildcard.

On Windows, `scripts/import-winget.ps1` fills the watchlist from `winget list`:

Expand Down Expand Up @@ -289,6 +300,9 @@ the response times, how customers are told and how to roll back.
only: anyone who can reach the port can read the watchlist and the CVEs found, with
or without the key, over plain HTTP. Keep it on 127.0.0.1, as the default and
`docker-compose.yml` do, or put it behind a proxy with TLS and authentication.
Against web pages acting through your browser, cross-site writes are refused, and so
is any request for a `Host` the server does not answer to, which closes DNS rebinding
(see [Web UI](#web-ui) for `PATCHRADAR_ALLOWED_HOSTS`).

Every GitHub release carries CycloneDX SBOMs of the Docker image and of the Python
environment, and dated Trivy reports of the image and of the repository at the tag.
Expand Down
6 changes: 4 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,10 @@ listens on all of the container's interfaces. The optional `PATCHRADAR_API_KEY`
protects only the endpoints that change the watchlist or start a scan: the watchlist
and the vulnerabilities found are readable by anyone who can reach the port, with or
without the key, over plain HTTP. Keep it on loopback, or put it behind a proxy that
adds TLS and authentication. The details are in question 2 of
[docs/nis2-compliance.md](docs/nis2-compliance.md).
adds TLS and authentication. Requests whose `Host` is not one the server answers to
— the loopback names, the address the connection arrived on, and the names in
`PATCHRADAR_ALLOWED_HOSTS` — are refused with 421, which closes DNS rebinding. The
details are in question 2 of [docs/nis2-compliance.md](docs/nis2-compliance.md).

## Evidence attached to every release

Expand Down
2 changes: 1 addition & 1 deletion benchmarks/test_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
@pytest.fixture
def client(loop, seeded_db):
transport = ASGITransport(app=app)
http_client = AsyncClient(transport=transport, base_url="http://bench")
http_client = AsyncClient(transport=transport, base_url="http://localhost")
yield http_client
loop.run_until_complete(http_client.aclose())

Expand Down
3 changes: 3 additions & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ services:
environment:
# read from .env (see .env.example); unset or empty means "no key"
PATCHRADAR_API_KEY: ${PATCHRADAR_API_KEY:-}
# names besides localhost:8000 the UI is opened by, e.g. after changing the
# published port above; any other Host is refused (see .env.example)
PATCHRADAR_ALLOWED_HOSTS: ${PATCHRADAR_ALLOWED_HOSTS:-}
NVD_API_KEY: ${NVD_API_KEY:-}
volumes:
# must match the Dockerfile VOLUME: the image runs as the unprivileged
Expand Down
16 changes: 14 additions & 2 deletions docs/nis2-compliance.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,20 @@ conta:
sulla rete se davanti non c'è un proxy che termina TLS;
- una scrittura che un browser invia per conto di un altro sito viene rifiutata con
403: il server accetta solo `Sec-Fetch-Site` uguale a `same-origin` o `none` e, se
quell'intestazione manca, un `Origin` uguale al server. È una difesa contro le pagine
web ostili visitate dall'utente, non un controllo degli accessi.
quell'intestazione manca, un `Origin` che sia uno degli host a cui il server
risponde, porta compresa (non più l'`Host` della richiesta stessa). È una difesa
contro le pagine web ostili visitate dall'utente, non un controllo degli accessi;
- ogni richiesta, letture e file statici compresi, il cui `Host` non è un nome a cui
il server risponde viene rifiutata con 421 (Misdirected Request), e con 400 se
`Host` manca o non è un host. Il server risponde a `localhost`, `127.0.0.1` e
`[::1]` sulla porta su cui ascolta, all'indirizzo su cui è arrivata la connessione e
ai nomi elencati nella variabile d'ambiente `PATCHRADAR_ALLOWED_HOSTS` (separati da
virgole: `nome` per qualunque porta, `nome:porta` solo per quella; nessun carattere
jolly). Difende dal DNS rebinding: una pagina ostile che fa risolvere il proprio nome
in 127.0.0.1 è "same-origin" per il browser, e fino al 2026-11-17 poteva così leggere
la watchlist e aggiungervi voci. Chi mette un proxy davanti al server e gli fa
passare il proprio `Host`, o rimappa la porta con Docker, aggiunge quel nome alla
variabile.

In pratica: esposta oltre la macchina locale, l'interfaccia mostra a chiunque la
raggiunga l'inventario del software e le sue vulnerabilità. Va lasciata sul loopback,
Expand Down
172 changes: 166 additions & 6 deletions src/patchradar/api/main.py
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
import asyncio
import hmac
import ipaddress
import logging
import math
import os
import re
from collections.abc import Awaitable, Callable, MutableMapping
from contextlib import asynccontextmanager
from importlib.metadata import version as pkg_version
from pathlib import Path as FilePath
from urllib.parse import urlsplit
from typing import Any

import aiosqlite
from fastapi import Depends, FastAPI, HTTPException, Path, Query, Request
Expand Down Expand Up @@ -103,6 +105,107 @@ async def require_api_key(provided: str | None = Depends(_api_key_header)) -> No
)


ALLOWED_HOSTS_ENV = "PATCHRADAR_ALLOWED_HOSTS"

# ASGI, spelt without importing Starlette, which is FastAPI's and not declared here.
Scope = MutableMapping[str, Any]
Receive = Callable[[], Awaitable[MutableMapping[str, Any]]]
Send = Callable[[MutableMapping[str, Any]], Awaitable[None]]
ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]

# The names a browser on this machine reaches the server by, whatever --host is.
_LOOPBACK_NAMES = frozenset({"localhost", "127.0.0.1", "::1"})

# A Host value, or the authority of an Origin: a name or an IPv4 address, or an
# IPv6 address in brackets, and an optional port. Nothing else — no userinfo,
# path or spaces — so what is matched is what a browser would have sent.
# Matched here rather than with urlsplit, which raises ValueError on brackets
# around something that is not an IPv6 address: a 500 for `Origin: http://[1.2]`.
_AUTHORITY_RE = re.compile(r"(?:(?P<name>[A-Za-z0-9._-]+)|\[(?P<ipv6>[0-9A-Fa-f:.]+)\])(?::(?P<port>[0-9]{1,5}))?")

# An Origin header as browsers serialise one (RFC 6454, 6.1).
_ORIGIN_RE = re.compile(r"(?P<scheme>https?)://(?P<authority>.+)")

_DEFAULT_PORTS = {"http": 80, "https": 443}


def _parse_authority(value: str) -> tuple[str, int | None] | None:
"""(host, port) of `name[:port]`, the host lower-cased and an address in its
canonical form; None when the value is not one."""
match = _AUTHORITY_RE.fullmatch(value)
if match is None:
return None
port = int(match["port"]) if match["port"] else None
if port is not None and port > 65535:
return None
if match["ipv6"] is not None:
try:
return ipaddress.IPv6Address(match["ipv6"]).compressed, port
except ValueError:
return None
name = match["name"].lower()
return _as_address(name) or name, port


def _as_address(value: str) -> str | None:
"""An IP address in its canonical form, or None when `value` is not one."""
try:
return ipaddress.ip_address(value).compressed
except ValueError:
return None


def configured_hosts() -> list[tuple[str, int | None]]:
"""The extra names in PATCHRADAR_ALLOWED_HOSTS, comma-separated.

`name` is answered on any port, `name:port` on that port only. An entry that
is not a name — `*`, a URL — is ignored (the startup log says so), never
read as "any host". Read per request, like the API key.
"""
raw = os.environ.get(ALLOWED_HOSTS_ENV, "")
entries = (_parse_authority(item.strip()) for item in raw.split(",") if item.strip())
return [entry for entry in entries if entry is not None]


def _answers_to(host: str, port: int | None, scope: Scope) -> bool:
"""Whether this server, as reached by this connection, is `host:port`.

The loopback names and the address the connection arrived on (uvicorn puts
the socket's own address in the scope's `server`), on the port it arrived
on or with no port; then the configured names. An address is taken from
`server` only when it is one: DNS rebinding works through a name, and no
answer of the attacker's makes a browser send an address it did not
connect to.
"""
for name, wanted in configured_hosts():
if host == name and (wanted is None or port == wanted):
return True
own_address, own_port = scope.get("server") or (None, None)
names = set(_LOOPBACK_NAMES)
if isinstance(own_address, str) and (address := _as_address(own_address)):
names.add(address)
if host not in names:
return False
return port is None or own_port is None or port == own_port


def _origin_is_this_server(origin: str, request: Request) -> bool:
"""Whether an Origin header names this server, port included.

Compared with the hosts the server answers to, not with the request's own
Host: under DNS rebinding the browser makes the two equal, and behind a
proxy that rewrites Host they differ for a legitimate page. The port is the
origin's, or the scheme's default when it has none, so a page from
http://localhost (port 80) is not this server on port 8000.
"""
match = _ORIGIN_RE.fullmatch(origin) # not "null", nor anything with a path
authority = _parse_authority(match["authority"]) if match else None
if match is None or authority is None:
return False
host, port = authority
return _answers_to(host, port if port is not None else _DEFAULT_PORTS[match["scheme"]], request.scope)


# What a browser's Sec-Fetch-Site may say about a write it is allowed to send:
# the page came from this server, or the user started the request directly.
_OWN_FETCH_SITES = {"same-origin", "none"}
Expand All @@ -118,18 +221,22 @@ async def require_same_origin(request: Request) -> None:

Browsers say where a request comes from, in Sec-Fetch-Site and, on every
cross-origin POST or DELETE, in Origin. Sec-Fetch-Site is preferred because
it survives a reverse proxy that rewrites Host; Origin against Host covers
the browsers that predate it. A client that sends neither header is not a
browser — curl, a script — and cannot be used for CSRF, so it is let through
to the key check like before.
it survives a reverse proxy that rewrites Host; Origin against the hosts the
server answers to covers the browsers that predate it. A client that sends
neither header is not a browser — curl, a script — and cannot be used for
CSRF, so it is let through to the key check like before.

"same-origin" is only as good as the origin: under DNS rebinding the
attacker's page is same-origin with the name it rebinds, and so is its
Origin. `require_known_host` refuses that name before any route runs.
"""
site = request.headers.get("sec-fetch-site")
if site is not None:
if site in _OWN_FETCH_SITES:
return
else:
origin = request.headers.get("origin")
if origin is None or urlsplit(origin).netloc == request.headers.get("host"):
if origin is None or _origin_is_this_server(origin, request):
return
raise HTTPException(status_code=403, detail="Cross-site request refused")

Expand All @@ -144,11 +251,64 @@ async def lifespan(app: FastAPI):
"unauthenticated. Set it before exposing PatchRadar beyond localhost.",
API_KEY_ENV,
)
ignored = [item.strip() for item in os.environ.get(ALLOWED_HOSTS_ENV, "").split(",")
if item.strip() and _parse_authority(item.strip()) is None]
if ignored:
logger.warning("%s: ignoring %r, which are not host or host:port", ALLOWED_HOSTS_ENV, ignored)
yield

app = FastAPI(title="PatchRadar", version=pkg_version("patchradar"), lifespan=lifespan)
app.mount("/static", StaticFiles(directory=FilePath(__file__).parent / "static"), name="static")


class RequireKnownHost:
"""Answer only to a Host this server is: every route, reads and /static too.

DNS rebinding: a page on rebind.evil.example is served by the attacker,
then the name is made to resolve to 127.0.0.1. The browser still counts the
page and http://rebind.evil.example:8000 as one origin — Sec-Fetch-Site
says same-origin, Origin equals Host — and lets the page read the answers.
Only Host gives it away, and it was never looked at: the page could add to
the watchlist and read it, the software installed and its versions.

421 Misdirected Request (RFC 9110, 15.5.20) for a well-formed Host that is
not this server: the request reached a server that will not answer for that
target. 400 for a Host that is missing or not a host[:port] at all, as
RFC 9112, 3.2 asks.

Plain ASGI rather than `@app.middleware("http")`: a second one of those
made the API benchmarks 14-18% slower (CodSpeed on this change).
"""

def __init__(self, app: ASGIApp) -> None:
self.app = app

async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
if scope["type"] != "http":
await self.app(scope, receive, send)
return
raw = Request(scope).headers.get("host", "")
authority = _parse_authority(raw)
if authority is None:
refusal = JSONResponse({"detail": "Missing or malformed Host header"}, status_code=400)
elif not _answers_to(*authority, scope):
logger.warning("refused a request for host %r: not one this server answers to (%s)",
raw[:100], ALLOWED_HOSTS_ENV)
refusal = JSONResponse(
{"detail": f"This server does not answer to that host; name it in {ALLOWED_HOSTS_ENV} if it should"},
status_code=421,
)
else:
await self.app(scope, receive, send)
return
await refusal(scope, receive, send)


# Added before `security_headers`, which therefore wraps it: the refusals carry
# the same headers as every other answer.
app.add_middleware(RequireKnownHost)


@app.middleware("http")
async def security_headers(request: Request, call_next) -> Response:
"""Add security headers to all responses — defense in depth against XSS and clickjacking."""
Expand Down
2 changes: 1 addition & 1 deletion tests/test_affected_conditions.py
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ def test_the_cli_scan_reads_the_edition_of_the_watched_cpe(upstream_9680):


async def test_the_api_scan_reads_the_edition_of_the_watched_cpe(upstream_9680):
async with AsyncClient(transport=ASGITransport(app=api.app), base_url="http://test") as client:
async with AsyncClient(transport=ASGITransport(app=api.app), base_url="http://localhost") as client:
added = await client.post("/api/watchlist/firefox", params={"version": "115.17.0", "cpe": FIREFOX_ESR})
assert added.status_code == 200, added.text
body = (await client.post("/api/scan", params={"days": 7})).json()
Expand Down
2 changes: 1 addition & 1 deletion tests/test_api_versioned.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@

@pytest.fixture
async def client():
async with AsyncClient(transport=ASGITransport(app=api.app), base_url="http://test") as ac:
async with AsyncClient(transport=ASGITransport(app=api.app), base_url="http://localhost") as ac:
yield ac


Expand Down
2 changes: 1 addition & 1 deletion tests/test_collector_failures.py
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,7 @@ def test_collector_error_is_readable():
@pytest.fixture
async def client():
await add_to_watchlist("nginx")
async with AsyncClient(transport=ASGITransport(app=api.app), base_url="http://t") as ac:
async with AsyncClient(transport=ASGITransport(app=api.app), base_url="http://localhost") as ac:
yield ac


Expand Down
2 changes: 1 addition & 1 deletion tests/test_csp.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@

@pytest.fixture
async def client():
async with AsyncClient(transport=ASGITransport(app=api.app), base_url="http://test") as ac:
async with AsyncClient(transport=ASGITransport(app=api.app), base_url="http://localhost") as ac:
yield ac


Expand Down
Loading