GHSA-2HJX-23VW-WVW4
Authentication bypass: LIGHTRAG_API_PREFIX starting with /api collapses the default WHITELIST_PATHS into a blanket exemption for the entire API
CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H
Fuente: GitHub
Ciclo de vida de la vulnerabilidad
| Fecha | Fase | Evento | Detalle |
|---|---|---|---|
| Divulgación | Publicada | GHSA-2HJX-23VW-WVW4 divulgada · CVSS 9.8 (GitHub) | |
| Remediación | Parche 1.5.5 | lightrag-hku · 0 d desde divulgación | |
| Divulgación | Modificada | Última actualización del registro | |
| Monitoreo | Detectada | Ingresó al índice | |
| Monitoreo | Verificada | Última verificación contra las fuentes |
Summary
The authentication whitelist is matched against the full request path, which includes the mount prefix, while `WHITELIST_PATHS` entries are written as natural route paths. The shipped default is `WHITELIST_PATHS=/health,/api/*`, exempted so that the Ollama-compatible routes (`/api/chat`, `/api/generate`) stay open. When `LIGHTRAG_API_PREFIX` is set to any value beginning with `/api`, every route path begins with `/api`, so the `/api` prefix pattern matches every request and the entire API becomes exempt from authentication.
The value in the project's own `--help` text, `/api/v1`, is such a value.
The result is that both configured authentication modes are bypassed at the same time. With `AUTH_ACCOUNTS` and `LIGHTRAG_API_KEY` both set, an unauthenticated network caller reads the document store through `GET /documents` and reaches the destructive `DELETE /documents` handler, along with the rest of the document, query and graph API.
Demonstrated impact: against the real server built by `create_app`, with both credentials configured and `LIGHTRAG_API_PREFIX=/api/v1`, an unauthenticated `DELETE /api/v1/documents` returns `200 {"status":"success","message":"All documents cleared successfully"}`. The same request with no prefix returns 401.
Severity / CVSS
`CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H`
Score: 9.8 (Critical), scored for the affected configuration. Unauthenticated, network reachable, no user interaction; confidentiality through document and knowledge-base reads, integrity and availability through the reachable delete handlers.
Stated plainly, because it bounds who is affected: this requires the operator to set `LIGHTRAG_API_PREFIX` to a value starting with `/api`. It does not affect a deployment that leaves the prefix unset. It is reported as a defect rather than a misconfiguration for three reasons. The triggering half of the condition, `WHITELIST_PATHS=/health,/api/*`, is the shipped default and needs no operator action. The other half is a documented, encouraged value: `/api/v1` is the example in `--help`. And the exemption's intended scope is stated in the codebase as the Ollama compatibility routes only, so extending it to `DELETE /documents` is outside the control's own documented contract.
Affected component
- `lightrag/api/utils_api.py:125-139` `path_is_whitelisted`, prefix matching by bare `str.startswith`
- `lightrag/api/utils_api.py:219-220` step 1 of `get_combined_auth_dependency.combined_dependency`: `path = request.url.path` then `path_is_whitelisted(path)`, before any credential is read
- `lightrag/api/utils_api.py:111-119` whitelist parsing, where a trailing `/*` becomes a prefix-match entry
- `lightrag/api/config.py:757` `WHITELIST_PATHS` default `"/health,/api/*"`
- `lightrag/api/config.py:456-461` `--api-prefix` / `LIGHTRAG_API_PREFIX`, whose `help` at `:460` documents the example value `/api/v1`
- `lightrag/api/lightrag_server.py:1417,1427` `api_prefix` becomes the FastAPI `root_path`
- `lightrag/api/lightrag_server.py:419-452` `_RootPathNormalizationMiddleware`, which restores `root_path` into `scope["path"]` when a proxy strips it
- `lightrag/api/admission_middleware.py:211-212` the pre-body admission gate calls `path_is_whitelisted` with the same unstripped path
- `lightrag/api/utils_api.py:418-424` `whitelist_exposes_api_routes`, the startup warning's matcher, which is also prefix-unaware
Version tested: commit `3fb91168`, which reports itself as 1.5.5 / api 0324 while 1.5.5 was still unreleased. Note that 1.5.5 shipped on 2026-07-31 and FIXES this defect; see the Fix section. Re-checked against `origin/main` at `1c1cf88b`: eight later commits, none of which touch `utils_api.py`, `config.py`, `admission_middleware.py` or `lightrag_server.py`, so all four files are byte-identical and every line reference below resolves at both commits.
Affected range: `>= 1.5.0, < 1.5.5`, fixed in 1.5.5. Lower bound established by walking the release tags: `--api-prefix` / `LIGHTRAG_API_PREFIX` is absent through `v1.4.16`, appears in `v1.5.0rc2`, and is present in every release from `v1.5.0` onward. The other two ingredients predate it and are present in every tag checked: the `/health,/api/*` whitelist default, and the `request.url.path` plus bare `startswith` matcher. Confirmed at tag `v1.5.0` directly, where the whitelist matcher already reads `path = request.url.path` and compares with `path.startswith(pattern)`, and `_normalize_api_prefix` already feeds `api_prefix` into FastAPI's `root_path`. Every other line number in this report refers to `3fb91168`, not to `v1.5.0`. Note that 1.5.5 is not on PyPI as a stable release yet, only `1.5.5rc1`; the latest stable there is 1.5.4, which is affected.
Root cause
Three facts combine.
- The matcher receives a prefixed path while the patterns are unprefixed. `WHITELIST_PATHS` entries are natural route paths such as `/health`. The enforcing dependency passes `request.url.path`, which in ASGI contains `root_path`. With `root_path=/api/v1`, a request routed to `/documents` has `request.url.path == "/api/v1/documents"`. Nothing strips the prefix before matching, so the comparison is made between two different kinds of path.
- The default whitelist entry is itself an `/api` prefix. `"/health,/api/*"` parses to `[('/health', False), ('/api', True)]`. Any request path starting with `/api` matches. Once the mount prefix starts with `/api`, that is every request path, so the check degenerates to always-true and returns before any credential is examined.
- Prefix matching has no segment boundary. `path.startswith('/api')` also matches unrelated sibling routes such as `/apikeys` or `/api_internal`. This widens any prefix entry beyond the path segment the operator wrote, independently of the mount-prefix issue. The correct idiom is already present in the same file: the token-renewal skip check at `utils_api.py:235` uses `path == skip_path or path.startswith(skip_path + "/")`, which cannot match mid-segment. The whitelist matcher 110 lines above it does not.
The codebase already holds the knowledge that the prefix must be removed before a path comparison, and applies it inconsistently. In `admission_middleware.py` the `api_prefix` constructor parameter is documented as "mount prefix to strip before matching paths" (`:145`), and `_is_admission_path` does strip it (`:166-168`) before comparing against `ADMISSION_PATHS`. Forty lines later the whitelist comparison in the same class passes the raw `scope["path"]` to `path_is_whitelisted` (`:211-212`). The same file strips the prefix for one path comparison and not for the other.
`path_is_whitelisted` documents itself as the one shared matcher "so every layer that has to answer 'may this request skip auth?' uses one matcher" (`:126-133`). Both of its callers hand it a prefixed path, so the shared matcher is consistently given input it does not normalize.
The defect places the exemption outside its own documented scope. `env.example:79-84` states the intent: the default "exempts /api/* so the Ollama-compatible endpoints (/api/chat, /api/generate, ...) stay open by default, matching Ollama's own unauthenticated behavior", and warns that those routes "invoke the LLM and read your knowledge base". `utils_api.py:626-641`, inside `display_splash_screen`, emits a startup warning in the same terms, that `WHITELIST_PATHS` "exempts the Ollama-compatible /api/* routes (/api/chat, /api/generate, ...) from authentication". Neither the documentation nor the warning contemplates the exemption covering `DELETE /documents`. In the prefix configuration the warning is still accurate about the Ollama routes while materially understating what is actually open, so an operator who reads it is told about two LLM routes when the whole API is exempt.
Impact
- Full unauthenticated read of the document store and knowledge base. `GET /documents` returns the document status listing and `GET /graph/label/list` returns graph labels, both without credentials. The query routes are exempt on the same basis, verified below.
- Unauthenticated destruction of the entire document store. `DELETE /documents` completes without credentials against the real server: `200 {"status":"success","message":"All documents cleared successfully"}`. This is not a reachability argument, it is the handler running to completion and clearing all documents and storage.
- Both configured authentication modes bypassed simultaneously. The whitelist check is step 1, before the token check (step 2) and the API-key check (step 4), so setting `AUTH_ACCOUNTS` and `LIGHTRAG_API_KEY` together does not help. The operator who has configured the most authentication available is equally exposed.
- The pre-body admission gate is bypassed as well. `admission_middleware.py:211-212` uses the same matcher on the same unstripped path, so the request-body-size and pending-document capacity limits that gate ingestion pre-authentication are also skipped, on the same condition.
- Silent onset. Nothing in the request or the logs distinguishes an exempted request from an authenticated one, and the startup warning's wording suggests a much narrower exposure, so the collapse is unlikely to be noticed.
Proof of Concept
Two probes, both unauthenticated throughout: no `Authorization` header, no `X-API-Key`. Both configure `AUTH_ACCOUNTS`, `TOKEN_SECRET` and `LIGHTRAG_API_KEY`, and both leave `WHITELIST_PATHS` unset so the shipped default applies.
Through the real entrypoint
`poc/probe_whitelist_realapp.py` builds the application exactly as the `lightrag-server` command does, `create_app(global_args)` over the real parsed config, and serves it on a real uvicorn socket. `LIGHTRAG_API_PREFIX` is the only variable.
prefix='' whitelist='/health,/api/*'
GET /documents -> 401 AUTH ENFORCED
POST /query -> 401 AUTH ENFORCED
GET /graph/label/list -> 401 AUTH ENFORCED
DELETE /documents -> 401 AUTH ENFORCED
prefix='/api/v1' whitelist='/health,/api/*'
GET /api/v1/documents -> 200 {"statuses":{}}
POST /api/v1/query -> 422 body validation, past auth
GET /api/v1/graph/label/list -> 200 []
DELETE /api/v1/documents -> 200 {"status":"success","message":"All documents cleared successfully"}The last line is the finding: the destructive route ran to completion, unauthenticated, on the server as shipped, using the prefix value from `--help`.
Isolating the cause
`poc/probe_whitelist_live.py` mounts the document, query and graph routers directly, which makes it cheap to sweep prefix values and confirm what the trigger actually is.
Control, no prefix, and the `/site01` control that isolates the cause:
prefix='' GET /documents 401 | POST /documents/paginated 401 | DELETE /documents 401 | POST /query 401 | GET /graph/label/list 401
prefix='/site01' GET /documents 401 | POST /documents/paginated 401 | DELETE /documents 401 | POST /query 401 | GET /graph/label/list 401`LIGHTRAG_API_PREFIX=/api`:
prefix='/api' whitelist_patterns=[('/health', False), ('/api', True)] auth_configured=True
GET /api/documents -> 200 {"statuses":{}}
POST /api/documents/paginated -> 422 body validation, past auth
DELETE /api/documents -> 500 reached handler internals
POST /api/query -> 422 body validation, past auth
GET /api/graph/label/list -> 200 []`LIGHTRAG_API_PREFIX=/api/v1`, the value from `--help`:
prefix='/api/v1' whitelist_patterns=[('/health', False), ('/api', True)] auth_configured=True
GET /api/v1/documents -> 200 {"statuses":{}}
POST /api/v1/documents/paginated -> 422 body validation, past auth
DELETE /api/v1/documents -> 500 reached handler internals
POST /api/v1/query -> 422 body validation, past auth
GET /api/v1/graph/label/list -> 200 []Reading the response codes in this second probe:
- 200 on `GET /documents` and `GET /graph/label/list` is a completed unauthenticated read across two routers.
- 422 on the `POST` routes is FastAPI body validation rejecting an empty body. It runs only after the dependency has allowed the request, so it is evidence of the bypass, not a failure.
- 500 on `DELETE /documents` here is only this probe passing `doc_manager=None`; it shows the request entered the handler. The real-entrypoint probe above is the one that matters for impact, and there the same request returns 200 and clears the store.
The `/site01` row is the control that matters: a mount prefix by itself changes nothing. The trigger is specifically a prefix that collides with the default whitelist entry.
Reproduce:
python3 poc/probe_whitelist_realapp.py "" # real entrypoint, control
python3 poc/probe_whitelist_realapp.py /api/v1 # real entrypoint, unauthenticated delete
python3 poc/probe_whitelist_live.py "" # control
python3 poc/probe_whitelist_live.py /site01 # control, non-colliding prefix
python3 poc/probe_whitelist_live.py /api
python3 poc/probe_whitelist_live.py /api/v1Verified at commit `3fb91168`, which is 1.5.5 / api 0324.
Recommended fix
- Match on the route path, not the mounted path. Strip the mount prefix before calling `path_is_whitelisted`, in both callers. The simplest correct form needs no new helper: subtract the known `api_prefix`, which `admission_middleware._is_admission_path` already does at `:166-168`. If you prefer to derive it from the scope, mirror what Starlette's own router uses to resolve a route, `starlette._utils.get_route_path`, which subtracts `root_path` only when the next character is `/` so the subtraction cannot cut mid-segment. That module is private, so copying its five-line logic is safer than importing it. Doing the normalization inside `path_is_whitelisted`, and passing it the request scope rather than a bare string, would make it impossible to forget at a call site, which matches the function's stated role as the single shared matcher.
- Make prefix matching segment-aware. Treat a `/*` entry as matching only the prefix itself or the prefix followed by `/`, so `/api/*` cannot match `/apikeys`.
- Refuse the collapsing combination at startup. When `api_prefix` is non-empty and any prefix entry in `WHITELIST_PATHS` matches it, the whitelist exempts the whole API. That is almost never intended and is cheap to detect where `whitelist_exposes_api_routes` is already called, in `display_splash_screen` (`utils_api.py:631-634`). Failing closed is defensible here; at minimum the existing warning should state that every route is exempt rather than naming only the Ollama routes. Note that the current warning is additionally gated on a non-loopback bind (`utils_api.py:634`), so a prefixed deployment behind a reverse proxy on loopback prints nothing at all.
- Consider scoping the default to the routes it is for. The documented intent is Ollama compatibility. `WHITELIST_PATHS=/health,/api/chat,/api/generate` expresses that intent exactly and is immune to prefix collision, unlike a blanket `/api/*`.
Fixes 1 and 2 are the defect. Fixes 3 and 4 remove the standing footgun.
References
- `GHSA-mmg5-8x8q-v934` publishes the `/api/*` exemption, scoped explicitly to `/api/chat` and `/api/generate` and framed as read-only LLM and knowledge-base exposure. This report is the prefix-matching defect that extends the same exemption to the entire API including destructive routes, which is outside that advisory's stated scope.
- `GHSA-597m-w632-p8qv` (this reporter, published 2026-07-29) is precedent in this repository that reaching outside an exemption's documented scope is treated as a vulnerability rather than as hardening.
- `env.example:79-84` and `lightrag/api/utils_api.py:626-641` state the intended scope of the default whitelist.
- Starlette path resolution: `get_route_path` subtracts `root_path` from `scope["path"]` for routing, which is why routes resolve normally while `request.url.path` still carries the prefix.
Fix
Fixed in 1.5.5, released 2026-07-31. Verified at tag `v1.5.5`, and the fix implements recommended
changes 1, 2 and 3 rather than only the immediate collapse.
- Matches the route path, not the mounted path. `path_is_whitelisted` now takes the ASGI scope
- Prefix matching is segment-aware. `:329` is now `route == pattern or route.startswith(pattern + "/")`,
- The admission gate is fixed at the same time. `lightrag/api/admission_middleware.py:208-209`
- The startup warning is prefix-aware. `whitelist_exposes_api_routes` (`utils_api.py:566` at
Recommendation 4, narrowing the shipped default from `/api/*` to the two Ollama routes it exists
for, is a standing footgun rather than part of the defect and remains open.
Incluye detalles técnicos publicados por el investigador. Úselos solo para validar y corregir sus propios sistemas.
Desglose de métricas
Rangos afectados
Estado del parche por paquete
| Paquete / producto | Estado | Corregida en | Desde divulgación | Última versión |
|---|---|---|---|---|
pypilightrag-hku |
Corregida | 1.5.5 | 0 d | 1.5.7 no afectada |
1.5.5Arsenal público
Sin exploits, módulos ni PoC públicos conocidos a la fecha de verificación.
https://github.com/HKUDS/LightRAG/security/advisories/GHSA-2hjx-23vw-wvw4Las referencias externas se muestran para copiar: cve.llama.ec no lo redirige a otros sitios.
