Skip to content

fix(site): close the hard-link race in open_container_file() on overlayfs - #534

Open
mrrobot47 wants to merge 1 commit into
EasyEngine:developfrom
mrrobot47:fix/sc4344-container-file-links
Open

mrrobot47 wants to merge 1 commit into
EasyEngine:developfrom
mrrobot47:fix/sc4344-container-file-links

Conversation

@mrrobot47

@mrrobot47 mrrobot47 commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

open_container_file() refuses to write a file in a site's config volume when it has other hard links, by checking st_nlink. While a rename over the file is still running, its old name can still be looked up even though the link is already gone from the inode's count. So a file that is hard-linked elsewhere reports nlink 1 for a moment, and a racing container could get the write into the other file. This shows on overlayfs, for example when /opt/easyengine runs inside a container: 8 (PHP 7.4) and 15 (PHP 8.5) writes landed in the linked file per 100,000 attempts. It was never seen on ext4 or tmpfs.

This change looks up a name that doesn't exist in the directory before the checks that follow fstat(), but only for writes. That lookup takes the directory lock a running rename holds, so it waits for the rename to finish, and the checks after it see the old name gone. Nothing is created in the directory, and reads are unchanged.

The write is now also refused when the lstat() of the path after that lookup reports other links. Without /proc (macOS) only the path's inode was checked after opening, so a hard link made to the file at that point (for example the opened file renamed to another name and linked back as custom.ini) was not caught. On Linux the /proc check already catches that case; there the extra check only refuses a file that gets a second name while it is being opened.

Every write through the helper gets the extra lookup: ee site restore and the site-command and site-type container migrations that edit custom.ini. There is no visible change in their output.

Tested with a hard-link racer on overlayfs, ext4 and tmpfs on PHP 7.4 and 8.5: no writes landed in the linked file over at least 300,000 attempts per PHP version on overlayfs, against 8 and 15 per 100,000 before the change. A lookup of an existing path at the same point, which takes no lock, still let writes through, so the lock is what closes the race. The symlink, FIFO, device and directory-swap racers and the 33-case static check of the helper behave as before.

For the link-count check, new unit tests on PHP 7.4 and 8.5 simulate a host without /proc and add a hard link to the file between opening and checking it, either a second name for it or the file renamed away and linked back; both are refused now and were written before. With /proc, the racer above never reached that check. With /proc hidden, the racer on overlayfs got 24 writes through in 200,000 without the check and 1 in 400,000 with it; only /proc can name the opened file, so that last case is left for hosts with no /proc whose sites live on overlayfs, which EasyEngine doesn't run on.

Summary by CodeRabbit

  • Bug Fixes
    • Write-capable file opens now check both the opened file and its linked path. If either has more than one hard link, the open is rejected. Read-only opens are unaffected by this check, so their existing behavior remains unchanged.

…ayfs

open_container_file() refuses to open a file for writing when it has other hard links, by checking st_nlink on the opened handle and the path name afterwards. While a rename over the file is still running, the old name can still be looked up even though the kernel has already dropped that link from the inode's count. A hard link that is being replaced then reports nlink 1, the path still names it, and the write goes into the other file. On overlayfs the window is wide enough for a racing container to hit it a few times per 100,000 attempts; on ext4 and tmpfs it was never hit.

Before the checks that follow fstat(), look up a name that doesn't exist in the directory. A lookup that misses the dentry cache takes the directory lock that a running rename or unlink holds, so it waits for that operation to finish, and the checks after it see the old name gone. Read-only opens are unchanged.

Also refuse the write when the lstat() of the path after that lookup reports other links. On hosts without /proc (macOS) only the path's inode was checked after opening, so a hard link made to the file after the lookup was not seen there.
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Changes: Container file validation

Layer / File(s) Summary
Write-open validation
src/helper/site-utils.php
For r+ opens, the function looks up a unique name in the directory before validation. It rejects handles if the opened file or linked path has multiple links. The documentation now includes the handle’s link count among non-Linux checks.

Change: Bug fix

Merge Risk: Minimal · up to 3027b

This change tightens write-open validation so multiply-linked container files are refused. Read-only opens are unchanged. No actionable merge-blocking risk is evident.

Security architecture risk: Minimal · up to 3027b

The inspected change tightens writable-file validation without weakening existing identity checks. Rejected opens occur before modification, and the inspected migration warns and preserves backups when restoration is refused. No introduced or worsened material risk was established.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The relevant attacker capability is control over directory entries in a site's PHP configuration volume while a privileged host operation opens a file there. The protected outcome is preventing that write from reaching an unintended linked object. The inspected evidence does not establish arbitrary host-file access or cross-tenant reach.

Trust Boundaries and Controls

  • observed — The gate continues to compare device and inode identity before and after opening, require regular files, validate directory paths and consult the kernel-reported descriptor path when available. The added link-count condition strengthens rejection, and rejected handles are closed before an exception escapes. Without /proc, descriptor-path validation remains unavailable and the added path link-count check supplies an additional control.
Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

PHPStan (2.3.3)

Composer install failed: dependency resolution error. Check composer.json and composer.lock for version constraints.

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 43ced8ec-3141-46b8-a9d2-1fe6470fcdeb
Commits

Reviewing files that changed from the base of the PR and between 36eb861 and 3027bc3.

Files selected for processing: 1

  • src/helper/site-utils.php

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant