~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
"""
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()