← Files Codex SecurityARCHIVED FILE

scripts/posix_scan_local_files.py

8.74 KB · Nov 21, 2026 · 18:10 UTC

↓ Download file

See the change to this file →

"""Stage and publish POSIX scan-local files through verified directory descriptors."""

from __future__ import annotations

import argparse
import errno
import os
import secrets
import stat
import sys
from collections.abc import Callable, Iterator
from contextlib import contextmanager
from pathlib import Path, PurePosixPath


def descriptor_relative_writes_available() -> bool:
    """Return whether the platform supports the descriptor-relative operations used for writes."""
    # os.replace accepts src_dir_fd/dst_dir_fd wherever descriptor-relative
    # os.rename is supported, but Python lists only os.rename in supports_dir_fd.
    required_operations = (os.mkdir, os.open, os.rename, os.stat, os.unlink)
    return hasattr(os, "O_NOFOLLOW") and all(
        operation in os.supports_dir_fd for operation in required_operations
    )


@contextmanager
def managed_fd(descriptor: int) -> Iterator[int]:
    """Yield the descriptor and close it when the context exits, including on error."""
    try:
        yield descriptor
    finally:
        os.close(descriptor)


@contextmanager
def stage_file(
    parent_fd: int, filename: str, payload: bytes, owner_read_write: bool
) -> Iterator[int]:
    """Yield a synced file descriptor for a new staging entry, removing the entry on exit if it still matches."""
    descriptor = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=parent_fd)
    try:
        with os.fdopen(descriptor, "wb", closefd=False) as handle:
            if owner_read_write:
                os.fchmod(descriptor, 0o600)
            handle.write(payload)
            handle.flush()
            os.fsync(descriptor)
        yield descriptor
    finally:
        try:
            entry = os.stat(filename, dir_fd=parent_fd, follow_symlinks=False)
            if os.path.samestat(os.fstat(descriptor), entry):
                os.unlink(filename, dir_fd=parent_fd)
        except FileNotFoundError:
            # Successful publication has already removed the temporary name.
            pass
        finally:
            os.close(descriptor)


def _rename_exclusive(parent_fd: int, source: str, destination: str) -> None:
    """Rename a directory entry atomically while requiring the destination to be absent."""
    import ctypes

    libc = ctypes.CDLL(None, use_errno=True)
    if sys.platform == "linux":
        rename = getattr(libc, "renameat2", None)
        flag = 1  # RENAME_NOREPLACE
    elif sys.platform == "darwin":
        rename = getattr(libc, "renameatx_np", None)
        flag = 4  # RENAME_EXCL
    else:
        rename = None
    code = errno.ENOSYS
    if rename is not None:
        rename.argtypes = [
            ctypes.c_int,
            ctypes.c_char_p,
            ctypes.c_int,
            ctypes.c_char_p,
            ctypes.c_uint,
        ]
        rename.restype = ctypes.c_int
        if rename(parent_fd, os.fsencode(source), parent_fd, os.fsencode(destination), flag) == 0:
            return
        code = ctypes.get_errno()
    elif sys.platform == "linux":
        import sysconfig

        # musl omits the renameat2 wrapper. Select the syscall for the Python
        # process's ABI, which can differ from the host kernel's architecture.
        arch = (sysconfig.get_config_var("MULTIARCH") or "").partition("-")[0]
        number = {"x86_64": 316, "aarch64": 276}.get(arch)
        syscall = getattr(libc, "syscall", None)
        if number is not None and ctypes.sizeof(ctypes.c_void_p) == 8 and syscall is not None:
            syscall.argtypes = [ctypes.c_long]
            syscall.restype = ctypes.c_long
            result = syscall(
                number,
                ctypes.c_long(parent_fd),
                ctypes.c_char_p(os.fsencode(source)),
                ctypes.c_long(parent_fd),
                ctypes.c_char_p(os.fsencode(destination)),
                ctypes.c_long(flag),
            )
            if result == 0:
                return
            code = ctypes.get_errno()
    detail = os.strerror(code)
    if code in {errno.ENOSYS, errno.ENOTSUP, errno.EOPNOTSUPP, errno.EINVAL}:
        detail = f"cannot publish a new file atomically without hard links or exclusive rename ({detail})"
    raise OSError(code, detail, destination)


