~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
"""High-value tests for security/module_whitelist.py - Module Import Security."""
from unittest.mock import patch, MagicMock
import pytest
from local_deep_research.security.module_whitelist import (
validate_module_import,
get_safe_module_class,
ALLOWED_MODULE_PATHS,
ALLOWED_CLASS_NAMES,
ALLOWED_MODULES,
SecurityError,
ModuleNotAllowedError,
)
# ---------------------------------------------------------------------------
# ALLOWED_MODULE_PATHS constraints
# ---------------------------------------------------------------------------
class TestAllowedModulePaths:
"""Whitelist structure validation."""
def test_is_frozenset(self):
assert isinstance(ALLOWED_MODULE_PATHS, frozenset)
def test_all_start_with_dot(self):
for path in ALLOWED_MODULE_PATHS:
assert path.startswith("."), (
f"Module path {path!r} must start with '.'"
)
def test_legacy_alias_same_object(self):
assert ALLOWED_MODULES is ALLOWED_MODULE_PATHS
def test_known_engine_paths_present(self):
expected = [
".engines.search_engine_brave",
".engines.search_engine_arxiv",
".engines.search_engine_wikipedia",
".engines.search_engine_tavily",
]
for path in expected:
assert path in ALLOWED_MODULE_PATHS
def test_not_empty(self):
assert len(ALLOWED_MODULE_PATHS) > 0
# ---------------------------------------------------------------------------
# ALLOWED_CLASS_NAMES constraints
# ---------------------------------------------------------------------------
class TestAllowedClassNames:
"""Class name whitelist validation."""
def test_is_frozenset(self):
assert isinstance(ALLOWED_CLASS_NAMES, frozenset)
def test_known_classes_present(self):
expected = [
"BraveSearchEngine",
"ArXivSearchEngine",
"WikipediaSearchEngine",
"TavilySearchEngine",
"BaseSearchEngine",
]
for cls_name in expected:
assert cls_name in ALLOWED_CLASS_NAMES
def test_not_empty(self):
assert len(ALLOWED_CLASS_NAMES) > 0
# ---------------------------------------------------------------------------
# SecurityError / ModuleNotAllowedError
# ---------------------------------------------------------------------------
class TestSecurityError:
def test_is_exception(self):
assert issubclass(SecurityError, Exception)
def test_alias_is_same_class(self):
assert ModuleNotAllowedError is SecurityError
def test_can_raise_and_catch(self):
with pytest.raises(SecurityError):
raise SecurityError("blocked")
# ---------------------------------------------------------------------------
# validate_module_import()
# ---------------------------------------------------------------------------
class TestValidateModuleImport:
"""Module + class pair validation."""
def test_valid_pair_accepted(self):
assert (
validate_module_import(
".engines.search_engine_brave", "BraveSearchEngine"
)
is True
)
def test_non_relative_path_rejected(self):
assert validate_module_import("os", "system") is False
def test_absolute_dotted_path_rejected(self):
assert (
validate_module_import(
"local_deep_research.web_search_engines.engines.search_engine_brave",
"BraveSearchEngine",
)
is False
)
def test_empty_module_rejected(self):
assert validate_module_import("", "BraveSearchEngine") is False
def test_empty_class_rejected(self):
assert (
validate_module_import(".engines.search_engine_brave", "") is False
)
def test_both_empty_rejected(self):
assert validate_module_import("", "") is False
def test_unlisted_module_rejected(self):
assert (
validate_module_import(
".engines.search_engine_evil", "BraveSearchEngine"
)
is False
)
def test_unlisted_class_rejected(self):
assert (
validate_module_import(".engines.search_engine_brave", "EvilEngine")
is False
)
def test_both_unlisted_rejected(self):
assert validate_module_import(".evil_module", "EvilClass") is False
# ---------------------------------------------------------------------------
# get_safe_module_class()
# ---------------------------------------------------------------------------
class TestGetSafeModuleClass:
"""Safe dynamic import."""
def test_invalid_module_raises_security_error(self):
with pytest.raises(
SecurityError, match="not in the security whitelist"
):
get_safe_module_class("os", "system")
def test_invalid_class_raises_security_error(self):
with pytest.raises(
SecurityError, match="not in the security whitelist"
):
get_safe_module_class(".engines.search_engine_brave", "EvilClass")
def test_whitelisted_class_non_whitelisted_module_rejected(self):
"""Whitelisted class name with non-whitelisted module still raises."""
with pytest.raises(
SecurityError, match="not in the security whitelist"
):
get_safe_module_class(
".engines.search_engine_evil", "BraveSearchEngine"
)
@patch(
"local_deep_research.security.module_whitelist.importlib.import_module"
)
def test_valid_pair_imports_and_returns_class(self, mock_import):
mock_module = MagicMock()
mock_module.BraveSearchEngine = type("BraveSearchEngine", (), {})
mock_import.return_value = mock_module
cls = get_safe_module_class(
".engines.search_engine_brave", "BraveSearchEngine"
)
assert cls is mock_module.BraveSearchEngine
mock_import.assert_called_once_with(
".engines.search_engine_brave",
package="local_deep_research.web_search_engines",
)
@patch(
"local_deep_research.security.module_whitelist.importlib.import_module"
)
def test_custom_package_used(self, mock_import):
mock_module = MagicMock()
mock_module.BraveSearchEngine = type("BraveSearchEngine", (), {})
mock_import.return_value = mock_module
get_safe_module_class(
".engines.search_engine_brave",
"BraveSearchEngine",
package="custom.package",
)
mock_import.assert_called_once_with(
".engines.search_engine_brave", package="custom.package"
)
@patch(
"local_deep_research.security.module_whitelist.importlib.import_module"
)
def test_module_not_found_propagates(self, mock_import):
mock_import.side_effect = ModuleNotFoundError("No module")
with pytest.raises(ModuleNotFoundError):
get_safe_module_class(
".engines.search_engine_brave", "BraveSearchEngine"
)
@patch(
"local_deep_research.security.module_whitelist.importlib.import_module"
)
def test_attribute_error_propagates(self, mock_import):
mock_module = MagicMock(spec=[]) # no attributes
mock_import.return_value = mock_module
with pytest.raises(AttributeError):
get_safe_module_class(
".engines.search_engine_brave", "BraveSearchEngine"
)
def test_success_log_emitted_below_debug(self):
"""Successful imports must log below the database sink's DEBUG
floor so the routine noise does not get persisted into research
logs. The database sink only persists levels ≥ DEBUG, so dropping
the level to TRACE keeps these lines out of /api/research/<id>/logs.
Note: both patches use ``with patch`` (not decorators) and
``logger`` is patched first. ``unittest.mock`` silently fails to
replace ``module_whitelist.logger`` when ``module_whitelist
.importlib.import_module`` is already being patched in the
same scope — the import-module patch interacts with the
module's namespace lookups in a way that breaks the subsequent
attribute assignment. Inverting the order (logger first, then
import_module) avoids the interaction."""
mock_module = MagicMock()
mock_module.BraveSearchEngine = type("BraveSearchEngine", (), {})
with patch(
"local_deep_research.security.module_whitelist.logger"
) as mock_logger:
with patch(
"local_deep_research.security.module_whitelist.importlib.import_module"
) as mock_import:
mock_import.return_value = mock_module
get_safe_module_class(
".engines.search_engine_brave", "BraveSearchEngine"
)
# The "successfully loaded" line must be logged at trace level, not
# debug, so it cannot be persisted to ResearchLog.
trace_calls = [
call_args
for call_args in mock_logger.trace.call_args_list
if call_args.args
and "Successfully loaded BraveSearchEngine" in call_args.args[0]
]
debug_calls = [
call_args
for call_args in mock_logger.debug.call_args_list
if call_args.args
and "Successfully loaded BraveSearchEngine" in call_args.args[0]
]
assert trace_calls, (
"Successful import must be logged at trace level so it is below"
" the database sink's DEBUG floor"
)
assert not debug_calls, (
"Successful import must NOT be logged at debug level — that would"
" get persisted to ResearchLog"
)