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.

8.1 KB
Raw Blame
"""
Comprehensive tests for security/directory_creation.py

Containment to an expected root is OPT-IN: passing no ``root=`` (the
default) performs the audited creation with null-byte and raw ``..``
traversal rejection but NO containment check. Containment is enforced
only when the caller explicitly passes ``root=``.

Tests cover:
- create_directory with root=None (the default): creates freely, but
  null-byte and raw ".." traversal rejection still apply
- create_directory with an explicit root=: containment is enforced
- mode / parents / exist_ok behavior
- symlinked-parent escape detection (requires an explicit root=)
"""

import pytest

from local_deep_research.security.directory_creation import (
    DirectoryCreationSecurityError,
    create_directory,
)


class TestCreateDirectoryNoRoot:
    """Tests for create_directory with root=None (the default).

    No containment is enforced in this mode -- the function is the audited
    + validated chokepoint, not a jail. Null-byte and raw ".." rejection
    still apply regardless of root.
    """

    def test_creates_dir_with_no_root(self, tmp_path):
        target = tmp_path / "subdir" / "nested"

        result = create_directory(target, context="test nested dir")

        assert result == target.resolve()
        assert target.is_dir()

    def test_no_containment_by_default(self, tmp_path):
        # A "conceptual" base exists alongside an entirely unrelated
        # location. With no root= passed, create_directory must not care
        # that target is nowhere near conceptual_base -- proving there is
        # no default/implicit containment now that it is opt-in.
        conceptual_base = tmp_path / "conceptual_base"
        conceptual_base.mkdir()
        target = tmp_path / "elsewhere" / "unrelated_dir"

        result = create_directory(target, context="no containment by default")

        assert result == target.resolve()
        assert target.is_dir()

    def test_traversal_that_resolves_outside_conceptual_base_succeeds(
        self, tmp_path
    ):
        # Without an explicit root=, a path that *resolves* outside some
        # conceptual base (but contains no raw ".." segment in its own
        # input -- it is built directly, not via "..") is created
        # successfully: there is nothing to contain it to.
        conceptual_base = tmp_path / "conceptual_base"
        conceptual_base.mkdir()
        target = tmp_path / "outside_conceptual_base"

        result = create_directory(target, context="outside conceptual base")

        assert result == target.resolve()
        assert target.is_dir()

    def test_rejects_null_byte_without_root(self, tmp_path):
        bad_path = str(tmp_path / "sub\x00dir")

        with pytest.raises(DirectoryCreationSecurityError, match="null byte"):
            create_directory(bad_path, context="null byte test")

    def test_rejects_raw_dotdot_segment_without_root(self, tmp_path):
        # No root= is passed, yet the raw ".." segment in the ORIGINAL
        # input must still be rejected -- this check is unconditional, not
        # part of the opt-in containment behavior.
        traversal_path = tmp_path / "foo" / ".." / "foo"

        with pytest.raises(DirectoryCreationSecurityError, match="traversal"):
            create_directory(traversal_path, context="dotdot in middle")

        assert not (tmp_path / "foo").exists()


class TestCreateDirectoryExplicitRoot:
    """Tests for create_directory with an explicit root= parameter."""

    def test_honors_explicit_root_outside_data_dir(self, tmp_path):
        base = tmp_path / "user_configured_library"
        target = base / "downloads"

        result = create_directory(
            target, context="library download dir", root=base
        )

        assert result == target.resolve()
        assert target.is_dir()

    def test_rejects_path_escaping_explicit_root(self, tmp_path):
        base = tmp_path / "library_root"
        base.mkdir()
        outside = tmp_path / "other_dir"

        with pytest.raises(DirectoryCreationSecurityError) as exc_info:
            create_directory(outside, context="escape attempt", root=base)

        assert str(base.resolve()) in str(exc_info.value)
        assert not outside.exists()

    def test_rejects_relative_traversal_with_explicit_root(self, tmp_path):
        base = tmp_path / "library_root"
        base.mkdir()
        escape_attempt = base / ".." / "escaped"

        with pytest.raises(DirectoryCreationSecurityError):
            create_directory(escape_attempt, context="dotdot escape", root=base)

    def test_creating_root_itself_is_allowed(self, tmp_path):
        base = tmp_path / "library_root"

        result = create_directory(base, context="root itself", root=base)

        assert result == base.resolve()
        assert base.is_dir()


class TestCreateDirectoryValidation:
    """Tests for input validation (null bytes, traversal segments) when an
    explicit root= is also given, showing these checks run independently of
    (and before) the containment check."""

    def test_rejects_null_byte_in_path(self, tmp_path):
        base = tmp_path / "root"
        base.mkdir()
        bad_path = str(base / "sub\x00dir")

        with pytest.raises(DirectoryCreationSecurityError, match="null byte"):
            create_directory(bad_path, context="null byte test", root=base)

    def test_rejects_raw_dotdot_segment_in_original_input(self, tmp_path):
        base = tmp_path / "root"
        base.mkdir()
        # Even though this resolves inside base (root/foo/../foo == root/foo),
        # the raw ".." segment in the original input must be rejected.
        traversal_path = base / "foo" / ".." / "foo"

        with pytest.raises(DirectoryCreationSecurityError, match="traversal"):
            create_directory(
                traversal_path, context="dotdot in middle", root=base
            )


class TestCreateDirectoryModeParentsExistOk:
    """Tests for mode / parents / exist_ok behavior."""

    def test_parents_false_raises_when_parent_missing(self, tmp_path):
        base = tmp_path / "root"
        base.mkdir()
        target = base / "missing_parent" / "child"

        with pytest.raises(FileNotFoundError):
            create_directory(
                target, context="no parents", root=base, parents=False
            )

    def test_exist_ok_false_raises_when_dir_exists(self, tmp_path):
        base = tmp_path / "root"
        base.mkdir()
        target = base / "existing"
        target.mkdir()

        with pytest.raises(FileExistsError):
            create_directory(
                target, context="already exists", root=base, exist_ok=False
            )

    def test_exist_ok_true_is_idempotent(self, tmp_path):
        base = tmp_path / "root"
        base.mkdir()
        target = base / "existing"
        target.mkdir()

        # Should not raise.
        result = create_directory(
            target, context="idempotent create", root=base, exist_ok=True
        )
        assert result == target.resolve()

    def test_mode_is_applied_to_new_directory(self, tmp_path):
        base = tmp_path / "root"
        base.mkdir()
        target = base / "restricted"

        create_directory(target, context="mode test", root=base, mode=0o700)

        # Account for umask potentially clearing bits; just verify owner rwx.
        actual_mode = target.stat().st_mode & 0o700
        assert actual_mode == 0o700


class TestCreateDirectorySymlinkEscape:
    """Tests for symlinked-parent escape detection.

    Symlink-escape detection is only meaningful in combination with
    containment, so this test passes an explicit root=.
    """

    def test_symlinked_parent_escaping_root_is_caught(self, tmp_path):
        base = tmp_path / "root"
        base.mkdir()
        outside = tmp_path / "outside"
        outside.mkdir()

        # Create a symlink inside the root that points outside of it.
        symlink_dir = base / "link_out"
        symlink_dir.symlink_to(outside, target_is_directory=True)

        target = symlink_dir / "new_subdir"

        with pytest.raises(DirectoryCreationSecurityError):
            create_directory(target, context="symlink escape", root=base)

        assert not (outside / "new_subdir").exists()