Skip to content

~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.

16.6 KB
Raw Blame
"""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