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.

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