From 6ab0e7c1e76f302b9597a96bc6ada386326cbe49 Mon Sep 17 00:00:00 2001 From: aimable100 <129232709+aimable100@users.noreply.github.com> Date: Tue, 10 Nov 2026 18:02:57 -0800 Subject: [PATCH 1/3] Add guarded filesystem API --- .github/workflows/ci.yml | 10 +- CHANGELOG.md | 11 + Cargo.toml | 8 +- README.md | 84 +++++-- pyproject.toml | 3 +- python/path_jail/__init__.py | 4 +- python/path_jail/__init__.pyi | 84 +++++++ src/lib.rs | 457 +++++++++++++++++++++++++++++++++- tests/test_jail.py | 144 ++++++++++- 9 files changed, 775 insertions(+), 30 deletions(-) create mode 100644 CHANGELOG.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0102de9..84cff6f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -19,17 +19,25 @@ jobs: fail-fast: false matrix: os: [ubuntu-latest, macos-latest, windows-latest] - python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"] + python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"] exclude: # Reduce matrix size: test all Python versions on Linux, min/max on others - os: macos-latest python-version: "3.10" - os: macos-latest python-version: "3.11" + - os: macos-latest + python-version: "3.12" + - os: macos-latest + python-version: "3.13" - os: windows-latest python-version: "3.10" - os: windows-latest python-version: "3.11" + - os: windows-latest + python-version: "3.12" + - os: windows-latest + python-version: "3.13" steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..eaa87b2 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +## 0.4.0 - 2026-11-10 + +- Add `FdJail` guarded file operations, policy options, capabilities, and attestations. +- Add guarded directory mutations on supported Linux platforms. +- Add `Jail.join_segments()` for independently validated path components. +- Upgrade the `path_jail` Rust core to 0.6.0. +- Upgrade PyO3 to 0.30. +- Add Python 3.14 to the tested and advertised version range. + diff --git a/Cargo.toml b/Cargo.toml index a7fb290..70b6c55 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "path_jail_py" -version = "0.3.0" +version = "0.4.0" edition = "2021" license = "MIT OR Apache-2.0" description = "Python bindings for path_jail - secure filesystem sandbox" @@ -11,8 +11,8 @@ name = "path_jail" crate-type = ["cdylib"] [dependencies] -path_jail = "0.5" -pyo3 = { version = "0.24", features = ["extension-module", "abi3-py39"] } +path_jail = { version = "0.6", features = ["guard"] } +pyo3 = { version = "0.30", features = ["extension-module", "abi3-py39"] } [package.metadata] -authors = ["Niki A. "] \ No newline at end of file +authors = ["Niki A. "] diff --git a/README.md b/README.md index 5b26ce6..3bbff9b 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ pip install path-jail ## Quick Start ```python -from path_jail import Jail, join +from path_jail import FdJail, Jail, join # One-shot validation safe_path = join("/var/uploads", "user/report.pdf") @@ -28,6 +28,14 @@ jail = Jail("/var/uploads") path1 = jail.join("2025/report.pdf") path2 = jail.join("data.csv") +# Validate independent path components without string concatenation +path3 = jail.join_segments("users", user_id, filename) + +# Open untrusted paths through a pinned directory descriptor (Unix) +guard = FdJail("/var/uploads") +with guard.open("user/report.pdf", "rb", require_regular_file=True) as file: + contents = file.read() + # These raise ValueError: jail.join("../../etc/passwd") # Path traversal jail.join("/etc/passwd") # Absolute path @@ -82,6 +90,54 @@ Join a relative path to the jail root. Returns the absolute path. safe = jail.join("subdir/file.txt") ``` +### `Jail.join_segments(*parts) -> str` + +Join separately validated path components. Empty components are skipped; +separators, `..`, and null bytes are rejected in every non-empty component. + +```python +safe = jail.join_segments("users", user_id, filename) +``` + +### `FdJail(root)` + +On Unix, `FdJail` opens files relative to a pinned jail root and returns normal +Python file objects. Linux 5.6+ on x86_64 and aarch64 uses `openat2` for atomic, +kernel-enforced resolution. macOS and other Unix platforms use an `O_NOFOLLOW` +fallback; check `capabilities().toctou_safe` when atomicity is required. + +```python +from path_jail import FdJail + +guard = FdJail("/var/uploads") + +with guard.open( + "user/report.pdf", + "rb", + require_regular_file=True, + reject_hard_links=True, +) as file: + contents = file.read() + +with guard.create("user/new.bin") as file: + file.write(b"new content") + +file, attestation = guard.open_with_attestation("user/report.pdf", "rb") +with file: + contents = file.read() +print(attestation.toctou_safe, attestation.file_inode) +``` + +`open()` supports standard `r`, `w`, `a`, and `x` modes with optional `b`, `t`, +and `+`. Policy options are `require_regular_file`, `reject_hard_links`, +`no_symlinks`, and `no_xdev`. The latter two require a backend whose matching +capability is true. + +Guarded `create_dir`, `remove_file`, `remove_dir`, and `rename` are available +when `capabilities().directory_operations` is true. Unsupported guarded +operations raise `NotImplementedError`. `FdJail` itself is unavailable on +Windows and its constructor raises `NotImplementedError` there. + ### `Jail.contains(path) -> str` Verify an existing absolute path is inside the jail. @@ -167,7 +223,7 @@ jail = Jail(UPLOAD_DIR) def save_upload(user_id: str, filename: str, data: bytes) -> str: """Safely save an uploaded file.""" # Validate and build path - safe_path = jail.join(f"{user_id}/{filename}") + safe_path = jail.join_segments(user_id, filename) # Create parent directories Path(safe_path).parent.mkdir(parents=True, exist_ok=True) @@ -276,6 +332,7 @@ ln /etc/passwd /var/uploads/innocent.txt ``` **Mitigations:** +- Use `FdJail.open(..., reject_hard_links=True)` for untrusted files - Use a separate partition for the jail (hard links cannot cross partitions) - Don't give untrusted users shell access - Use container isolation @@ -291,19 +348,13 @@ open(safe_path) # Escapes! ``` **Mitigations:** -- Open with `O_NOFOLLOW` so a symlink swapped in at the final component is - refused (intermediate directories are still unprotected): - ```python - import os - - fd = os.open(safe_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o644) - with os.fdopen(fd, "wb") as f: - f.write(data) - ``` -- Use container/chroot isolation for strong guarantees -- The Rust crate's `guard` feature makes validate-and-open a single - kernel-checked step on Linux x86_64/aarch64 with kernel 5.6+; it is not - exposed in these bindings yet. +- Use `FdJail.open()` so validation and opening are performed by the guarded + backend. On Linux 5.6+ x86_64/aarch64 this is a single kernel-checked step. +- Check `FdJail.capabilities().toctou_safe` or the returned attestation before + relying on atomic path resolution. Other Unix platforms use a fallback that + protects the final component but is not fully TOCTOU-safe. +- Use container/chroot isolation when the active backend does not meet the + threat model. #### Windows Reserved Device Names @@ -408,7 +459,8 @@ path-jail crosses the Python/Rust boundary once per call. The tight syscall loop ## Thread Safety -`Jail` instances are thread-safe and can be shared across threads without locks. +`Jail` and `FdJail` instances are thread-safe and can be shared across threads +without locks. ## Development diff --git a/pyproject.toml b/pyproject.toml index be5d5a3..7ca7d9b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "maturin" [project] name = "path-jail" -version = "0.3.0" +version = "0.4.0" description = "Secure filesystem sandbox. Restricts paths to a root directory, preventing traversal attacks." readme = "README.md" license = { text = "MIT OR Apache-2.0" } @@ -21,6 +21,7 @@ classifiers = [ "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", "Programming Language :: Rust", "Topic :: Security", "Typing :: Typed", diff --git a/python/path_jail/__init__.py b/python/path_jail/__init__.py index 33c200c..85bdd59 100644 --- a/python/path_jail/__init__.py +++ b/python/path_jail/__init__.py @@ -1,7 +1,7 @@ # Re-export from native module -from .path_jail import Jail, join +from .path_jail import Attestation, FdJail, GuardCapabilities, Jail, join -__all__ = ["Jail", "join"] +__all__ = ["Attestation", "FdJail", "GuardCapabilities", "Jail", "join"] from importlib.metadata import version as _version __version__ = _version("path-jail") diff --git a/python/path_jail/__init__.pyi b/python/path_jail/__init__.pyi index f0af071..714cb65 100644 --- a/python/path_jail/__init__.pyi +++ b/python/path_jail/__init__.pyi @@ -1,6 +1,7 @@ """Type stubs for path_jail.""" from os import PathLike +from typing import IO, Any, BinaryIO __version__: str @@ -56,6 +57,13 @@ class Jail: """ ... + def join_segments(self, *parts: _PathLike) -> str: + """Join separately validated path components beneath the jail root. + + Empty parts are skipped. Separators, ``..``, and null bytes are rejected. + """ + ... + def contains(self, path: _PathLike) -> str: """Verify an absolute path is inside the jail. @@ -90,6 +98,82 @@ class Jail: def __repr__(self) -> str: ... def __str__(self) -> str: ... +class GuardCapabilities: + """Guarantees and operations provided by the active guarded backend.""" + + @property + def toctou_safe(self) -> bool: ... + @property + def directory_operations(self) -> bool: ... + @property + def no_symlinks(self) -> bool: ... + @property + def no_xdev(self) -> bool: ... + +class Attestation: + """Metadata captured from the exact handle returned by a guarded open.""" + + @property + def jail_root(self) -> str: ... + @property + def opened_path(self) -> str: ... + @property + def root_inode(self) -> int: ... + @property + def file_inode(self) -> int: ... + @property + def device(self) -> int: ... + @property + def nlink(self) -> int: ... + @property + def toctou_safe(self) -> bool: ... + @property + def opened_at_ns(self) -> int: ... + @property + def signature(self) -> bytes | None: ... + +class FdJail: + """Descriptor-based jail for guarded file operations on Unix.""" + + def __init__(self, root: _PathLike) -> None: ... + @property + def root(self) -> str: ... + def capabilities(self) -> GuardCapabilities: ... + def open( + self, + path: _PathLike, + mode: str = "r", + *, + require_regular_file: bool = False, + reject_hard_links: bool = False, + no_symlinks: bool = False, + no_xdev: bool = False, + ) -> IO[Any]: ... + def open_with_attestation( + self, + path: _PathLike, + mode: str = "r", + *, + require_regular_file: bool = False, + reject_hard_links: bool = False, + no_symlinks: bool = False, + no_xdev: bool = False, + ) -> tuple[IO[Any], Attestation]: ... + def create( + self, + path: _PathLike, + *, + require_regular_file: bool = False, + reject_hard_links: bool = False, + no_symlinks: bool = False, + no_xdev: bool = False, + ) -> BinaryIO: ... + def create_dir(self, path: _PathLike) -> None: ... + def remove_file(self, path: _PathLike) -> None: ... + def remove_dir(self, path: _PathLike) -> None: ... + def rename(self, source: _PathLike, destination: _PathLike) -> None: ... + def __repr__(self) -> str: ... + def join(root: _PathLike, path: _PathLike) -> str: """One-shot path validation. diff --git a/src/lib.rs b/src/lib.rs index d5af38f..06d9853 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,9 +1,17 @@ #![allow(clippy::useless_conversion)] +#[cfg(unix)] +use ::path_jail::guard::{Attestation as RustAttestation, FdJail as RustFdJail, OpenOptions}; use ::path_jail::{Jail as RustJail, JailError}; -use pyo3::exceptions::{PyOSError, PyTypeError, PyValueError}; +use pyo3::exceptions::{PyNotImplementedError, PyOSError, PyTypeError, PyValueError}; use pyo3::prelude::*; -use pyo3::types::PyString; +#[cfg(unix)] +use pyo3::types::PyDict; +use pyo3::types::{PyString, PyTuple}; +#[cfg(unix)] +use std::fs::File; +#[cfg(unix)] +use std::os::fd::{FromRawFd, IntoRawFd}; use std::path::PathBuf; /// Maximum path length before we keep the \\?\ prefix on Windows. @@ -71,13 +79,13 @@ fn extract_path(obj: &Bound<'_, PyAny>) -> PyResult { } // Try str first - if let Ok(s) = obj.downcast::() { + if let Ok(s) = obj.cast::() { return validate_path(&s.to_cow()?); } // Try os.PathLike via __fspath__ if let Ok(fspath) = obj.call_method0("__fspath__") { - if let Ok(s) = fspath.downcast::() { + if let Ok(s) = fspath.cast::() { return validate_path(&s.to_cow()?); } // Could be bytes, but we only support str paths @@ -89,6 +97,19 @@ fn extract_path(obj: &Bound<'_, PyAny>) -> PyResult { Err(PyTypeError::new_err("expected str or os.PathLike object")) } +/// Extract path segments as UTF-8 strings for `Jail::join_segments`. +fn extract_segments(parts: &Bound<'_, PyTuple>) -> PyResult> { + parts + .iter() + .map(|part| { + let path = extract_path(&part)?; + path.into_os_string() + .into_string() + .map_err(|_| PyValueError::new_err("path segment is not valid Unicode")) + }) + .collect() +} + /// Convert an OS error without discarding its numeric error code. fn io_error_to_py(err: std::io::Error) -> PyErr { let message = err.to_string(); @@ -118,6 +139,13 @@ fn to_py_err(err: JailError) -> PyErr { } // Filesystem root or non-directory. (A missing root surfaces as Io.) err @ JailError::InvalidRoot { .. } => PyValueError::new_err(err.to_string()), + #[cfg(all( + target_os = "linux", + any(target_arch = "x86_64", target_arch = "aarch64") + ))] + err @ JailError::UnsupportedKernel { .. } => { + PyNotImplementedError::new_err(err.to_string()) + } JailError::Io(err) => io_error_to_py(err), // Handle future error variants from path_jail crate _ => PyValueError::new_err(format!("path_jail error: {}", err)), @@ -179,6 +207,20 @@ impl Jail { .map_err(to_py_err) } + /// Join separately supplied path components beneath the jail root. + /// + /// Each non-empty part must be one component. Separators, `..`, and null + /// bytes are rejected before the path is joined. + #[pyo3(signature = (*parts))] + fn join_segments(&self, parts: &Bound<'_, PyTuple>) -> PyResult { + let parts = extract_segments(parts)?; + self.inner + .join_segments(&parts) + .map(normalize_path) + .map(path_to_string) + .map_err(to_py_err) + } + /// Verify an absolute path is inside the jail. /// /// Args: @@ -233,6 +275,410 @@ impl Jail { } } +/// Guarantees and operations provided by the active guarded backend. +#[pyclass(name = "GuardCapabilities", frozen)] +#[derive(Clone)] +struct PyGuardCapabilities { + #[pyo3(get)] + toctou_safe: bool, + #[pyo3(get)] + directory_operations: bool, + #[pyo3(get)] + no_symlinks: bool, + #[pyo3(get)] + no_xdev: bool, +} + +/// Metadata captured from the exact file handle returned by a guarded open. +#[pyclass(name = "Attestation", frozen)] +#[derive(Clone)] +struct PyAttestation { + #[pyo3(get)] + jail_root: String, + #[pyo3(get)] + opened_path: String, + #[pyo3(get)] + root_inode: u64, + #[pyo3(get)] + file_inode: u64, + #[pyo3(get)] + device: u64, + #[pyo3(get)] + nlink: u64, + #[pyo3(get)] + toctou_safe: bool, + #[pyo3(get)] + opened_at_ns: u64, + #[pyo3(get)] + signature: Option>, +} + +#[cfg(unix)] +impl From<&RustAttestation> for PyAttestation { + fn from(value: &RustAttestation) -> Self { + let opened_at_ns = value + .opened_at + .duration_since(std::time::SystemTime::UNIX_EPOCH) + .unwrap_or_default() + .as_nanos() as u64; + Self { + jail_root: path_to_string(normalize_path(value.jail_root.clone())), + opened_path: path_to_string(value.opened_path.clone()), + root_inode: value.root_inode, + file_inode: value.file_inode, + device: value.device, + nlink: value.nlink, + toctou_safe: value.toctou_safe, + opened_at_ns, + signature: value.signature.map(|signature| signature.to_vec()), + } + } +} + +#[cfg(unix)] +#[derive(Clone, Copy)] +struct ParsedMode { + read: bool, + write: bool, + append: bool, + truncate: bool, + create: bool, + create_new: bool, +} + +#[cfg(unix)] +fn parse_mode(mode: &str) -> PyResult { + let base_modes = mode + .chars() + .filter(|character| matches!(character, 'r' | 'w' | 'a' | 'x')) + .collect::>(); + let plus_count = mode.chars().filter(|character| *character == '+').count(); + let binary_count = mode.chars().filter(|character| *character == 'b').count(); + let text_count = mode.chars().filter(|character| *character == 't').count(); + let valid_characters = mode + .chars() + .all(|character| matches!(character, 'r' | 'w' | 'a' | 'x' | 'b' | 't' | '+')); + + if !valid_characters + || base_modes.len() != 1 + || plus_count > 1 + || binary_count > 1 + || text_count > 1 + || (binary_count == 1 && text_count == 1) + { + return Err(PyValueError::new_err(format!( + "invalid file mode: '{mode}'" + ))); + } + + let update = plus_count == 1; + Ok(match base_modes[0] { + 'r' => ParsedMode { + read: true, + write: update, + append: false, + truncate: false, + create: false, + create_new: false, + }, + 'w' => ParsedMode { + read: update, + write: true, + append: false, + truncate: true, + create: true, + create_new: false, + }, + 'a' => ParsedMode { + read: update, + write: false, + append: true, + truncate: false, + create: true, + create_new: false, + }, + 'x' => ParsedMode { + read: update, + write: true, + append: false, + truncate: false, + create: false, + create_new: true, + }, + _ => unreachable!(), + }) +} + +#[cfg(unix)] +fn file_to_python(py: Python<'_>, file: File, mode: &str) -> PyResult> { + let kwargs = PyDict::new(py); + kwargs.set_item("closefd", true)?; + let raw_fd = file.into_raw_fd(); + let result = py + .import("builtins")? + .call_method("open", (raw_fd, mode), Some(&kwargs)); + match result { + Ok(file) => Ok(file.unbind()), + Err(error) => { + // Python did not accept ownership, so close the descriptor here. + drop(unsafe { File::from_raw_fd(raw_fd) }); + Err(error) + } + } +} + +#[cfg(unix)] +#[pyclass(name = "FdJail")] +struct PyFdJail { + inner: RustFdJail, +} + +#[cfg(unix)] +impl PyFdJail { + #[allow(clippy::too_many_arguments)] + fn open_guarded( + &self, + path: PathBuf, + mode: &str, + require_regular_file: bool, + reject_hard_links: bool, + no_symlinks: bool, + no_xdev: bool, + ) -> PyResult<(File, PyAttestation)> { + let parsed = parse_mode(mode)?; + let capabilities = self.inner.capabilities(); + if no_symlinks && !capabilities.no_symlinks { + return Err(PyNotImplementedError::new_err( + "no_symlinks is not supported by the active guarded backend", + )); + } + if no_xdev && !capabilities.no_xdev { + return Err(PyNotImplementedError::new_err( + "no_xdev is not supported by the active guarded backend", + )); + } + let options = OpenOptions::new() + .read(parsed.read) + .write(parsed.write) + .append(parsed.append) + .truncate(parsed.truncate) + .create(parsed.create) + .create_new(parsed.create_new) + .require_regular_file(require_regular_file) + .reject_hard_links(reject_hard_links) + .no_symlinks(no_symlinks) + .no_xdev(no_xdev); + let guarded = self.inner.open(path, options).map_err(to_py_err)?; + let attestation = PyAttestation::from(guarded.attestation()); + Ok((guarded.into_file(), attestation)) + } + + fn require_directory_operations(&self) -> PyResult<()> { + if self.inner.capabilities().directory_operations { + Ok(()) + } else { + Err(PyNotImplementedError::new_err( + "guarded directory mutations require Linux x86_64/aarch64", + )) + } + } +} + +#[cfg(unix)] +#[pymethods] +impl PyFdJail { + #[new] + fn new(root: &Bound<'_, PyAny>) -> PyResult { + let root = extract_path(root)?; + let inner = RustFdJail::new(root).map_err(to_py_err)?; + Ok(Self { inner }) + } + + #[getter] + fn root(&self) -> String { + path_to_string(normalize_path(self.inner.root().to_owned())) + } + + fn capabilities(&self) -> PyGuardCapabilities { + let capabilities = self.inner.capabilities(); + PyGuardCapabilities { + toctou_safe: capabilities.toctou_safe, + directory_operations: capabilities.directory_operations, + no_symlinks: capabilities.no_symlinks, + no_xdev: capabilities.no_xdev, + } + } + + #[pyo3(signature = (path, mode = "r", *, require_regular_file = false, reject_hard_links = false, no_symlinks = false, no_xdev = false))] + #[allow(clippy::too_many_arguments)] + fn open( + &self, + py: Python<'_>, + path: &Bound<'_, PyAny>, + mode: &str, + require_regular_file: bool, + reject_hard_links: bool, + no_symlinks: bool, + no_xdev: bool, + ) -> PyResult> { + let path = extract_path(path)?; + let (file, _) = self.open_guarded( + path, + mode, + require_regular_file, + reject_hard_links, + no_symlinks, + no_xdev, + )?; + file_to_python(py, file, mode) + } + + #[pyo3(signature = (path, mode = "r", *, require_regular_file = false, reject_hard_links = false, no_symlinks = false, no_xdev = false))] + #[allow(clippy::too_many_arguments)] + fn open_with_attestation( + &self, + py: Python<'_>, + path: &Bound<'_, PyAny>, + mode: &str, + require_regular_file: bool, + reject_hard_links: bool, + no_symlinks: bool, + no_xdev: bool, + ) -> PyResult<(Py, PyAttestation)> { + let path = extract_path(path)?; + let (file, attestation) = self.open_guarded( + path, + mode, + require_regular_file, + reject_hard_links, + no_symlinks, + no_xdev, + )?; + Ok((file_to_python(py, file, mode)?, attestation)) + } + + #[pyo3(signature = (path, *, require_regular_file = false, reject_hard_links = false, no_symlinks = false, no_xdev = false))] + fn create( + &self, + py: Python<'_>, + path: &Bound<'_, PyAny>, + require_regular_file: bool, + reject_hard_links: bool, + no_symlinks: bool, + no_xdev: bool, + ) -> PyResult> { + self.open( + py, + path, + "xb", + require_regular_file, + reject_hard_links, + no_symlinks, + no_xdev, + ) + } + + fn create_dir(&self, path: &Bound<'_, PyAny>) -> PyResult<()> { + #[cfg(all( + target_os = "linux", + any(target_arch = "x86_64", target_arch = "aarch64") + ))] + { + self.require_directory_operations()?; + let path = extract_path(path)?; + self.inner.create_dir(path).map_err(to_py_err) + } + #[cfg(not(all( + target_os = "linux", + any(target_arch = "x86_64", target_arch = "aarch64") + )))] + { + let _ = path; + self.require_directory_operations() + } + } + + fn remove_file(&self, path: &Bound<'_, PyAny>) -> PyResult<()> { + #[cfg(all( + target_os = "linux", + any(target_arch = "x86_64", target_arch = "aarch64") + ))] + { + self.require_directory_operations()?; + let path = extract_path(path)?; + self.inner.remove_file(path).map_err(to_py_err) + } + #[cfg(not(all( + target_os = "linux", + any(target_arch = "x86_64", target_arch = "aarch64") + )))] + { + let _ = path; + self.require_directory_operations() + } + } + + fn remove_dir(&self, path: &Bound<'_, PyAny>) -> PyResult<()> { + #[cfg(all( + target_os = "linux", + any(target_arch = "x86_64", target_arch = "aarch64") + ))] + { + self.require_directory_operations()?; + let path = extract_path(path)?; + self.inner.remove_dir(path).map_err(to_py_err) + } + #[cfg(not(all( + target_os = "linux", + any(target_arch = "x86_64", target_arch = "aarch64") + )))] + { + let _ = path; + self.require_directory_operations() + } + } + + fn rename(&self, source: &Bound<'_, PyAny>, destination: &Bound<'_, PyAny>) -> PyResult<()> { + #[cfg(all( + target_os = "linux", + any(target_arch = "x86_64", target_arch = "aarch64") + ))] + { + self.require_directory_operations()?; + let source = extract_path(source)?; + let destination = extract_path(destination)?; + self.inner.rename(source, destination).map_err(to_py_err) + } + #[cfg(not(all( + target_os = "linux", + any(target_arch = "x86_64", target_arch = "aarch64") + )))] + { + let _ = (source, destination); + self.require_directory_operations() + } + } + + fn __repr__(&self) -> String { + format!("FdJail('{}')", self.inner.root().display()) + } +} + +#[cfg(windows)] +#[pyclass(name = "FdJail")] +struct PyFdJail; + +#[cfg(windows)] +#[pymethods] +impl PyFdJail { + #[new] + fn new(_root: &Bound<'_, PyAny>) -> PyResult { + Err(PyNotImplementedError::new_err( + "FdJail is available on Unix platforms only", + )) + } +} + /// One-shot path validation. /// /// This is a convenience function for validating a single path. @@ -280,6 +726,9 @@ fn join(root: &Bound<'_, PyAny>, path: &Bound<'_, PyAny>) -> PyResult { #[pymodule] fn path_jail(m: &Bound<'_, PyModule>) -> PyResult<()> { m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; m.add_function(wrap_pyfunction!(join, m)?)?; Ok(()) } diff --git a/tests/test_jail.py b/tests/test_jail.py index e5a954f..b37ab8b 100644 --- a/tests/test_jail.py +++ b/tests/test_jail.py @@ -1,10 +1,11 @@ import os import sys import tempfile +from io import IOBase from pathlib import Path import pytest -from path_jail import Jail, join +from path_jail import FdJail, Jail, join # Windows extended-length path prefix WIN_PREFIX = "\\\\?\\" @@ -65,6 +66,25 @@ def test_join_pathlike(self, jail_dir): result = jail.join(Path("subdir") / "file.txt") assert paths_equal(result, os.path.join(normalize_path(jail.root), "subdir", "file.txt")) + def test_join_segments(self, jail_dir): + jail = Jail(jail_dir) + result = jail.join_segments("users", "alice", "report.pdf") + expected = os.path.join(normalize_path(jail.root), "users", "alice", "report.pdf") + assert paths_equal(result, expected) + + def test_join_segments_accepts_pathlike_and_skips_empty(self, jail_dir): + jail = Jail(jail_dir) + assert paths_equal( + jail.join_segments(Path("users"), "", "report.pdf"), + jail.join_segments("users", "report.pdf"), + ) + + @pytest.mark.parametrize("part", ["..", "users/alice", "users\\alice", "bad\x00name"]) + def test_join_segments_rejects_invalid_component(self, jail_dir, part): + jail = Jail(jail_dir) + with pytest.raises(ValueError): + jail.join_segments("safe", part) + def test_join_blocks_traversal(self, jail_dir): jail = Jail(jail_dir) with pytest.raises(ValueError, match="escapes"): @@ -401,7 +421,7 @@ def test_trailing_slash(self, jail_dir): class TestCoreBehavior: - """Behavior that comes from the path_jail 0.5 core.""" + """Behavior that comes from the path_jail 0.6 core.""" def test_non_directory_root_is_value_error(self, jail_dir): file_root = os.path.join(jail_dir, "file.txt") @@ -433,3 +453,123 @@ def test_version_matches_metadata(self): import path_jail assert path_jail.__version__ == version("path-jail") + + +class TestFdJail: + def test_windows_reports_unsupported(self, jail_dir): + if sys.platform != "win32": + pytest.skip("Windows-only behavior") + with pytest.raises(NotImplementedError, match="Unix"): + FdJail(jail_dir) + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_open_returns_normal_python_file(self, jail_dir): + Path(jail_dir, "message.txt").write_text("hello", encoding="utf-8") + jail = FdJail(jail_dir) + + with jail.open("message.txt") as file: + assert isinstance(file, IOBase) + assert file.read() == "hello" + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_binary_create_and_open(self, jail_dir): + jail = FdJail(jail_dir) + with jail.create("created.bin") as file: + file.write(b"created") + with jail.open("created.bin", "rb", require_regular_file=True) as file: + assert file.read() == b"created" + with pytest.raises(FileExistsError): + jail.create("created.bin") + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_write_append_and_update_modes(self, jail_dir): + jail = FdJail(jail_dir) + with jail.open("value.txt", "w") as file: + file.write("one") + with jail.open("value.txt", "a") as file: + file.write(" two") + with jail.open("value.txt", "r+") as file: + assert file.read() == "one two" + file.seek(0) + file.write("ONE") + assert Path(jail_dir, "value.txt").read_text(encoding="utf-8") == "ONE two" + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + @pytest.mark.parametrize("mode", ["", "rr", "rw", "rbb", "rbt", "q"]) + def test_invalid_mode_is_rejected(self, jail_dir, mode): + jail = FdJail(jail_dir) + with pytest.raises(ValueError, match="invalid file mode"): + jail.open("value.txt", mode) + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_open_with_attestation(self, jail_dir): + Path(jail_dir, "report.txt").write_text("report", encoding="utf-8") + jail = FdJail(jail_dir) + + file, attestation = jail.open_with_attestation( + "report.txt", "rb", require_regular_file=True + ) + with file: + assert file.read() == b"report" + assert attestation.opened_path == "report.txt" + assert attestation.file_inode > 0 + assert attestation.root_inode > 0 + assert attestation.nlink >= 1 + assert attestation.signature is None + assert attestation.toctou_safe == jail.capabilities().toctou_safe + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_require_regular_file_rejects_directory(self, jail_dir): + Path(jail_dir, "directory").mkdir() + jail = FdJail(jail_dir) + with pytest.raises(ValueError, match="regular"): + jail.open("directory", "rb", require_regular_file=True) + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_reject_hard_links(self, jail_dir): + original = Path(jail_dir, "original.txt") + original.write_text("linked", encoding="utf-8") + os.link(original, Path(jail_dir, "linked.txt")) + jail = FdJail(jail_dir) + + with pytest.raises(ValueError, match="hard link"): + jail.open("linked.txt", "rb", reject_hard_links=True) + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_symlink_escape_is_rejected(self, jail_dir): + outside = tempfile.NamedTemporaryFile(delete=False) + try: + outside.write(b"secret") + outside.close() + os.symlink(outside.name, Path(jail_dir, "escape")) + jail = FdJail(jail_dir) + with pytest.raises(ValueError): + jail.open("escape", "rb") + finally: + outside.close() + os.unlink(outside.name) + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_capabilities_and_directory_mutations(self, jail_dir): + jail = FdJail(jail_dir) + capabilities = jail.capabilities() + assert capabilities.toctou_safe == capabilities.directory_operations + assert capabilities.no_symlinks == capabilities.toctou_safe + assert capabilities.no_xdev == capabilities.toctou_safe + + if not capabilities.directory_operations: + with pytest.raises(NotImplementedError, match="no_symlinks"): + jail.open("missing", no_symlinks=True) + with pytest.raises(NotImplementedError, match="no_xdev"): + jail.open("missing", no_xdev=True) + with pytest.raises(NotImplementedError): + jail.create_dir("work") + return + + jail.create_dir("work") + with jail.create("work/source.txt") as file: + file.write(b"data") + jail.rename("work/source.txt", "work/destination.txt") + jail.remove_file("work/destination.txt") + jail.remove_dir("work") + assert not Path(jail_dir, "work").exists() From 8de27235a0267c6ddd12c3405606e00cd18255cb Mon Sep 17 00:00:00 2001 From: aimable100 <129232709+aimable100@users.noreply.github.com> Date: Tue, 10 Nov 2026 18:14:55 -0800 Subject: [PATCH 2/3] Fix guarded file ownership and blocking opens --- src/lib.rs | 94 +++++++++++++++++++++++++++++++++++----------- tests/test_jail.py | 66 +++++++++++++++++++++++++++++++- 2 files changed, 136 insertions(+), 24 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 06d9853..b85f997 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -11,7 +11,7 @@ use pyo3::types::{PyString, PyTuple}; #[cfg(unix)] use std::fs::File; #[cfg(unix)] -use std::os::fd::{FromRawFd, IntoRawFd}; +use std::os::fd::IntoRawFd; use std::path::PathBuf; /// Maximum path length before we keep the \\?\ prefix on Windows. @@ -338,6 +338,9 @@ impl From<&RustAttestation> for PyAttestation { #[cfg(unix)] #[derive(Clone, Copy)] struct ParsedMode { + base: char, + binary: bool, + update: bool, read: bool, write: bool, append: bool, @@ -372,8 +375,12 @@ fn parse_mode(mode: &str) -> PyResult { } let update = plus_count == 1; + let binary = binary_count == 1; Ok(match base_modes[0] { 'r' => ParsedMode { + base: 'r', + binary, + update, read: true, write: update, append: false, @@ -382,6 +389,9 @@ fn parse_mode(mode: &str) -> PyResult { create_new: false, }, 'w' => ParsedMode { + base: 'w', + binary, + update, read: update, write: true, append: false, @@ -390,6 +400,9 @@ fn parse_mode(mode: &str) -> PyResult { create_new: false, }, 'a' => ParsedMode { + base: 'a', + binary, + update, read: update, write: false, append: true, @@ -398,6 +411,9 @@ fn parse_mode(mode: &str) -> PyResult { create_new: false, }, 'x' => ParsedMode { + base: 'x', + binary, + update, read: update, write: true, append: false, @@ -410,20 +426,42 @@ fn parse_mode(mode: &str) -> PyResult { } #[cfg(unix)] -fn file_to_python(py: Python<'_>, file: File, mode: &str) -> PyResult> { +fn file_to_python( + py: Python<'_>, + file: File, + mode: ParsedMode, + requested_mode: &str, +) -> PyResult> { + let io = py.import("io")?; + let file_io = io.getattr("FileIO")?; + let buffered_type = if mode.update { + io.getattr("BufferedRandom")? + } else if mode.read { + io.getattr("BufferedReader")? + } else { + io.getattr("BufferedWriter")? + }; + let text_io_wrapper = if mode.binary { + None + } else { + Some(io.getattr("TextIOWrapper")?) + }; let kwargs = PyDict::new(py); kwargs.set_item("closefd", true)?; + + let raw_mode = format!("{}b{}", mode.base, if mode.update { "+" } else { "" }); let raw_fd = file.into_raw_fd(); - let result = py - .import("builtins")? - .call_method("open", (raw_fd, mode), Some(&kwargs)); - match result { - Ok(file) => Ok(file.unbind()), - Err(error) => { - // Python did not accept ownership, so close the descriptor here. - drop(unsafe { File::from_raw_fd(raw_fd) }); - Err(error) + // FileIO is the single ownership handoff. If a buffered or text wrapper + // fails, dropping `raw` closes the descriptor exactly once. + let raw = file_io.call((raw_fd, raw_mode), Some(&kwargs))?; + let buffered = buffered_type.call1((raw,))?; + match text_io_wrapper { + Some(wrapper) => { + let text = wrapper.call1((buffered,))?; + text.setattr("mode", requested_mode)?; + Ok(text.unbind()) } + None => Ok(buffered.unbind()), } } @@ -436,15 +474,14 @@ struct PyFdJail { #[cfg(unix)] impl PyFdJail { #[allow(clippy::too_many_arguments)] - fn open_guarded( + fn options( &self, - path: PathBuf, mode: &str, require_regular_file: bool, reject_hard_links: bool, no_symlinks: bool, no_xdev: bool, - ) -> PyResult<(File, PyAttestation)> { + ) -> PyResult<(ParsedMode, OpenOptions)> { let parsed = parse_mode(mode)?; let capabilities = self.inner.capabilities(); if no_symlinks && !capabilities.no_symlinks { @@ -468,7 +505,15 @@ impl PyFdJail { .reject_hard_links(reject_hard_links) .no_symlinks(no_symlinks) .no_xdev(no_xdev); - let guarded = self.inner.open(path, options).map_err(to_py_err)?; + Ok((parsed, options)) + } + + fn open_guarded( + &self, + path: PathBuf, + options: OpenOptions, + ) -> Result<(File, PyAttestation), JailError> { + let guarded = self.inner.open(path, options)?; let attestation = PyAttestation::from(guarded.attestation()); Ok((guarded.into_file(), attestation)) } @@ -522,15 +567,17 @@ impl PyFdJail { no_xdev: bool, ) -> PyResult> { let path = extract_path(path)?; - let (file, _) = self.open_guarded( - path, + let (parsed, options) = self.options( mode, require_regular_file, reject_hard_links, no_symlinks, no_xdev, )?; - file_to_python(py, file, mode) + let (file, _) = py + .detach(|| self.open_guarded(path, options)) + .map_err(to_py_err)?; + file_to_python(py, file, parsed, mode) } #[pyo3(signature = (path, mode = "r", *, require_regular_file = false, reject_hard_links = false, no_symlinks = false, no_xdev = false))] @@ -546,15 +593,17 @@ impl PyFdJail { no_xdev: bool, ) -> PyResult<(Py, PyAttestation)> { let path = extract_path(path)?; - let (file, attestation) = self.open_guarded( - path, + let (parsed, options) = self.options( mode, require_regular_file, reject_hard_links, no_symlinks, no_xdev, )?; - Ok((file_to_python(py, file, mode)?, attestation)) + let (file, attestation) = py + .detach(|| self.open_guarded(path, options)) + .map_err(to_py_err)?; + Ok((file_to_python(py, file, parsed, mode)?, attestation)) } #[pyo3(signature = (path, *, require_regular_file = false, reject_hard_links = false, no_symlinks = false, no_xdev = false))] @@ -672,7 +721,8 @@ struct PyFdJail; #[pymethods] impl PyFdJail { #[new] - fn new(_root: &Bound<'_, PyAny>) -> PyResult { + fn new(root: &Bound<'_, PyAny>) -> PyResult { + let _ = root; Err(PyNotImplementedError::new_err( "FdJail is available on Unix platforms only", )) diff --git a/tests/test_jail.py b/tests/test_jail.py index b37ab8b..9775727 100644 --- a/tests/test_jail.py +++ b/tests/test_jail.py @@ -1,7 +1,9 @@ +import gc import os +import subprocess import sys import tempfile -from io import IOBase +from io import IOBase, UnsupportedOperation from pathlib import Path import pytest @@ -460,7 +462,7 @@ def test_windows_reports_unsupported(self, jail_dir): if sys.platform != "win32": pytest.skip("Windows-only behavior") with pytest.raises(NotImplementedError, match="Unix"): - FdJail(jail_dir) + FdJail(root=jail_dir) @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") def test_open_returns_normal_python_file(self, jail_dir): @@ -485,6 +487,7 @@ def test_binary_create_and_open(self, jail_dir): def test_write_append_and_update_modes(self, jail_dir): jail = FdJail(jail_dir) with jail.open("value.txt", "w") as file: + assert file.mode == "w" file.write("one") with jail.open("value.txt", "a") as file: file.write(" two") @@ -501,6 +504,53 @@ def test_invalid_mode_is_rejected(self, jail_dir, mode): with pytest.raises(ValueError, match="invalid file mode"): jail.open("value.txt", mode) + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_non_seekable_wrapper_failure_closes_descriptor_once(self, jail_dir): + os.mkfifo(Path(jail_dir, "pipe")) + jail = FdJail(jail_dir) + before = len(os.listdir("/dev/fd")) + + for _ in range(20): + with pytest.raises(UnsupportedOperation): + jail.open("pipe", "r+") + + gc.collect() + assert len(os.listdir("/dev/fd")) <= before + + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_blocking_open_releases_gil(self, jail_dir): + script = """ +import os +import sys +import threading +import time +from path_jail import FdJail + +root = sys.argv[1] +fifo = os.path.join(root, "blocking-pipe") +os.mkfifo(fifo) +jail = FdJail(root) + +def write_later(): + time.sleep(0.1) + fd = os.open(fifo, os.O_WRONLY) + try: + os.write(fd, b"ready") + finally: + os.close(fd) + +writer = threading.Thread(target=write_later) +writer.start() +with jail.open("blocking-pipe", "rb") as file: + assert file.read() == b"ready" +writer.join() +""" + subprocess.run( + [sys.executable, "-c", script, jail_dir], + check=True, + timeout=5, + ) + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") def test_open_with_attestation(self, jail_dir): Path(jail_dir, "report.txt").write_text("report", encoding="utf-8") @@ -549,6 +599,18 @@ def test_symlink_escape_is_rejected(self, jail_dir): outside.close() os.unlink(outside.name) + @pytest.mark.skipif(sys.platform != "linux", reason="no_symlinks requires Linux") + def test_no_symlinks_rejects_internal_symlink(self, jail_dir): + Path(jail_dir, "target.txt").write_text("inside", encoding="utf-8") + os.symlink("target.txt", Path(jail_dir, "link.txt")) + jail = FdJail(jail_dir) + assert jail.capabilities().no_symlinks + + with jail.open("link.txt") as file: + assert file.read() == "inside" + with pytest.raises(ValueError): + jail.open("link.txt", no_symlinks=True) + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") def test_capabilities_and_directory_mutations(self, jail_dir): jail = FdJail(jail_dir) From d7a9e924cc2509973e6eb988eed57493d65d2e76 Mon Sep 17 00:00:00 2001 From: aimable100 <129232709+aimable100@users.noreply.github.com> Date: Wed, 11 Nov 2026 09:29:16 -0800 Subject: [PATCH 3/3] Close descriptors on Python file initialization errors --- src/lib.rs | 12 ++++++++---- tests/test_jail.py | 15 +++++++++++++++ 2 files changed, 23 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index b85f997..5c83030 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -11,7 +11,7 @@ use pyo3::types::{PyString, PyTuple}; #[cfg(unix)] use std::fs::File; #[cfg(unix)] -use std::os::fd::IntoRawFd; +use std::os::fd::{AsRawFd, IntoRawFd}; use std::path::PathBuf; /// Maximum path length before we keep the \\?\ prefix on Windows. @@ -450,10 +450,14 @@ fn file_to_python( kwargs.set_item("closefd", true)?; let raw_mode = format!("{}b{}", mode.base, if mode.update { "+" } else { "" }); - let raw_fd = file.into_raw_fd(); - // FileIO is the single ownership handoff. If a buffered or text wrapper - // fails, dropping `raw` closes the descriptor exactly once. + let raw_fd = file.as_raw_fd(); + // Rust retains ownership until FileIO initializes successfully. FileIO + // does not adopt an existing descriptor when initialization fails (for + // example, for a directory), so `file` closes that failure path. After a + // successful call, forgetting the Rust File leaves FileIO as sole owner. let raw = file_io.call((raw_fd, raw_mode), Some(&kwargs))?; + let _ = file.into_raw_fd(); + // If a buffered or text wrapper fails, dropping `raw` closes exactly once. let buffered = buffered_type.call1((raw,))?; match text_io_wrapper { Some(wrapper) => { diff --git a/tests/test_jail.py b/tests/test_jail.py index 9775727..bee1cca 100644 --- a/tests/test_jail.py +++ b/tests/test_jail.py @@ -517,6 +517,21 @@ def test_non_seekable_wrapper_failure_closes_descriptor_once(self, jail_dir): gc.collect() assert len(os.listdir("/dev/fd")) <= before + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") + def test_directory_wrapper_failure_closes_descriptor_once(self, jail_dir): + Path(jail_dir, "directory").mkdir() + jail = FdJail(jail_dir) + before = len(os.listdir("/dev/fd")) + + for _ in range(20): + with pytest.raises(IsADirectoryError): + jail.open("directory", "rb") + with pytest.raises(IsADirectoryError): + jail.open_with_attestation("directory", "rb") + + gc.collect() + assert len(os.listdir("/dev/fd")) <= before + @pytest.mark.skipif(sys.platform == "win32", reason="FdJail is Unix-only") def test_blocking_open_releases_gil(self, jail_dir): script = """