| name | php-filesystem-audit |
| description | PHP 文件系统操作审计工具。聚焦 mkdir/chmod/chown/unlink/rmdir/link/symlink/readlink/touch/权限与 TOCTOU 等操作的安全风险，为路径校验绕过与写入链利用提供“可利用性增强证据”（不替代 FILE/UPLOAD/WRITE 等 sink 子审计）。 |
PHP 文件系统操作审计（php-filesystem-audit）
分析 PHP 项目中对文件系统的关键操作，特别关注这些操作如何与：
- 路径校验/归一化失败（目录遍历、basePath 缺失）
- 落点写入/读取/包含链路
- 写后触发（可执行性、可包含性）
- 竞争条件（TOCTOU）
发生联动，从而提升真实利用可能性。
覆盖范围（必做）
必须覆盖并输出“证据点 + 风险解释 + 可利用性判断”的点：
1) 创建/目录操作
mkdir($path, $mode, $recursive)rmdir($path)touch($path)tmpfile() / tempnam()- 框架封装的目录创建（如
Storage::put/ensureDirectory 的底层封装，若识别得到）
2) 权限/所有权变更（常用于提权链或绕过执行策略）
3) 链接与重定向落点（常见 symlink/hardlink 绕过）
symlink($target, $link)link($target, $link)readlink($path)
4) 删除与清理（结合 TOCTOU 或覆盖链）
unlink($path)unlink/rename 变体删除rename($src, $dest)（用于落点变更时需特别关注 TOCTOU）copy/move 变体（当作为“落点准备步骤”出现）
5) 路径竞态与 TOCTOU（必须单独审计）
对“检查-使用分离”的代码模式给出判定：
- 是否存在
if (realpath/canonicalize + 前缀校验) 后又在某个分支/异常处理里重复 join/open/write（路径可能变化）
- 是否存在先判断可写/再写入、先检查再执行文件操作
- 是否存在符号链接解析/不一致解析（检查时与实际打开时 resolved path 不一致）
关键输出要求（强制）
每条发现必须包含：
-
位置证据：文件路径与函数/调用点（尽量带行号；找不到行号则标注待定位）
-
操作类型：创建/权限/链接/删除/重命名/拷贝等
-
路径控制来源：路径参数来自 GET/POST/SESSION/配置还是硬编码
-
跟链路的关系（必须至少选一条说明）：
- 与
WRITE/UPLOAD 落点可执行性或可包含性关联
- 与
FILE（读取/包含）或 ARCHIVE（解压落点）关联
- 与鉴权/资源归属关联（例如仅管理员目录有写权限但绕过）
- 与 TOCTOU 竞态关联（检查点 -> 使用点之间路径可能被替换）
-
可利用性判断：
- ✅ 已确认：能证明利用链的关键前置条件由此文件系统操作提供（或与 WRITE/UPLOAD/FILE 的证据形成闭环）
- ⚠️ 待验证：存在风险，但缺少某个关键前置条件或 trace/解析证据不足
- ❌ 不可利用：有强约束（baseDir allowlist 生效、resolved path 一致性保护、权限固定且无法更改、竞态窗口被消除）
- 🔍 环境依赖：需依赖特定文件系统/权限/并发时序/服务端目录结构
-
可触发性约束（强制）：
- 仅对“能够被具体 HTTP 路由/入口触发”的文件系统操作生成漏洞条目，并且必须能提供真实路由与完整参数用于 PoC。
- 若无法定位具体路由入口（如纯后台任务/定时任务/命令行工具且入口不可追踪），该 FS 风险只能在报告中标注“未能定位入口，跳过条目生成（待人工补齐触发路径）”，不得仍按漏洞条目模板强行输出不可执行 PoC。
报告输出
输出到：
{output_path}/vuln_audit/fs_{timestamp}.md
漏洞编号规范（建议：FS）
- 详见：
shared/SEVERITY_RATING.md
- 漏洞编号：
{C/H/M/L}-FS-{序号}
漏洞条目模板（强制）
每条发现必须遵循以下结构（不得省略）：
### [{等级前缀}-FS-{序号}] 文件系统操作链风险（权限/链接/删除/TOCTOU/路径控制）
| 项目 | 信息 |
|------|------|
| 严重等级 | {🔴/🟠/🟡/🔵} (CVSS {score}) |
| 可达性 (R) | {0-3} - {理由} |
| 影响范围 (I) | {0-3} - {理由} |
| 利用复杂度 (C) | {0-3} - {理由} |
| 可利用性 | ✅ 已确认 / ⚠️ 待验证 / ❌ 不可利用 / 🔍 环境依赖 |
| 位置 | {file}:{line} ({Function/Class}) |
#### 数据流链（Source → Path Control → FS Operation → Chain Influence）
（逐行写出：用户/上下文输入如何进入路径控制变量、是否经过 realpath/canonicalize 及前缀校验、最终如何落到 mkdir/chown/symlink/unlink/rename/等文件系统操作参数、以及该文件系统操作如何影响后续链路能力：WRITE/UPLOAD/FILE/ARCHIVE/CMD/TPL/EXPR/DESER 等）
#### 可利用前置条件
- 鉴权要求：{无需/需登录/需特定权限}
- 输入可控性：{完全可控/条件可控/不可控}
- 触发条件：{分支/异常路径/需要特定文件系统权限/需要竞态窗口/需要特定目录结构}
- 链路承接：{它如何为其它 sink 类别提供“可利用性增强”说明（写入落点/可包含性/权限提升/绕过执行策略/触发竞态）}
#### 验证 PoC（强制：可观测验证框架）
```http
{HTTP Method} {真实路由与完整参数} HTTP/1.1
Host: {host}
{必要 Header/Session/JWT/Cookie}
{Payload}
PoC 输出/观察点（必须写清楚）：
- 由该 FS 操作造成的文件系统状态变化是否可观测（例如：目标路径下文件创建/权限变化/链接指向变化/删除结果/最终落点存在性）。
- 若为 TOCTOU：展示“检查点与使用点 resolved path 不一致/窗口可被利用”的可观测现象（例如并发触发导致最终落点改变）。
证据引用（强制：来自源码片段）
必须至少包含三段与定位对应的证据片段（可以直接在文本中复述关键行）：
- FS 操作调用点（mkdir/chmod/chown/symlink/unlink/rename 等）及参数位置（file:line）
- 路径校验/归一化逻辑（realpath/canonicalize/baseDir 前缀校验）及其与 FS 操作之间的关系（同一函数内或跨函数）
- 路径控制来源（GET/POST/SESSION/配置硬编码等）及其传递链
建议修复
- 路径校验与实际使用必须绑定到同一个 resolved target：
realpath/canonicalize 后用同一个值进行 open/rename/write（避免 TOCTOU）
- 禁止对可被攻击者影响的路径进行“先校验后使用”的拆分；若必须拆分，应在同一系统调用/同一文件描述符上下文内完成
- 对 symlink/hardlink：在目标落点启用防链接策略（平台支持时禁用跟随符号链接，或基于 inode/文件描述符校验一致性）
- 权限变更必须最小化并确保不可由用户影响；避免攻击者能控制
chmod/chown 的路径
代码搜索语句（强制）
rg -n "(mkdir\\(|rmdir\\(|touch\\(|tmpfile\\(|tempnam\\(|chmod\\(|chown\\(|chgrp\\(|symlink\\(|readlink\\(|link\\(|unlink\\(|rename\\(|copy\\(|symlink\\()" .
rg -n "(realpath\\(|canonicalize\\(|dirname\\(|basename\\(|baseDir|dest(path)?|target(path)?)" .
修复建议（强制要点）
- 路径校验与实际使用必须绑定到同一个 resolved target：
realpath/canonicalize 后用同一个值进行 open/rename/write（避免 TOCTOU）
- 禁止对可被攻击者影响的路径进行“先校验后使用”的拆分；若必须拆分，应在同一系统调用/同一文件描述符上下文内完成
- 对 symlink/hardlink：在目标落点上启用防链接策略（平台支持时禁用跟随符号链接，或基于 inode/文件描述符校验一致性）
- 权限变更必须最小化并确保不可由用户影响；避免攻击者能控制
chmod/chown 的路径
