Eliminating TOCTOU Path Traversal in Python with Kernel-Enforced Containment and Lean 4 Formal Verification

Description and use

PathFence removes TOCTOU path traversal in Python by pinning root directories with kernel‑level checks and formal verification in Lean 4.

Problem

Python applications that validate paths with string checks are vulnerable to TOCTOU race conditions, allowing attackers to replace directories with symlinks and access unintended files.

Outcome

PathFence eliminates TOCTOU path traversal without C extensions, providing zero‑dependency pure‑Python containment verified by 15 Lean 4 theorems and supported on Linux, macOS, BSD, and Windows.

Workflow

• 1. Create a Workspace or call pathfence.safe_open with a root directory.
• 2. PathFence normalizes the requested path and verifies containment using kernel flags or step‑by‑step O_NOFOLLOW walks.
• 3. If the path is allowed, PathFence returns a verified file descriptor; otherwise it denies or rejects with a reason.
• 4. The application uses the returned descriptor to read/write files safely.

Evidence

PathFence is a zero‑dependency, pure‑Python path containment library backed by OS kernel primitives and mathematically verified in Lean 4.

Source

The decision is lexical. It looks only at the path string, never at the file system.

Source

PathFence invokes the openat2(2) syscall directly via ctypes with four strict resolution flags: RESOLVE_BENEATH, RESOLVE_NO_SYMLINKS, RESOLVE_NO_MAGICLINKS, RESOLVE_NO_XDEV.

Source

We model path components, depth tracking, lexical normalization, and step‑by‑step directory resolution, proving 15 theorems with zero sorry placeholders and zero custom axioms.

Source