def publish_new_file(parent_fd: int, source: str, destination: str) -> None:
    """Publish the staged name without overwriting the destination, using an exclusive rename if linking is unavailable."""
    try:
        os.link(
            source, destination, src_dir_fd=parent_fd, dst_dir_fd=parent_fd, follow_symlinks=False
        )
    except OSError as exc:
        if exc.errno not in {
            errno.EPERM,
            errno.ENOTSUP,
            errno.EOPNOTSUPP,
            errno.ENOSYS,
            errno.EXDEV,
            errno.EMLINK,
        }:
            raise
        _rename_exclusive(parent_fd, source, destination)
    else:
        os.unlink(source, dir_fd=parent_fd)


@contextmanager
def stage_write(
    parent_fd: int,
    relative_path: str,
    payload: bytes,
    *,
    owner_read_write: bool,
    replace_existing: bool,
    compare_existing: bool,
    check_parent: Callable[[Path], None],
    contract_error: type[ValueError],
) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:
    """Stage payload under the open parent directory and yield a callable that publishes it.

    Call the publisher inside the context. It returns file metadata and the
    change time in nanoseconds. With compare_existing, matching bytes can
    reuse an existing file when replacements are allowed.
    """
    name = PurePosixPath(relative_path).name
    # Stage through the held parent so a replacement path cannot redirect the write.
    try:
        metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
    except FileNotFoundError:
        pass
    else:
        if not replace_existing:
            raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), relative_path)
        if not stat.S_ISREG(metadata.st_mode):
            raise contract_error(f"{relative_path}: expected a regular non-symlink file")
        try:
            existing_fd = os.open(
                name,
                os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0),
                dir_fd=parent_fd,
            )
        except OSError as exc:
            if exc.errno not in {errno.ENOENT, errno.EACCES, errno.EPERM}:
                raise
        else:
            with managed_fd(existing_fd):
                opened = os.fstat(existing_fd)
                if not stat.S_ISREG(opened.st_mode):
                    raise contract_error(f"{relative_path}: expected a regular non-symlink file")
                if not os.path.samestat(opened, metadata):
                    raise contract_error(f"{relative_path}: changed while it was being opened")
                if compare_existing and opened.st_size == len(payload):
                    from windows_scan_local_files import stream_matches_payload

                    try:
                        with os.fdopen(existing_fd, "rb", closefd=False) as handle:
                            matches = stream_matches_payload(handle, payload)
                    except OSError:
                        # A failed content comparison still allows an atomic replacement.
                        matches = False
                    if matches:
                        yield lambda _directory=None: (opened, opened.st_ctime_ns)
                        return
    # A valid destination may already occupy the filesystem's entire name limit.
    candidate = f".{secrets.token_hex(8)}.tmp"
    if name.casefold() == candidate:
        candidate = "." + candidate

    with stage_file(parent_fd, candidate, payload, owner_read_write) as staged_fd:
        staged = os.fstat(staged_fd)

        def publish(directory: Path | None = None) -> tuple[os.stat_result, int]:
            if directory is not None:
                check_parent(directory)
            if replace_existing:
                os.replace(candidate, name, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
                return staged, staged.st_ctime_ns
            named = os.stat(candidate, dir_fd=parent_fd, follow_symlinks=False)
            if not os.path.samestat(staged, named) or staged.st_ctime_ns != named.st_ctime_ns:
                raise contract_error(f"{relative_path}: staged file changed before publication")
            publish_new_file(parent_fd, candidate, name)
            published = os.fstat(staged_fd)
            if (staged.st_size, staged.st_mtime_ns) != (
                published.st_size,
                published.st_mtime_ns,
            ):
                raise contract_error(f"{relative_path}: staged contents changed during publication")
            return published, published.st_ctime_ns

        yield publish


if __name__ == "__main__":
    argparse.ArgumentParser(description=__doc__).parse_args()

SHA-256: 0911b75dc67fdc04d0284fb97977063fe88ab3dfc2ec79becc426ff55483dfd7