filelock: SoftFileLock stale-break restore follows a swapped-in symbolic link and hard-links a file of the user running the lock into the lock directory

When a soft-lock stale break finds that the marker (the lock file at <path>) it renamed aside was a live one recreated by a successor, the restore branch of break_lock_file() checks the break name with lstat (a check that reads a name without following a symbolic link) and then calls os.link(break_path, lock_file) by name. On CPython 3.12 and later on Linux (and on macOS) that call follows a symbolic link (a file that redirects to another path). A local user (the other user below) who can write a shared lock directory without the sticky bit (a directory flag that lets only a file's owner rename or remove it) replaces the break name with a symbolic link between those two calls.

The SoftFileLock, MarkerSoftFileLock, SoftFileLease or lifetime break of the user running the lock (the lock user below) then creates a hard link (a second name for the same file), in that directory, to any of the lock user's own files on the same filesystem. That includes files inside directories the other user cannot enter and links that fs.protected_hardlinks (a Linux setting that forbids hard links to files one does not own) refuses the other user when it asks itself. The link exposes the file's size, times, mode and owner, keeps the inode (the kernel's identity for a file, independent of its name) alive, and gives the other user a name it can move. On 4.2.0 a later FileLock of the lock user on that name truncated the file. Affected versions: filelock >= 4.1.0 and <= 4.2.0 (finding ANT-2026-SB29HIAL).

Severity

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

AV:L (local): the other user needs an account on the same host. AC:H (high attack complexity): two short races against a few lines of Python, timed by inotify (a Linux facility that reports file events), and the lock user must take the lock again and again (the scanner won 10 runs out of 10 after 9 to 910 lock cycles). PR:L (low privileges): an unprivileged account is enough. UI:N (no user interaction): the lock user's process acts on its own. C:L (low confidentiality impact): the file's metadata through the new name, not its content. I:H (high integrity impact): the other user chooses the file, and whatever the lock user later does to names in that directory lands on it. On 4.2.0 the lock user's own FileLock truncated the 17-byte private file to 0 bytes and, with a permissive mode, would have changed its mode too. A:N (no availability impact): the lock keeps working.

Classification from the review: security, conditional on a shared parent without the sticky bit, which crosses the protected-directory boundary. The scanner rated it high (CWE-363). This is an earlier-public-context finding. #786 added the restore branch and guarded a symbolic link already present when lstat runs, not one swapped in after it.

Scope and preconditions

• The other user can write the lock directory, and it has no sticky bit: a 0777 or group-writable cache or project directory. In a root-owned 1777 directory the unprivileged lock user cannot rename the other user's marker and only waits. In a 1777 directory the lock user owns, fs.protected_symlinks=1 (a Linux setting that refuses to follow another user's symbolic link in a world-writable sticky directory) makes the link fail with EACCES (permission denied). Testing showed no effect in sticky directories.
• The interpreter's os.link follows symbolic links. CPython 3.14 on Linux issues linkat(..., AT_SYMLINK_FOLLOW). CPython 3.11 issues link(2), which links the symbolic link itself, and is not affected. The scanner did not test 3.12 and 3.13. On macOS link(2) follows (confirmed in our review on macOS 27.0.1: a plain os.link of a symbolic link gave the target st_nlink 2, that is two names).
• The target file and the lock directory are on the same filesystem (hard links cannot cross filesystems), and the lock user takes the lock more than once.
• Every soft-lock path reaches the branch: SoftFileLock, MarkerSoftFileLock, and the break. The native does not, but it is the consumer that turns the planted link into a truncation.

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, which no file-based lock can defend against. This finding is about what the lock itself adds inside such a directory, a hard link the other user cannot make on its own.

Affected code

At the scanned commit b831496, the restore branch of break_lock_file runs for SoftFileLock._try_break_stale_lock, MarkerSoftFileLock, SoftFileLease and the lifetime break. The truncation in UnixFileLock._finalize_locked_fd is what a later native lock on the planted name did to the file (reported in its own advisory).

Introduced

fc73fc51e137 ("fix(soft): restore a live marker a stale break moved aside", #786, 2026-10-08), first released in 4.1.0 (verified against the tags). Releases before 4.1.0 have no restore branch, so this does not affect them.

Mechanism

# src/filelock/_util.py:115-122
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()
elif stat.S_ISREG(st_after.st_mode) and _HAS_LINK:  # pragma: needs hard-link
    with suppress(FileExistsError):
        os.link(break_path, lock_file)
        Path(break_path).unlink()

The S_ISREG test (is it a regular file) is about what lstat saw on line 117, not about what link resolves on line 121. The docstring says the code must not put a symbolic link back "because link would follow a symlink to its target", and the test at the scanned commit names the consequence ("publish the victim file's inode at the lock path"), but that test only covers a symbolic link that is already there when lstat runs. The 128-bit token stops others from guessing the break name, not from reading it. The name is in the directory listing from the moment the rename has happened. The package's other links pass follow_symlinks=False where the runtime honours it; this one does not. An strace (a tool that logs a process's system calls) on CPython 3.14.8 shows os.link(a, b) as linkat(AT_FDCWD, a, AT_FDCWD, b, AT_SYMLINK_FOLLOW).

The other user plays both the stale holder and the "successor" the branch exists for:

1. The other user leaves a genuine marker of a dead process at the lock path (a forked child takes the lock and _exits). The lock user's _try_break_stale_lock() reads it and owner_is_stale() agrees, so break_lock_file() renames it to app.lock.break.<pid>.<token>. In a directory without the sticky bit the lock user may rename a file it does not own.
2. The other user still owns that file and gives it a newer mtime (modification time) after the lstat on line 113. Line 117 then takes it for a recreated marker, and line 119 sees a regular file.