~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
# allow: no-sut-import — security tests for the delete/clear_history
# endpoints; drives the real FastAPI routes through an authenticated
# TestClient while stubbing the DB session so we can plant a ResearchHistory
# row whose ``report_path`` points at a canary file under tmp_path.
"""Regression tests for database-stored report paths used during deletion.
Both single-research deletion and clear-history apply the shared report-path
containment checks. These tests plant absolute, traversing and symlink paths
in isolated database rows and require outside canaries to survive. Positive
controls require legitimate in-root reports to be deleted.
The write-surface checks also record whether production creates report_path
values, independently of the delete-side containment contract."""
import itertools
import uuid
from contextlib import contextmanager
from datetime import datetime, timezone
from unittest.mock import MagicMock, patch
import pytest
from fastapi.testclient import TestClient
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from sqlalchemy.pool import StaticPool
from tests.test_utils import add_src_to_path
add_src_to_path()
from local_deep_research.database.models import Base, ResearchHistory # noqa: E402
# Patching targets — ``web.routers.research`` imports ``get_user_db_session``
# and ``get_active_research_ids`` at module load, but does a local
# ``from ..queue.lifecycle_cleanup import cleanup_queued_research_state``
# inside the route bodies (unchanged by the FastAPI migration). The
# lifecycle symbol has to be patched at its SOURCE so the local re-import
# resolves to the mock.
_RR = "local_deep_research.web.routers.research"
_LIFECYCLE = "local_deep_research.web.queue.lifecycle_cleanup"
TEST_PASSWORD = "ReportPathCanaryPass123" # noqa: S105
# Monotonic, never random — see test_save_raw_config_blocked_keys_fastapi.py
# for why: random /8 addresses collide across a session with many clients.
_FORWARDED_IP_SEQ = itertools.count(1)
@pytest.fixture(autouse=True)
def _slowapi_off():
"""Take the per-IP HTTP rate limiter out of the picture.
Every test below registers a fresh user to get an authenticated,
CSRF-carrying client; nothing here is about rate limiting.
"""
from local_deep_research.web.dependencies.rate_limit import limiter
original = limiter.enabled
limiter.enabled = False
try:
yield
finally:
limiter.enabled = original
def _csrf(client: TestClient) -> str:
client.get("/auth/login")
resp = client.get("/auth/csrf-token")
return resp.json().get("csrf_token", "") if resp.status_code == 200 else ""
@pytest.fixture
def route_client(app):
"""Authenticated TestClient over the REAL FastAPI research router.
A real registered/logged-in user (not a faked session) is what gets
past ``require_auth``; the DB session itself is separately patched per
test (``_route_db_patches``) so the real per-user database is never
touched.
"""
n = next(_FORWARDED_IP_SEQ)
client = TestClient(app, raise_server_exceptions=False)
client.headers.update(
{"X-Forwarded-For": f"10.{(n // 250) % 250 + 1}.{n % 250 + 1}.23"}
)
username = f"report_path_canary_{uuid.uuid4().hex[:8]}"
resp = client.post(
"/auth/register",
data={
"username": username,
"password": TEST_PASSWORD,
"confirm_password": TEST_PASSWORD,
"acknowledge": "true",
"csrf_token": _csrf(client),
},
follow_redirects=False,
)
assert resp.status_code == 302, (
"harness broken — could not register a user to drive the endpoint "
f"with: {resp.status_code} {resp.text[:300]}"
)
# DELETE and POST both need a live CSRF header (ASGI middleware, no
# off switch).
token = _csrf(client)
if token:
client.headers.update({"X-CSRFToken": token})
return client
def _seed_db(rid, report_path_value, status="completed"):
"""Build an in-memory SQLite session with one ResearchHistory row.
Returns ``(session, engine)``. Caller is responsible for closing /
disposing.
``StaticPool`` + ``check_same_thread=False``: this session is patched
into a real ``TestClient`` request for a sync route, dispatched
through ``run_in_threadpool`` on a different thread than the one that
seeded it here — without a shared, thread-agnostic connection,
closing/rolling back this session later trips ``sqlite3.
ProgrammingError: SQLite objects created in a thread can only be used
in that same thread``. Same fix as
``test_socket_ownership_edges_fastapi.py``.
"""
engine = create_engine(
"sqlite:///:memory:",
poolclass=StaticPool,
connect_args={"check_same_thread": False},
)
Base.metadata.create_all(engine)
session = sessionmaker(bind=engine)()
session.add(
ResearchHistory(
id=rid,
query="q",
mode="quick",
status=status,
created_at=datetime.now(timezone.utc).isoformat(),
report_path=report_path_value,
)
)
session.commit()
return session, engine
def _close(session, engine):
session.close()
engine.dispose()
@contextmanager
def _route_db_patches(session):
"""Patch the symbols ``research_routes`` looks up at request time.
Yields nothing — the patchers remain active inside the ``with`` block.
Use as::
with _route_db_patches(session):
resp = route_client.delete(...)
"""
patchers = [
patch(f"{_RR}.get_user_db_session"),
patch(f"{_RR}.get_active_research_ids", return_value=[]),
patch(f"{_LIFECYCLE}.cleanup_queued_research_state"),
]
mocks = [p.start() for p in patchers]
try:
# get_user_db_session is used as a context manager by the routes:
# ``with get_user_db_session(username) as db_session``.
mocks[0].return_value.__enter__ = lambda _s: session
mocks[0].return_value.__exit__ = MagicMock(return_value=False)
mocks[2].return_value = MagicMock()
yield
finally:
for p in reversed(patchers):
p.stop()
# ---------------------------------------------------------------------------
# DELETE /api/delete/<research_id>
# ---------------------------------------------------------------------------
class TestDeleteEndpointCanaryProtection:
"""``DELETE /api/delete/<research_id>`` must not unlink paths outside
the configured research outputs directory.
FIXED during the FastAPI port (see module docstring): the handler now
resolves ``report_path`` and requires
``is_relative_to(research_outputs_root)`` before unlinking. These three
tests used to be ``xfail(strict=True)`` documenting the missing check;
they are now plain regression pins on the containment behaviour.
"""
def test_absolute_path_outside_root_is_preserved(
self, route_client, tmp_path
):
"""An absolute path stored in ``report_path`` that lives outside
any plausible research-outputs root must not be unlinked."""
outside_dir = tmp_path / "outside_storage"
outside_dir.mkdir()
canary = outside_dir / "canary.txt"
canary.write_text("DO NOT DELETE")
assert canary.exists()
rid = "rid-delete-abs"
session, engine = _seed_db(rid, str(canary))
try:
with _route_db_patches(session):
resp = route_client.delete(f"/api/delete/{rid}")
# The endpoint may succeed (200) or fail for unrelated reasons
# (400 if it bails out before the unlink); the security
# assertion is that the canary file is never touched either way.
assert resp.status_code == 200, resp.text
assert session.query(ResearchHistory).count() == 0
finally:
_close(session, engine)
assert canary.exists(), (
"DELETE /api/delete/<id> unlinked an absolute report_path "
"outside the storage root — no path validation present"
)
assert canary.read_text() == "DO NOT DELETE"
def test_parent_traversal_path_is_preserved(self, route_client, tmp_path):
"""A ``report_path`` containing ``..`` segments that resolves
outside the storage root must not be unlinked."""
outside_dir = tmp_path / "outside_sibling"
outside_dir.mkdir()
canary = outside_dir / "victim.txt"
canary.write_text("DO NOT DELETE")
# Pretend the "storage root" is tmp_path / "research_outputs".
# Construct a path that uses ``..`` to escape it and reach the canary.
fake_storage_root = tmp_path / "research_outputs"
traversal_path = (
fake_storage_root
/ "sub"
/ ".."
/ ".."
/ "outside_sibling"
/ "victim.txt"
)
# NOTE: the intermediate "sub" dir must exist or the OS cannot
# stat the ``..``-laden path at all (ENOENT on the first hop) and
# the route's ``.exists()`` guard would skip the unlink — a false
# green rather than a security pass.
(fake_storage_root / "sub").mkdir(parents=True)
# Sanity-check the traversal is live: stat-able AND pointing at
# the canary.
assert traversal_path.exists(), "traversal payload must be stat-able"
assert traversal_path.resolve() == canary.resolve()
rid = "rid-delete-traversal"
session, engine = _seed_db(rid, str(traversal_path))
try:
with _route_db_patches(session):
resp = route_client.delete(f"/api/delete/{rid}")
assert resp.status_code == 200, resp.text
assert session.query(ResearchHistory).count() == 0
finally:
_close(session, engine)
assert canary.exists(), (
"DELETE /api/delete/<id> followed a ``..``-laden report_path "
"outside the storage root — no containment check present"
)
assert canary.read_text() == "DO NOT DELETE"
def test_symlink_pointing_outside_root_is_preserved(
self, route_client, tmp_path
):
"""A ``report_path`` that is a symlink whose target lives outside
the storage root must not be unlinked (whether the unlink follows
the link or not — either is unsafe)."""
outside_dir = tmp_path / "outside_target"
outside_dir.mkdir()
canary = outside_dir / "symlink_target.txt"
canary.write_text("DO NOT DELETE")
# Place the symlink inside the (hypothetical) storage root.
fake_storage_root = tmp_path / "research_outputs"
fake_storage_root.mkdir()
link = fake_storage_root / "evil_link"
try:
link.symlink_to(canary)
except OSError:
pytest.skip("Cannot create symlinks in this environment")
assert link.is_symlink()
rid = "rid-delete-symlink"
# Use the symlink path (not the target). The route does
# ``Path(report_path).unlink()`` which deletes the symlink itself —
# also outside the storage semantics, so it must be blocked.
session, engine = _seed_db(rid, str(link))
try:
with _route_db_patches(session):
resp = route_client.delete(f"/api/delete/{rid}")
assert resp.status_code == 200, resp.text
assert session.query(ResearchHistory).count() == 0
finally:
_close(session, engine)
# Canary target must STILL exist (tripwire against dereferencing).
assert canary.exists(), (
"DELETE /api/delete/<id> followed a symlink target outside the "
"storage root — no link-target containment check present"
)
assert canary.read_text() == "DO NOT DELETE"
# The symlink in the storage area must also still exist.
assert link.is_symlink() or link.exists(), (
"DELETE /api/delete/<id> removed a symlink whose report_path "
"was trusted verbatim — no path validation present"
)
def test_legitimate_path_inside_storage_root_can_be_deleted(
self, route_client, tmp_path, monkeypatch
):
"""POSITIVE CONTROL: a ``report_path`` that lives inside the
configured research outputs directory must still be unlinked so
that the documented delete behaviour is preserved.
This test should stay GREEN. If a future fix accidentally blocks
legitimate deletes, this test breaks and flags the regression.
"""
# Point LDR_DATA_DIR at a tmp_path subdir so
# ``get_research_outputs_directory()`` returns
# tmp_path/app_data/research_outputs.
ldr_data = tmp_path / "app_data"
monkeypatch.setenv("LDR_DATA_DIR", str(ldr_data))
outputs_root = ldr_data / "research_outputs"
outputs_root.mkdir(parents=True)
legit_report = outputs_root / "legit_report.md"
legit_report.write_text("# legit report")
assert legit_report.exists()
rid = "rid-delete-legit"
session, engine = _seed_db(rid, str(legit_report))
try:
with _route_db_patches(session):
resp = route_client.delete(f"/api/delete/{rid}")
assert resp.status_code == 200, resp.status_code
finally:
_close(session, engine)
assert not legit_report.exists(), (
"POSITIVE CONTROL FAILED: a legitimate report inside the "
"research outputs root was not deleted. If a containment fix "
"was just added, it is overly restrictive."
)
# ---------------------------------------------------------------------------
# POST /api/clear_history
# ---------------------------------------------------------------------------
class TestClearHistoryEndpointCanaryProtection:
"""``POST /api/clear_history`` must not unlink paths outside the
configured research outputs directory — for ANY row in the user's
history."""
def test_absolute_path_outside_root_is_preserved(
self, route_client, tmp_path
):
"""An absolute canary path outside the storage root survives a
bulk clear_history."""
outside_dir = tmp_path / "clear_outside"
outside_dir.mkdir()
canary = outside_dir / "canary.txt"
canary.write_text("DO NOT DELETE")
rid = "rid-clear-abs"
session, engine = _seed_db(rid, str(canary))
try:
with _route_db_patches(session):
resp = route_client.post("/api/clear_history")
assert resp.status_code == 200, resp.text
assert session.query(ResearchHistory).count() == 0
finally:
_close(session, engine)
assert canary.exists(), (
"POST /api/clear_history unlinked an absolute report_path "
"outside the storage root — no path validation present"
)
assert canary.read_text() == "DO NOT DELETE"
def test_parent_traversal_path_is_preserved(self, route_client, tmp_path):
"""A ``..``-laden ``report_path`` that resolves outside the
storage root survives clear_history."""
outside_dir = tmp_path / "clear_outside_sibling"
outside_dir.mkdir()
canary = outside_dir / "victim.txt"
canary.write_text("DO NOT DELETE")
fake_storage_root = tmp_path / "research_outputs"
traversal_path = (
fake_storage_root
/ "sub"
/ ".."
/ ".."
/ "clear_outside_sibling"
/ "victim.txt"
)
# Intermediate dir must exist for the OS to resolve the ``..`` hops
# (see the delete-endpoint twin for the false-green explanation).
(fake_storage_root / "sub").mkdir(parents=True)
assert traversal_path.exists(), "traversal payload must be stat-able"
assert traversal_path.resolve() == canary.resolve()
rid = "rid-clear-traversal"
session, engine = _seed_db(rid, str(traversal_path))
try:
with _route_db_patches(session):
resp = route_client.post("/api/clear_history")
assert resp.status_code == 200, resp.text
assert session.query(ResearchHistory).count() == 0
finally:
_close(session, engine)
assert canary.exists(), (
"POST /api/clear_history followed a ``..``-laden report_path "
"outside the storage root — no containment check present"
)
assert canary.read_text() == "DO NOT DELETE"
def test_symlink_pointing_outside_root_is_preserved(
self, route_client, tmp_path
):
"""A ``report_path`` that is a symlink to a file outside the
storage root survives clear_history."""
outside_dir = tmp_path / "clear_symlink_target"
outside_dir.mkdir()
canary = outside_dir / "symlink_target.txt"
canary.write_text("DO NOT DELETE")
fake_storage_root = tmp_path / "research_outputs"
fake_storage_root.mkdir()
link = fake_storage_root / "evil_link"
try:
link.symlink_to(canary)
except OSError:
pytest.skip("Cannot create symlinks in this environment")
assert link.is_symlink()
rid = "rid-clear-symlink"
session, engine = _seed_db(rid, str(link))
try:
with _route_db_patches(session):
resp = route_client.post("/api/clear_history")
assert resp.status_code == 200, resp.text
assert session.query(ResearchHistory).count() == 0
finally:
_close(session, engine)
assert canary.exists(), (
"POST /api/clear_history followed a symlink target outside the "
"storage root — no link-target containment check present"
)
assert canary.read_text() == "DO NOT DELETE"
assert link.is_symlink() or link.exists(), (
"POST /api/clear_history removed a symlink whose report_path "
"was trusted verbatim — no path validation present"
)
def test_multiple_malicious_paths_all_preserved(
self, route_client, tmp_path
):
"""When several rows hold canary paths, clear_history must not
touch ANY of them."""
outside_dir = tmp_path / "bulk_outside"
outside_dir.mkdir()
canaries = []
for i in range(3):
c = outside_dir / f"canary_{i}.txt"
c.write_text(f"DO NOT DELETE {i}")
canaries.append(c)
session, engine = _seed_db("rid-clear-bulk-0", str(canaries[0]))
for i in range(1, len(canaries)):
session.add(
ResearchHistory(
id=f"rid-clear-bulk-{i}",
query="q",
mode="quick",
status="completed",
created_at=datetime.now(timezone.utc).isoformat(),
report_path=str(canaries[i]),
)
)
session.commit()
try:
with _route_db_patches(session):
resp = route_client.post("/api/clear_history")
assert resp.status_code == 200, resp.text
assert session.query(ResearchHistory).count() == 0
finally:
_close(session, engine)
for i, c in enumerate(canaries):
assert c.exists(), (
f"POST /api/clear_history unlinked bulk canary #{i} "
f"({c}) — no path validation present"
)
assert c.read_text() == f"DO NOT DELETE {i}"
def test_legitimate_path_inside_storage_root_can_be_deleted(
self, route_client, tmp_path, monkeypatch
):
"""POSITIVE CONTROL: legitimate reports inside the storage root
still get cleaned up by clear_history."""
ldr_data = tmp_path / "app_data"
monkeypatch.setenv("LDR_DATA_DIR", str(ldr_data))
outputs_root = ldr_data / "research_outputs"
outputs_root.mkdir(parents=True)
legit = outputs_root / "clear_legit.md"
legit.write_text("# legit")
rid = "rid-clear-legit"
session, engine = _seed_db(rid, str(legit))
try:
with _route_db_patches(session):
resp = route_client.post("/api/clear_history")
assert resp.status_code == 200, resp.status_code
finally:
_close(session, engine)
assert not legit.exists(), (
"POSITIVE CONTROL FAILED: a legitimate report inside the "
"research outputs root was not cleared. If a containment fix "
"was just added, it is overly restrictive."
)
# ---------------------------------------------------------------------------
# Write-side tripwires: the column itself has no validator, and processor_v2
# faithfully copies op_data["report_path"] into the column. Together these
# close the loop on the vulnerability even though we don't exercise the
# HTTP write path here.
# ---------------------------------------------------------------------------
class TestReportPathWriteSurface:
"""Document the write-side surface that makes the unlink-trust bug
reachable in practice."""
def test_research_history_report_path_is_unvalidated_text(self):
"""``ResearchHistory.report_path`` is a plain ``Column(Text)`` —
no SQLAlchemy ``CheckConstraint``, no custom ``TypeDecorator``,
no validator. Tripwire against future hardening regressions: a
later change that adds a validator here is what would make the
delete-time trust assumption safe."""
col = ResearchHistory.__table__.columns["report_path"]
assert col.type.__class__.__name__ == "Text", (
f"Expected Text column type, got {col.type.__class__.__name__} "
f"— write-side validator added? Audit delete-side unlinks."
)
check_constraints = [
c
for c in ResearchHistory.__table__.constraints
if c.__class__.__name__ == "CheckConstraint"
]
offending = [
c
for c in check_constraints
if "report_path"
in (c.sqltext.text if hasattr(c, "sqltext") else str(c))
]
assert not offending, (
"ResearchHistory has a CHECK constraint on report_path; "
"review whether it actually constrains the value space."
)
def test_processor_v2_copies_arbitrary_op_data_report_path(self):
"""``QueueProcessorV2.process_pending_operations_for_user`` assigns
``op_data["report_path"]`` directly to ``ResearchHistory.report_path``
without normalisation. Tripwire: if a future revision adds
sanitisation here, the delete-time trust assumption is partly
defused and this assertion flags it for re-review."""
import inspect as _inspect
from local_deep_research.web.queue import processor_v2
source = _inspect.getsource(
processor_v2.QueueProcessorV2.process_pending_operations_for_user
)
assert 'report_path = op_data.get("report_path")' in source
# No Path.resolve, no is_relative_to, no PathValidator on the same
# source fragment. If a future fix adds one, this assertion flags
# it for re-evaluation of the delete-time unlink trust.
forbidden_helpers = (
"Path(report_path).resolve()",
'op_data["report_path"]).resolve()',
"is_relative_to",
"PathValidator",
)
for fragment in forbidden_helpers:
assert fragment not in source, (
f"processor_v2 source now contains {fragment!r} — "
f"report-path sanitisation added? Re-evaluate the "
f"delete-time unlink trust."
)