GHSA-m462-7rxw-wvpg: Medium severity pip/filelock vulnerability

StrictSoftFileLock and AsyncStrictSoftFileLock check <path>.filelock (the coordination directory that holds the lock's state) with one lstat call on its name. lstat reports what a name is without following a symbolic link (a file that redirects to another path). After that check, the code reaches <path>.filelock/claims by pathname for every later operation (mkdir, scan, publish, link, unlink). opendirectory passes ONOFOLLOW (a flag that makes an open fail when the final name is a symbolic link), but the flag covers only the final claims component. The kernel follows a symbolic link in any earlier component.

Another local user (the other user below) who can rename <path>.filelock exchanges it for a symbolic link after the check. In a shared directory without the sticky bit (a directory flag that lets only a file's owner rename or remove it), any user with write access can do this. Where the shared directory is sticky, such as /tmp, only the user who created <path>.filelock before the user running the lock (the lock user below) first used it can. The lock user's process (root's, if root takes the lock) then creates a claims directory and claim files (the files whose presence says a process wants or holds the lock) inside a directory the other user chooses but only the lock user can write.

When the link points at another strict lock's .filelock directory, the stranded claims make that lock time out for every process until an operator finds and force-breaks each one. The claims property and forcebreak() resolve the same path with no check at all. Affected versions: filelock >= 3.30.0 and <= 4.2.0 (finding ANT-2026-SVFEYX89).

Severity

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

AV:L (local): the other user needs an account on the same host. AC:H (high attack complexity): the swap must land between the lstat and the next mkdir. The other user does not aim at that window. It flips the name in a loop with renameat2(RENAMEEXCHANGE) (a system call that swaps two names in one step) across repeated acquires, and won after 1 to 31 runs of the lock user's program in the scanner's trials. A sticky directory also requires it to have created <path>.filelock first. 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): through claims, one file name per planted link from a directory only the lock user can list. I:L (low integrity impact): a directory named claims and files with filelock's fixed claim names and contents appear, created with the lock user's privileges, in a directory the other user chooses but cannot write. The process overwrites or truncates nothing that exists. A:H (high availability impact): aimed at another strict lock of the lock user, the stranded claims deny that lock to every process until an operator finds and force-breaks each one. Classification from the review: security, conditional on the other user being able to rename the intermediate component. The scanner rated it high (CWE-363).

Scope and preconditions

- The other user can rename <path>.filelock. In a writable directory without the sticky bit (a 0777 or group-writable project or cache directory), any user with write permission on the directory can, even though the lock user created and owns <path>.filelock. In a sticky directory such as /tmp, only the user who created <path>.filelock before the lock user's first use can, because that user then owns both the directory and the symbolic link (the planting precondition of GHSA-9c4x-gm8v-wgc4). - The link's target is a directory the lock user can write. The effect that matters is on that directory. An acquire that completes through the link also holds the shared lock with its claims elsewhere, but a user who can rename <path>.filelock can defeat that lock's exclusion anyway. - fs.protectedsymlinks=1 (a Linux setting that refuses to follow another user's symbolic link in a world-writable sticky directory) does not interfere. The link is an intermediate path component, not the last one. In the sticky-directory case it also sits in a directory the other user owns. - Missed attempts show up to the lock user as SoftFileLockProtocolError or FileNotFoundError. The swap therefore works against a lock that a program takes more than once: a periodic job, a worker pool, or a caller that retries or waits with a timeout (each poll of a waiting acquisition is a new attempt). - The two entry points that need no race (claims and forcebreak() on a resting symbolic link) depend on the lock user inspecting or recovering the lock. The planted link invites this by making acquire() fail with a protocol error. The forcebreak() variant works only when the lock user breaks claims that name a live process on its own host without checking them first, as the recovery loop in docs/tutorials.rst does. docs/how-to.rst tells the operator to verify that the named owner is gone before breaking. - Platform: POSIX, demonstrated on Linux (tmpfs and overlayfs). Windows has no dirfd (file operations relative to an open directory handle), and on Windows the documented requirement is a lock directory that untrusted users cannot write.

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 check and the first use are adjacent lines of StrictSoftFileLock.acquire. There, ensureprotocoldirectory runs lstat on <path>.filelock and then mkdir on <path>.filelock/claims. opendirectory passes ODIRECTORY | ONOFOLLOW but receives the full <path>.filelock/claims. The claim scan goes by pathname in readexistingclaims (directory.exists()) and listclaimnames (os.scandir(directory)). So do publishrecord, linknoreplace, unlinkindirectory and the clock probe in filesystemnow. The claims property and forcebreak() take the directory from claimdirectory by string concatenation, and requireexactname confirms the name with a by-name os.scandir.

Introduced

The by-name claim directory came with 650c17c79c54 ("feat(strict): replace shared markers with owner claims", #659, 2026-07-14), first released in 3.30.0. One effect is newer. The clock-probe files that a swap at claims leaves behind need filesystemnow, added in 508d0548538f ("fix(strict): age private records by the filesystem clock", #792, 2026-10-07), first released in 4.1.0. Before that commit a claim scan created nothing. We checked both against the git tags.

Mechanism

On the benign path, ensureprotocoldirectory(coordinationdirectory) finds <path>.filelock to be a real directory, and ensureprotocoldirectory(claimdirectory) finds claims inside it. The doorway (the acquire step that scans existing claims and publishes the caller's own) then publishes into it. A symbolic link resting at <path>.filelock stops at the first call with "is not a real directory". That answer describes the name at that instant only; nothing carries it forward. With the name exchanged for a link to a directory T between the two calls:

- The second call runs mkdir("<path>.filelock/claims"), which creates T/claims with the lock user's credentials. The mkdir succeeds, so ensureprotocoldirectory returns without looking at anything. - attemptdoorway then works in T/claims for as long as the name still points there. readexistingclaims uses directory.exists() and os.scandir(directory). publishrecord opens the claim directory by its full path and creates .intent-v1-<token>.claim.private-v1-<hex>.tmp and intent-v1-<token>.claim (the intent claim, which announces a pending acquire) in it. When its intent wins the scan, linknoreplace adds held-v1-<token>.claim (the held claim, which marks the lock as taken). opendirectory does pass ODIRECTORY | ONOFOLLOW, but on "<path>.filelock/claims", so the flag covers claims only. - Cleanup resolves the name again. unlinkindirectory opens <path>.filelock/claims by path. When the name is back at the real directory by then, the unlink gets ENOENT (the "no such file" error), which unlinkownerpathresult counts as removed. The claim file stays in T/claims.

When T/claims already exists, the mkdir takes the FileExistsError branch, lstat sees a real directory, and the same scan and publication run on the existing directory. With T/claims holding a file secret-name.txt and an old .held-v1-<hex>.claim.private-v1-<hex>.tmp, the lock user's process raises SoftFileLockProtocolError: … claim 'secret-name.txt': unknown claim name or protocol version. reclaimprivaterecord unlinks the private-record file. intent-.claim files and a clock-probe file from filesystemnow stay behind.

The window is a few lines of Python between two system calls, but the other user does not aim at it. renameat2 with RENAMEEXCHANGE flips the name in a loop, so each system call of the lock user sees the directory or the link more or less at random. An attempt that sees the link at the lstat raises SoftFileLockProtocolError. One that sees the directory there and the link at the next mkdir is a hit. Four other ways reach the same by-name resolution. The scanner observed each of them at the same commit, with victim and attacker as separate accounts and default lock options.

The first way strands claims in another strict lock. With the swapped-in link pointing at the coordination directory of a second lock of the lock user (/home/victim/private/db.lock.filelock, parent mode 0700), 200 acquires of the shared lock left 7 to 17 well-formed intent-v1-.claim and held-v1-.claim files in the second lock's claims. No process holds that lock, yet StrictSoftFileLock("/home/victim/private/db.lock", timeout=1) raises Timeout from then on, until an operator force-breaks each stranded claim.

The second way swaps one component lower, at claims. The claim scan does not use a descriptor (an open handle that stays bound to one directory whatever its name later points to). os.scandir(directory), the record reads, reclaimprivaterecord (called with its descriptor slot set to None) and the clock probe in filesystemnow (os.open(directory / name, OCREAT | OEXCL | ONOFOLLOW) followed by probe.unlink()) all go by pathname. For a sticky directory, the other user needs to have created <path>.filelock first. It then puts a real claims directory (mode 1777) in it with one empty file named .held-v1-<32 zeros>.claim.private-v1-<32 zeros>.tmp, so that every scan calls the probe, and exchanges claims with a link in a loop.

After 200 acquires by the lock user, 14 to 42 one-byte, mode 0600, lock-user-owned files named .held-v1-<hex>.claim.private-v1-<hex>.tmp are in the 0700 directory the link points to. The probe open went through the link, and the pathname unlink ran after claims was a directory again and got ENOENT. A swap at this level does not affect publication or release, because there opendirectory's ONOFOLLOW does cover claims.

The third way is claims with no race. The property calls readexistingclaims on an instance that did not go through acquire, and directory.exists() and os.scandir(directory) both follow a link. After the other user runs mkdir /tmp/work.lock.filelock; ln -s /home/victim/private /tmp/work.lock.filelock/claims, acquire() refuses with "is not a real directory". The inspection loop from docs/how-to.rst (for claim in lock.claims: ...) raises SoftFileLockProtocolError: … claim 'customer-1123f274.db': unknown claim name or protocol version. That names the first non-hidden entry, in sort order, of a directory the other user cannot list. A missing or empty target returns (), a non-directory gives "Not a directory" and an unreadable directory "Permission denied", so the call also tells those apart.

The fourth way is forcebreak() with no race. It confirms the name with a by-name os.scandir in requireexactname and unlinks through unlinkindirectory, where ONOFOLLOW again covers claims only. After the other user's one command ln -s /home/victim/private/db.lock.filelock /tmp/service.lock.filelock, the recovery loop from docs/tutorials.rst run by the lock user on /tmp/service.lock (for claim in stale.claims: stale.forcebreak(claim.name)) lists and removes the held and intent claims of the live holder of /home/victim/private/db.lock. A second process then acquires that lock while the first is still in its critical section with islocked == True. The first holder's release() later finds its claims gone, counts ENOENT as removed and returns without error. Only a directory named claims below the link's target is reachable, so the targets are other strict locks, not arbitrary files.

Reproduction

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

repro

python #!/usr/bin/env python3 import collections import os import pwd import shutil import stat import subprocess import sys

asvictim = {"user": "victim", "group": "victim", "extragroups": []} asattacker = {"user": "attacker", "group": "attacker", "extragroups": []} victimjob = [sys.executable, "/tmp/repro.d/victimjob.py"] attackerswaploop = [sys.executable, "/tmp/repro.d/attackerswaploop.py"] victimuid = pwd.getpwnam("victim").pwuid

set up: a directory both users can write (0777, no sticky bit) and one only the victim can write. The shared one is on tmpfs to keep the attacker's rename loop off the container's disk. shared = "/dev/shm/filelock-repro-shared" private = "/tmp/filelock-repro-private" shutil.rmtree(shared, ignoreerrors=True) shutil.rmtree(private, ignoreerrors=True) os.mkdir(shared) os.chmod(shared, 0o777) os.mkdir(private, 0o700) shutil.chown(private, "victim", "victim")

ownmkdir = subprocess.run(["mkdir", f"{private}/claims"], captureoutput=True, text=True, asattacker) print(f"CONTROL attacker's own mkdir: {ownmkdir.stderr.strip()}")

subprocess.run(["ln", "-s", private, f"{shared}/static.lock.filelock"], check=True, asattacker) refused = subprocess.run([victimjob, f"{shared}/static.lock"], captureoutput=True, text=True, check=True, asvictim) print(f"CONTROL symlink resting at static.lock.filelock: {refused.stdout.strip()}; private directory holds {os.listdir(private)}")

the job has run before, undisturbed, so work.lock.filelock is the victim's own directory firstrun = subprocess.run([victimjob, f"{shared}/work.lock"], captureoutput=True, text=True, check=True, asvictim) coordination = os.lstat(f"{shared}/work.lock.filelock") print(f"CONTROL undisturbed job: {firstrun.stdout.strip()}; work.lock.filelock is {stat.filemode(coordination.stmode)}, owner uid {coordination.stuid}") privatebeforeattack = os.listdir(private) print(f"CONTROL private directory holds {privatebeforeattack}")

attack: the attacker keeps exchanging work.lock.filelock with a symlink to the private directory while the job keeps running; each run is one more chance to land between the check and the use swapper = subprocess.Popen([attackerswaploop, f"{shared}/work.lock", private], asattacker) joboutcomes = collections.Counter() while joboutcomes.total() < 200 and not os.listdir(private): job = subprocess.run([victimjob, f"{shared}/work.lock"], captureoutput=True, text=True, asvictim) joboutcomes[job.stdout.strip()] += 1 assert swapper.poll() is None, "the attacker's swap loop stopped on its own" swapper.kill() swapper.wait()

check: the victim's lock created "claims" inside the directory the attacker could not write print(f"OBSERVED {joboutcomes.total()} runs of the job printed {dict(joboutcomes)}") print(f"OBSERVED private directory holds {os.listdir(private)}") redirected = False if os.path.lexists(f"{private}/claims"): claims = os.lstat(f"{private}/claims") print(f"OBSERVED {private}/claims is {stat.filemode(claims.stmode)}, owner uid {claims.stuid} (victim is {victimuid}), holds {os.listdir(f'{private}/claims')}") redirected = stat.SISDIR(claims.stmode) and claims.stuid == victimuid print("BUG" if privatebeforeattack == [] and redirected else "OK")

repro.d/attackerswaploop.py

python import ctypes import os import sys import time

lockpath, targetdirectory = sys.argv[1], sys.argv[2] coordinationdirectory = f"{lockpath}.filelock".encode() symlinktotarget = f"{lockpath}.decoy".encode() os.symlink(targetdirectory, symlinktotarget)

renameat2 = ctypes.CDLL(None, useerrno=True).renameat2 ATFDCWD = -100 RENAMEEXCHANGE = 2 giveupat = time.monotonic() + 300 while time.monotonic() < giveupat: # one atomic syscall: the name always exists, as the victim's directory or as the symlink if renameat2(ATFDCWD, coordinationdirectory, ATFDCWD, symlinktotarget, RENAMEEXCHANGE) != 0: raise OSError(ctypes.geterrno(), "renameat2(RENAMEEXCHANGE)")

repro.d/victimjob.py

python import sys

from filelock import StrictSoftFileLock

try: with StrictSoftFileLock(sys.argv[1], timeout=1): print("job ran") except OSError as error: # filelock.Timeout and SoftFileLockProtocolError are both OSError print(f"job skipped: {type(error).name}")

Attack sequence

mermaid sequenceDiagram participant X as other local user participant N as work.lock.filelock (name in shared dir) participant V as job of the lock user (StrictSoftFileLock, timeout=1) participant T as /tmp/private (0700, lock user only) X->>N: plant work.lock.decoy -> T, loop renameat2(RENAMEEXCHANGE) rect rgb(207, 228, 255) V->>N: lstat work.lock.filelock: a real directory end rect rgb(255, 214, 214) X->>N: exchange lands: name is now the symbolic link to T V->>T: mkdir work.lock.filelock/claims creates T/claims (owned by the lock user) V->>T: scan, publish intent-v1-<token>.claim, link held-v1-<token>.claim in T/claims X->>N: exchange again: name is the directory V->>N: release(): unlink by path gets ENOENT, counted as removed Note over V,T: T/claims and its claim files stay behind#59; aimed at another lock's .filelock they block that lock end Note over V,N: a miss: lstat sees the symbolic link, SoftFileLockProtocolError, next run tries again

Evidence

The scanner's reproducer (commit b831496, Linux 6.1 x8664, CPython 3.14, fs.protectedsymlinks=1) creates /dev/shm/filelock-repro-shared (0777, no sticky bit) and /tmp/filelock-repro-private (0700, owned by victim). Three controls run first. The other account's own mkdir in the private directory answers Permission denied. A link resting at static.lock.filelock gives job skipped: SoftFileLockProtocolError with the private directory holding []. An undisturbed job prints job ran and leaves work.lock.filelock as drwxr-xr-x, owner uid 1000.

Then the swap loop starts and the job (with StrictSoftFileLock(path, timeout=1)) runs up to 200 times until the private directory is no longer empty. That took 1 to 8 runs, about 1.5 s in total. Afterwards claims, a directory owned by uid 1000 and mode 0755, is in the private directory; in some runs it holds intent-v1-<token>.claim and held-v1-<token>.claim files. Verdict BUG. In a 1777 directory on tmpfs (a memory-backed filesystem), with the other account having created <path>.filelock first, the lock user created T/claims after 4, 22 and 2 runs in three trials. The scanner ran the four further cases under Mechanism in separate runs with the same accounts.

Our review ran the reproducer against the 4.2.0 release image and the scanned commit (BUG on both) and against the head of #839 (OK: all 200 runs completed with the private directory empty). The review's regression tests on POSIX cover the claims-level swap and the forcebreak() case. We did not verify Windows.

Impact

Another local user who can rename <path>.filelock makes the lock user's process create a directory named claims, mode 0777 & ~umask (umask: the process's default permission mask), inside any directory that process can write, and leave claim files in it. The other user chooses the location only. filelock fixes the directory name, and the files contain filelock's own claim record (magic, token, PID, host name, start token). The process overwrites or truncates nothing that exists. This amounts to directory and file creation outside the lock's directory with the lock user's privileges, not a write of chosen data.

Where the chosen directory already has a claims subdirectory, the lock user's process also scans it, unlinks entries named like stale private records, and raises an error that quotes the first other file name in it. Aimed at another strict lock's .filelock directory, the stranded claims deny that lock to every process until an operator finds and forcebreak()s each one. Without this the other user has no way to affect a lock in a directory it cannot enter. The swap at claims leaves one-byte 0600 dot-files instead of claims.

Through claims, another user learns one file name per planted link from a directory only the lock user can list, and whether a guessed path is missing or empty, a file or a directory. This needs the exception text or its claimname to reach that user (a shared log, CI output, an error report); on its own this disclosure is minor. The forcebreak() variant puts two processes inside a different strict lock's critical section, one the other user can neither list nor write, with neither told. That happens only when the lock user runs the tutorial's blind recovery loop.

This shares only the bug class with GHSA-j8f7-rjxc-mr56 (the symbolic link at the ReadWriteLock database path, fixed in 4.0.9). There the other user chose the file the lock opened. Here the link sits one component above the final one, the other user swaps it in after the check that refuses it, and it chooses only the parent directory.

Workarounds

Keep strict locks in a directory no other user can write. In a sticky shared directory, create <path>.filelock as the service user before any other account can, and check its owner before first use. Do not run the recovery loop from docs/tutorials.rst on a lock in a shared directory without first verifying, as docs/how-to.rst says, that the owner named in each claim is gone. Treat an unexpected SoftFileLockProtocolError that quotes an unknown claim name as a sign that claims may point elsewhere. Keep the exception text of claims out of logs other accounts can read. On Windows, keep the lock directory writable only by trusted users.

Patched version

4.2.1.

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

Credits

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

- 2026-10-15 23:08 UTC: report received (finding ANT-2026-SVFEYX89, scanned commit b831496b0273) - 2026-10-16 01:31 UTC: fix PR #839 opened - 2026-10-16 05:41 UTC: draft advisory created (first as part of GHSA-9c4x-gm8v-wgc4, then split into this advisory)