Tox-dev Filelock: Time-of-check Time-of-use (TOCTOU) Race Condition (CVE-2026-112935)

The stale-lock break shared by SoftFileLock, MarkerSoftFileLock and SoftFileLease (and their async variants, and a FileLock that has fallen back to a soft lock on ENOSYS, the "not implemented" error) recognises the marker it judged stale by two values. The marker is the lock file at <path>, whose presence says a process holds the lock. The values are its inode number (the kernel's identity for a file, independent of its name) and its modification time (mtime) not being newer. The check runs after the contender has already closed the marker, so nothing keeps the inode allocated.

On a filesystem that hands a freed inode number straight to the next file (ext4, xfs, overlayfs on them) the next holder's marker can carry that number. A contender still between its read and its break then renames and unlinks the live marker. Another local user (the other user below) who can create files in the lock's directory, a sticky /tmp included (the sticky bit is a directory flag that lets only a file's owner remove it), forces this at will. It plants a marker with a stale owner record and a modification time in the future and unlinks it as soon as a contender has read it. Two processes of the user running the lock (the lock user below) then hold the same default-configured lock at once, and nothing raises or logs. Affected versions: filelock >= 3.22.0 and <= 4.2.0 (finding ANT-2026-KIIS96IX).

Severity

CVSS:3.1/AV:L/AC:H/PR:L/UI:N/S:U/C:N/I:H/A:N, 4.7 (Medium).

AV:L (local): the other user needs an account on the same host. AC:H (high attack complexity): a race, though one the other user starts, lengthens (by making the lock user's /proc read slow) and retries at every release. The scanner measured 10 to 26 overlaps per 20-second run. PR:L (low privileges): an unprivileged account is enough. UI:N (no user interaction): the lock user's processes act on their own. C:N (no confidentiality impact): the other user reads nothing. I:H (high integrity impact): two holders write the data the lock protects, and neither learns of the other. A:N (no availability impact): the lock keeps working.

Classification from the review: security, conditional on a sticky shared directory, ext4-style inode reuse and at least two contenders of the lock user. Our review verified it across UIDs (a UID is a user account's numeric id): the other user as uid 1001, the lock user's processes as uid 1000, BUG on 4.2.0 over ext4. The scanner rated it high (CWE-367).

Scope and preconditions

• The other user can create files in the lock's directory; a root-owned 1777 directory such as /tmp or /var/tmp is enough. It creates, utimes (sets the timestamps of) and unlinks only its own file. The sticky bit stops it removing the lock user's marker (checked: EPERM, operation not permitted), so the lock user's own stale break does the deletion.
• The directory is on a filesystem that hands a freed inode number straight to the next file. ext4 does (six create/unlink rounds returned one number six times, in the image's overlayfs /tmp and on a loop-mounted ext4), and xfs does. tmpfs returned six increasing numbers and the same run there gave no overlap, and btrfs does not hand a freed number back.
• The lock user has at least two processes contending for the lock, and the displaced holder is still inside when the next contender polls (the breaker itself comes back one poll_interval, 50 ms by default, later).
• The lock is SoftFileLock, MarkerSoftFileLock or SoftFileLease (or async forms). The default flock-based FileLock joins them only after it has fallen back to SoftFileLock on ENOSYS. StrictSoftFileLock does not call break_lock_file, so it is not affected.
• The same overlap also occurs with no other user involved, under heavy same-account contention, when a contender breaks a dead holder's marker and a successor creates its marker within the same timestamp tick (about once in 750 crashes with 64 workers on a 2-CPU machine, not on tmpfs).

filelock's checks against another local user hold only when no other user can replace the lock's directory or any of its ancestors. That is the case when each ancestor belongs to the lock user or root and is either not writable by others or sticky. A user who can rename entries in a non-sticky directory above the lock controls every name below it. No file-based lock can defend against that.

Affected code

At the scanned commit b831496, the re-check sits in break_lock_file. Its callers are SoftFileLock._try_break_stale_lock, MarkerSoftFileLock._try_break_stale_lock and SoftFileLease._try_break_stale_lock. The reader _read_lock_file closes the judged marker before the verdict.

Introduced

e35c3afac473 ("feat(soft): detect and break stale locks", #476, 2026-02-13), first released in 3.22.0 (verified against the tags). Every release since, up to 4.2.0, carries the check.

Mechanism

_try_break_stale_lock reads the marker through _read_lock_file (lstat, O_RDONLY | O_NONBLOCK | O_NOFOLLOW open, fstat, read, close), decides with owner_is_stale that the owner is gone, and calls break_lock_file(lock_file, mtime, ino):

# src/filelock/_util.py:113-118
if (current := os.lstat(lock_file)).st_mtime > mtime_before or current.st_ino != ino_before:
    return
break_path: Final[str] = f"{lock_file}.break.{os.getpid()}.{secrets.token_hex(16)}"
Path(lock_file).rename(break_path)
if (st_after := os.lstat(break_path)).st_mtime <= mtime_before and st_after.st_ino == ino_before:
    Path(break_path).unlink()

Between the close in _read_lock_file and the lstat on line 113 nothing keeps the inode allocated. An inode number identifies a file only while something holds that inode. The release path already says so ("Our open descriptor keeps the inode allocated, so its number cannot name a successor's marker yet"); the break path does not. That leaves the modification time, which the file's owner sets to any value and which the code compares by order. With two jobs A and B of the lock user and the other user:

1. The other user creates app.lock (inode I) with the record <its own pid>\n<host>\n1\n and sets its time to the year 2100 with os.utime(). A live PID with a wrong start token (the value that identifies one incarnation of a PID) is a recycled PID, so every contender judges the owner stale. On its own this marker only makes the lock user's processes wait: they cannot rename another user's file in a sticky directory (EPERM, and acquire(timeout=1) raises Timeout).
2. A polls, reads (record, mtime=2100, ino=I), closes the file and enters owner_is_stale().
3. The other user unlinks its marker. Inode I is free.
4. B polls. The path is empty, so O_EXCL (create only if absent) succeeds and ext4 gives the new marker inode number I. B holds the lock.
5. A reaches line 113 and looks at B's marker: its time (now) is not newer than 2100 and its inode number is I. A renames it (it is the lock user's own file, so the sticky bit does not object), line 117 passes for the same reason, and line 118 unlinks the live marker.
6. The path is empty again while B is still inside. The next contender to poll, A included, creates its marker and holds the lock as well.

When B releases, _unlink_open_marker finds another file at the path and leaves it alone, so neither side raises or logs a