~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
"""Hypothesis properties for library PDF filesystem confinement.
Complements the fixed-payload batteries in ``test_remote_filename_writes``
and ``test_poisoned_path_reads``. A failure that creates/modifies an
outside-root path or serves the canary marker is a vulnerability;
setup/liveness failures are a broken test.
Fixtures: ``fs_storage``, ``fresh_document``, ``library_session`` and
``canary_paths`` come from
``tests/security/conftest.py`` (they were duplicated verbatim across four
batteries in this directory and are now defined once); ``library_client``
is built here from ``test_poisoned_path_reads``'s
``_authenticated_fastapi_client`` helper because it is specific to the
library router. The registered username is exposed as
``library_client.username`` (random per test — the Flask-era
``_make_bare_flask_client`` this used to build on could fake a fixed
session username, a real FastAPI login cannot). All of them use
``tmp_path`` only.
Run with:
``.venv/bin/python -m pytest tests/security/test_path_property_fuzz.py -v --no-header --timeout=120``
"""
from __future__ import annotations
from pathlib import Path
from unittest.mock import patch
import pytest
from hypothesis import HealthCheck, given, settings, strategies as st
from tests.test_utils import add_src_to_path
add_src_to_path()
from tests.security.test_poisoned_path_reads import ( # noqa: E402
_LR,
_PDF_POISON,
_PDF_SAFE,
_authenticated_fastapi_client,
_library_settings_mock,
_make_canary,
_patched_user_db_session,
_slowapi_off, # noqa: F401 -- registers the autouse rate-limiter fixture
)
from tests.security.test_remote_filename_writes import ( # noqa: E402
_MINIMAL_PDF,
_assert_files_inside,
)
_ANY_NON_SURROGATE = st.characters(blacklist_categories=("Cs",))
_HOSTILE_ATOMS = st.sampled_from(
[
"..",
".",
"...",
"....",
"/",
"\\",
"../",
"..\\",
"..//",
"....//",
"..;/",
"%2e%2e%2f",
"%2e%2e/",
"..%2f",
"..%252f",
"..%c0%af",
"\x00",
"evil\x00.pdf",
"\uff0e\uff0e\uff0f",
"cafe\u0301",
"cafe\u00e9",
"a b",
"-rf",
"tmp",
"etc",
"root",
"escape.pdf",
]
)
def _hostile_paths():
"""Random 1..2000-character names, biased toward hostile path atoms."""
return st.one_of(
st.text(alphabet=_ANY_NON_SURROGATE, min_size=1, max_size=2000),
st.builds(
"".join,
st.lists(
st.one_of(
_HOSTILE_ATOMS,
st.text(alphabet=_ANY_NON_SURROGATE, max_size=25),
),
min_size=1,
max_size=8,
),
),
)
def _depth_neutral_segments():
"""Fuzzed single path segments that preserve a fixed escape depth."""
return st.text(
alphabet=st.characters(blacklist_categories=("Cs", "Cc")),
min_size=1,
max_size=60,
).filter(lambda value: "/" not in value and value not in (".", ".."))
def _outside_state(
base: Path, library_root: Path
) -> dict[str, tuple[str, bytes | str | None]]:
root = library_root.resolve()
state: dict[str, tuple[str, bytes | str | None]] = {}
for path in sorted(base.rglob("*")):
resolved = path.resolve()
if resolved == root or root in resolved.parents:
continue
if path.is_symlink():
state[str(path)] = ("symlink", str(path.readlink()))
elif path.is_file():
state[str(path)] = ("file", path.read_bytes())
else:
state[str(path)] = ("directory", None)
return state
def _assert_outside_tree_unchanged(
before: dict[str, tuple[str, bytes | str | None]],
tmp_path: Path,
library_root: Path,
) -> None:
after = _outside_state(tmp_path, library_root)
assert after == before, (
"VULNERABILITY: save_pdf created, deleted, or modified an entry "
f"outside library_root {library_root}"
)
@pytest.fixture
def library_client(app):
"""Authenticated client for the REAL FastAPI library router.
Same helper as ``test_poisoned_path_reads.library_client``. The real
registered username is exposed as ``.username`` — tests below use it
to compute the per-user storage root the same way the route does
(``apply_user_subdir``), rather than a hardcoded constant.
"""
return _authenticated_fastapi_client(app, "library-pdf-user")
class TestSavePdfProperty:
@given(filename=_hostile_paths())
@settings(
max_examples=50,
deadline=None,
suppress_health_check=[HealthCheck.function_scoped_fixture],
)
def test_random_filename_is_rejected_or_confined(
self,
fs_storage,
fresh_document,
library_session,
canary_paths,
tmp_path,
filename,
):
before = _outside_state(tmp_path, fs_storage.library_root)
fresh_document.storage_mode = None
fresh_document.file_path = None
try:
relative_path, _ = fs_storage.save_pdf(
_MINIMAL_PDF,
fresh_document,
library_session,
filename,
)
except (ValueError, OSError):
_assert_files_inside(fs_storage.library_root, None, canary_paths)
_assert_outside_tree_unchanged(
before, tmp_path, fs_storage.library_root
)
return
_assert_files_inside(
fs_storage.library_root, relative_path, canary_paths
)
written = (fs_storage.library_root / relative_path).resolve()
assert written.is_file(), f"save_pdf returned missing path: {written}"
assert written.read_bytes() == _MINIMAL_PDF
_assert_outside_tree_unchanged(
before, tmp_path, fs_storage.library_root
)
@given(segment=_depth_neutral_segments())
@settings(
max_examples=40,
deadline=None,
suppress_health_check=[HealthCheck.function_scoped_fixture],
)
def test_live_traversal_filename_cannot_create_outside_file(
self,
fs_storage,
fresh_document,
library_session,
canary_paths,
tmp_path,
segment,
):
filename = f"pdfs/{segment}/../../../outside_canary_zone/escape.pdf"
expected = tmp_path / "outside_canary_zone" / "escape.pdf"
assert (
fs_storage.library_root / filename
).resolve() == expected.resolve()
before = _outside_state(tmp_path, fs_storage.library_root)
fresh_document.storage_mode = None
fresh_document.file_path = None
try:
relative_path, _ = fs_storage.save_pdf(
_MINIMAL_PDF,
fresh_document,
library_session,
filename,
)
except (ValueError, OSError):
_assert_files_inside(fs_storage.library_root, None, canary_paths)
_assert_outside_tree_unchanged(
before, tmp_path, fs_storage.library_root
)
return
_assert_files_inside(
fs_storage.library_root, relative_path, canary_paths
)
_assert_outside_tree_unchanged(
before, tmp_path, fs_storage.library_root
)
class TestLibraryResolverProperty:
USERNAME = "fuzz-resolver-user"
@staticmethod
def _root(tmp_path: Path) -> tuple[Path, Path]:
base_root = tmp_path / "library"
root = base_root / TestLibraryResolverProperty.USERNAME
root.mkdir(parents=True, exist_ok=True)
return base_root, root
@given(relative_path=_hostile_paths())
@settings(
max_examples=50,
deadline=None,
suppress_health_check=[HealthCheck.function_scoped_fixture],
)
def test_random_path_resolves_inside_root_or_none(
self, tmp_path, relative_path, monkeypatch
):
from local_deep_research.research_library.utils import (
get_absolute_path_from_settings,
)
# get_absolute_path_from_settings's storage_path lookup carries an
# eagerly-evaluated str(get_library_directory()) default -- Python
# evaluates it before get_setting() runs, regardless of the
# explicit settings_manager passed below, so it unconditionally
# mkdirs <data_dir>/library. Pin LDR_DATA_DIR so that lands under
# tmp_path instead of the real platformdirs user data dir.
monkeypatch.setenv("LDR_DATA_DIR", str(tmp_path / "app_data"))
base_root, root = self._root(tmp_path)
canary = _make_canary(tmp_path / "secrets", "canary.pdf", _PDF_POISON)
resolved = get_absolute_path_from_settings(
relative_path,
self.USERNAME,
settings_manager=_library_settings_mock(base_root),
)
if resolved is not None:
assert resolved.resolve().is_relative_to(root.resolve()), (
"VULNERABILITY: get_absolute_path_from_settings returned "
f"outside-root path {resolved} for {relative_path!r}"
)
assert canary.read_bytes() == _PDF_POISON
@given(segment=_depth_neutral_segments())
@settings(
max_examples=40,
deadline=None,
suppress_health_check=[HealthCheck.function_scoped_fixture],
)
def test_live_traversal_resolver_returns_none(
self, tmp_path, segment, monkeypatch
):
from local_deep_research.research_library.utils import (
get_absolute_path_from_settings,
)
# Same eager-default-argument hazard as
# test_random_path_resolves_inside_root_or_none above.
monkeypatch.setenv("LDR_DATA_DIR", str(tmp_path / "app_data"))
base_root, root = self._root(tmp_path)
canary = _make_canary(tmp_path / "secrets", "canary.pdf", _PDF_POISON)
relative_path = f"pdfs/{segment}/../../../../secrets/canary.pdf"
assert (root / relative_path).resolve() == canary.resolve()
resolved = get_absolute_path_from_settings(
relative_path,
self.USERNAME,
settings_manager=_library_settings_mock(base_root),
)
assert resolved is None, (
"VULNERABILITY: resolver returned a path for a live traversal "
f"payload: {resolved}"
)
assert canary.read_bytes() == _PDF_POISON
class TestPdfStorageReadProperty:
@given(file_path=_hostile_paths())
@settings(
max_examples=40,
deadline=None,
suppress_health_check=[HealthCheck.function_scoped_fixture],
)
def test_random_file_path_never_returns_bytes(
self, fs_storage, fresh_document, library_session, tmp_path, file_path
):
canary = _make_canary(tmp_path / "secrets", "canary.pdf", _PDF_POISON)
fresh_document.file_path = file_path
fresh_document.storage_mode = "filesystem"
result = fs_storage.load_pdf(fresh_document, library_session)
assert result is None, (
"VULNERABILITY: load_pdf returned bytes although the only PDF is "
f"the outside canary for {file_path!r}"
)
assert canary.read_bytes() == _PDF_POISON
@given(segment=_depth_neutral_segments())
@settings(
max_examples=40,
deadline=None,
suppress_health_check=[HealthCheck.function_scoped_fixture],
)
def test_live_traversal_file_path_never_returns_canary(
self, fs_storage, fresh_document, library_session, tmp_path, segment
):
canary = _make_canary(tmp_path / "secrets", "canary.pdf", _PDF_POISON)
file_path = f"pdfs/{segment}/../../../secrets/canary.pdf"
assert (
fs_storage.library_root / file_path
).resolve() == canary.resolve()
fresh_document.file_path = file_path
fresh_document.storage_mode = "filesystem"
assert fs_storage.load_pdf(fresh_document, library_session) is None, (
"VULNERABILITY: load_pdf served the outside-root canary"
)
assert canary.read_bytes() == _PDF_POISON
@given(
payload=st.one_of(
_hostile_paths().map(lambda value: (value, None)),
_depth_neutral_segments().map(
lambda segment: (
f"pdfs/{segment}/../../../secrets/canary.pdf",
segment,
)
),
)
)
@settings(
max_examples=40,
deadline=None,
suppress_health_check=[HealthCheck.function_scoped_fixture],
)
def test_has_pdf_is_false_without_an_in_root_file(
self, fs_storage, fresh_document, library_session, tmp_path, payload
):
file_path, live_segment = payload
canary = _make_canary(tmp_path / "secrets", "canary.pdf", _PDF_POISON)
if live_segment is not None:
assert (
fs_storage.library_root / file_path
).resolve() == canary.resolve()
fresh_document.file_path = file_path
fresh_document.storage_mode = "filesystem"
assert fs_storage.has_pdf(fresh_document, library_session) is False, (
"VULNERABILITY: has_pdf accepted a path despite no in-root PDF "
f"existing for {file_path!r}"
)
assert canary.read_bytes() == _PDF_POISON
class TestViewPdfRouteProperty:
@given(
payload=st.one_of(
_hostile_paths().map(lambda value: (value, None)),
_depth_neutral_segments().map(
lambda segment: (
f"pdfs/{segment}/../../../../secrets/canary.pdf",
segment,
)
),
)
)
@settings(
max_examples=25,
deadline=None,
suppress_health_check=[HealthCheck.function_scoped_fixture],
)
def test_route_never_serves_outside_canary(
self,
library_client,
fresh_document,
library_session,
tmp_path,
payload,
):
file_path, live_segment = payload
base_root = tmp_path / "library"
root = base_root / library_client.username
(root / "pdfs").mkdir(parents=True, exist_ok=True)
canary = _make_canary(tmp_path / "secrets", "canary.pdf", _PDF_POISON)
if live_segment is not None:
assert (root / file_path).resolve() == canary.resolve()
fresh_document.file_path = file_path
fresh_document.storage_mode = "filesystem"
library_session.commit()
with patch(
f"{_LR}.get_settings_manager",
return_value=_library_settings_mock(base_root),
):
with _patched_user_db_session(_LR, library_session):
response = library_client.get(
f"/library/document/{fresh_document.id}/pdf"
)
assert response.status_code in (200, 404, 500)
assert _PDF_POISON not in response.data, (
"VULNERABILITY: view_pdf route served outside-root canary bytes"
)
assert canary.read_bytes() == _PDF_POISON
class TestPositiveControls:
def test_clean_filename_round_trips_inside_root(
self, fs_storage, fresh_document, library_session, canary_paths
):
relative_path, _ = fs_storage.save_pdf(
_MINIMAL_PDF,
fresh_document,
library_session,
"clean.pdf",
)
written = (fs_storage.library_root / relative_path).resolve()
assert written.is_relative_to(
(fs_storage.library_root / "pdfs").resolve()
)
assert (
fs_storage.load_pdf(fresh_document, library_session) == _MINIMAL_PDF
)
assert fs_storage.has_pdf(fresh_document, library_session) is True
_assert_files_inside(
fs_storage.library_root, relative_path, canary_paths
)
def test_view_pdf_route_serves_legitimate_in_root_pdf(
self, library_client, fresh_document, library_session, tmp_path
):
base_root = tmp_path / "library"
root = base_root / library_client.username
legitimate = root / "pdfs" / "legitimate.pdf"
legitimate.parent.mkdir(parents=True)
legitimate.write_bytes(_PDF_SAFE)
fresh_document.file_path = "pdfs/legitimate.pdf"
fresh_document.storage_mode = "filesystem"
library_session.commit()
with patch(
f"{_LR}.get_settings_manager",
return_value=_library_settings_mock(base_root),
):
with _patched_user_db_session(_LR, library_session):
response = library_client.get(
f"/library/document/{fresh_document.id}/pdf"
)
assert response.status_code == 200
assert response.data == _PDF_SAFE