~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
"""Security module for verified directory creation operations.
This module provides a single audited chokepoint for creating directories.
Like ``security/file_write_verifier.py`` it is the sanctioned entry point that
all production directory creation must route through (enforced by a
pre-commit/CI check that forbids raw ``mkdir``/``makedirs``), giving one place
that rejects null bytes and ``..`` traversal, resolves symlinks, and audit-logs
every creation.
Containment to an expected root is OPT-IN: pass ``root=`` when the target is
built from an untrusted / user-influenced component (e.g. a per-user directory
named after a username) to require it to resolve inside that root. Most call
sites build paths from trusted constants under the data directory and pass no
``root`` — for them the value is the audit + the no-bypass guarantee, not
containment.
"""
from pathlib import Path
from loguru import logger
class DirectoryCreationSecurityError(Exception):
"""Raised when a directory creation operation is not allowed by security checks."""
pass
def create_directory(
path: str | Path,
*,
context: str,
root: str | Path | None = None,
parents: bool = True,
exist_ok: bool = True,
mode: int | None = None,
) -> Path:
"""Create a directory through the audited security chokepoint.
Rejects null bytes and raw ``..`` traversal, resolves the path (following
symlinks), optionally enforces containment within ``root``, creates the
directory, and audit-logs it.
Args:
path: Path to the directory to create.
context: Description of what's being created (for error messages and
audit logs).
root: Optional containment root. When provided, ``path`` must resolve
inside ``root`` (a symlinked parent that escapes it is caught) or a
``DirectoryCreationSecurityError`` is raised. Pass this only when
``path`` is built from an untrusted / user-influenced component;
when ``None`` (the default) no containment is enforced.
parents: Create parent directories as needed (default: True).
exist_ok: Do not raise if the directory already exists (default: True).
mode: Optional permission mode to pass to ``Path.mkdir``. If ``None``,
the ``Path.mkdir`` default is used.
Returns:
The resolved ``Path`` of the created directory.
Raises:
DirectoryCreationSecurityError: If the path contains a null byte, a
raw ``..`` traversal segment, or (when ``root`` is given) resolves
outside ``root``.
OSError: If ``path`` or ``root`` cannot be fully resolved (a symlink
loop, a symlink chain whose resolved form outgrows PATH_MAX, an
unreadable component), or if the mkdir itself fails.
Example:
>>> create_directory(data_dir / "cache", context="rag cache")
>>> # opt-in containment for an untrusted leaf name:
>>> create_directory(
... base / username, context="per-user library", root=base
... )
"""
# Reject null bytes in the raw path before any resolution happens.
if "\x00" in str(path):
raise DirectoryCreationSecurityError(
f"Refusing to create directory with null byte in path ({context})"
)
# Reject a raw ".." segment in the ORIGINAL input path parts. This is
# checked before resolve() because resolve() would silently collapse a
# traversal attempt, hiding the fact that the caller tried to escape.
if ".." in Path(path).parts:
raise DirectoryCreationSecurityError(
f"Refusing to create directory with '..' traversal segment: {path} ({context})"
)
# Resolution follows symlinks, so a symlinked parent directory that
# escapes the root is caught here. It also works for paths that do not
# yet exist. resolve_allow_missing() tolerates only missing components
# and raises OSError for anything else it cannot resolve (a loop, or a
# symlink chain whose resolved form outgrows PATH_MAX), where a bare
# non-strict resolve() would return a half-resolved path. Lazy import:
# this module is imported very early during bootstrap.
from .path_validator import resolve_allow_missing
p = resolve_allow_missing(Path(path))
if root is not None:
# Opt-in containment: require the target to resolve inside the given
# root. The resolution above already followed symlinks, so a
# symlinked parent that escapes the root is caught here too. (A path
# is is_relative_to itself, so creating the root itself is allowed.)
root_resolved = resolve_allow_missing(Path(root))
if not p.is_relative_to(root_resolved):
raise DirectoryCreationSecurityError(
f"Refusing to create directory outside {root_resolved}: {p} ({context})"
)
if mode is not None:
# nosemgrep: semgrep.rules.path-traversal-risk, reason: Verified directory helper rejects nulls and traversal segments and checks resolved containment when root is supplied
p.mkdir(parents=parents, exist_ok=exist_ok, mode=mode)
else:
# nosemgrep: semgrep.rules.path-traversal-risk, reason: Verified directory helper rejects nulls and traversal segments and checks resolved containment when root is supplied
p.mkdir(parents=parents, exist_ok=exist_ok)
logger.debug(f"Verified directory creation: {p} ({context})")
return p