在合并前加一道闸:让漏洞自查进入每次提交的检查链路
在合并前加一道闸:让漏洞自查进入每次提交的检查链路
PHP2Shell(CVE-2026-109618 / CVE-2026-109619)最让人不安的地方,不是 CVSS v4.0 的 9.2 分,而是它的位置:漏洞不在业务代码里,而在 PHP 引擎的请求生命周期中。你把自己的仓库翻个底朝天,也找不到那行“有问题的代码”,因为问题出在跑代码的那台机器上。当官方在 10 月 21 日同时放出 8.5.12 / 8.4.27 / 8.3.36 / 8.2.35 四个修复版本时,社区复盘里已经出现了“补丁发布时 PoC 已公开、利用工具已泄露”的说法,甚至有云厂商称在公开披露前就监测到大量攻击尝试——修复窗口被压缩到了以小时计。
这意味着安全检查的对象变了:从“我提交的代码”扩展到“我部署的运行时”。而一旦检查对象变成运行时版本,它就非常适合变成一个带退出码的命令,插进每次提交与每次合并的链路里。
本仓库 php2shell-checker 提供的正是这样一个最小可用的断言工具:不跑 exploit、不扫响应体、只做版本判定,然后把结论压缩进 0/1/3 三个退出码。本文从源码出发,讲清楚它判什么、不判什么,以及怎样把它接进 pre-commit 与 pre-merge,而不至于第三天就被团队关掉。
为什么这次没法靠“审代码”发现
先摆事实。PHP 官方 10 月 21 日的安全公告把两个漏洞的成因写得很直白:一个是 OOM(内存耗尽)处理过程中请求数据只初始化了一半,清理阶段把无效数据当成有效数据处理(CVE-2026-109618);另一个是请求私有的内部状态在其内存被释放后仍然存活,同一 worker 处理的下一个请求可能在正常初始化覆盖它之前就用到这份陈旧状态(CVE-2026-109619)。
这两条描述的共性在于:它们都发生在应用代码执行之前或之外。官方明确点出,风险最高的是 mod_php,因为已有演示表明未认证请求可以在任何应用代码运行前触发攻击;受影响面覆盖 PHP-FPM、Apache mod_php、php-cgi、FrankenPHP 与 LiteSpeed。社区里那句“站点代码只有一个 Hello World 也同样暴露”,说的就是这个意思。
对工程团队而言,这带来三个直接后果:
- SAST 与代码评审失效。PHPStan、Psalm、PHPCS 分析的是语法树与类型流,它们没有“引擎版本”这个输入。
- 依赖扫描也失效。
composer audit看的是composer.lock里的包,而 PHP 解释器本身不是 Composer 依赖。 - 8.1 及更早分支没有官方补丁。官方只提供了 7.4 / 8.0 / 8.1 的最小源码 backport,实际修复要依赖发行版或 LTS 厂商;8.1 分支上哪怕你打到
8.1.99,上游也没有对应修复。
所以真正需要被“检查”的,是一句可以证伪的断言:这台提供服务的机器,跑的 PHP 是否已经包含针对这两个 CVE 的修复。这就是本项目的定位。
一个把结论交给退出码的工具
仓库结构极简,一共八个文件。根目录的 phpcheck.js 只有两行,是一个转发入口:
#!/usr/bin/env node
require('./skills/phpcheck-url/scripts/phpcheck.js')
真正的实现位于 skills/phpcheck-url/scripts/phpcheck.js,99 行;配套两份技能说明书 skills/phpcheck-url/SKILL.md 与 skills/phpcheck-server/SKILL.md;phpcheck.test.js 用 Node 内置 test runner 写了 49 个用例。这种“入口 + 可独立分发的技能目录”的布局不是随手为之——测试里有一条 the URL skill runs independently with its bundled checker,会把 skills/phpcheck-url 整个复制到临时目录再执行,确保这个目录能脱离仓库单独使用。
判定逻辑集中在 versionStatus():
const FIXED_IN = { '8.2': 35, '8.3': 36, '8.4': 27, '8.5': 12 }
const OLDER_BRANCHES = new Set(['5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1'])
function versionStatus(version) {
const match = /^(\d+)\.(\d+)\.(\d+)([-+~].*)?$/.exec(version || '')
if (!match) return 'unknown'
if (/(?:^|[-+~.])(?:dev|alpha|beta|rc)/i.test(match[4] || '')) return 'unknown'
const branch = `${Number(match[1])}.${Number(match[2])}`
if (OLDER_BRANCHES.has(branch)) return 'potentially_vulnerable'
const fixed = FIXED_IN[branch]
if (fixed === undefined) return 'unknown'
if (Number(match[3]) < fixed) return 'potentially_vulnerable'
return 'ok'
}
这段不到二十行的函数决定了整套闸门的性格,值得逐条拆开:
- 只认同
x.y.z三段式。8.4这种两段版本直接unknown;8.4.27RC1、8.4.27-rc1、8.4.27~beta1、8.1.35-dev全部unknown——预发布版本不参与“是否已修复”的推断,这是一个正确的保守选择。 - 旧分支无条件告警。命中
OLDER_BRANCHES就返回potentially_vulnerable,不再看补丁号。测试里8.1.99与8.1.34同等待遇,这是刻意的:上游对这些分支没有发布修复,补丁号再大也不能证明安全。反过来说,如果你的资产清单里长期存在 8.1 主机,这道闸门会永远红——这个问题我们在后面的阈值设计里必须正面处理。 - 未知分支归入
unknown。8.6.0、9.0.0都返回unknown,因为FIXED_IN里没有它们的修复版本号。新分支刚出来时,工具会“闭嘴”,而不是给出一个乐观的ok。 - 发行版后缀被容忍。正则里
([-+~].*)?允许8.4.26-1ubuntu1、8.4.27-1ubuntu1这类版本串进入数值比较,测试里两者分别判定为potentially_vulnerable与ok。
三个状态与退出码的映射写在 main() 末尾:
const code = { ok: 0, potentially_vulnerable: 1, unknown: 3 }[result.patch_status]
加上参数解析失败时的 2,就得到了 README.md 里那张表:OK → 0、POTENTIALLY VULNERABLE → 1、UNKNOWN → 3、参数错误 → 2。JSON 模式下额外输出 patch_status、reason、php_version、exit_code 四个字段。
本地实测(Node v18.19.0,需要 fetch、AbortSignal.timeout、util.parseArgs,即 Node 18+):
$ node phpcheck.js --version
1.0.0
$ node phpcheck.js "not a url" ; echo "exit=$?"
UNKNOWN: URL contains spaces or control characters
exit=3
$ node phpcheck.js https://example.com --timeout 999 ; echo "exit=$?"
--timeout must be greater than 0 and at most 60 seconds
Usage: node phpcheck.js URL [--timeout SECONDS] [--json]
node phpcheck.js --version
exit=2
这里有一个必须提前知道的坑:URL 本身写错(含空格、协议不是 http/https、带账号或 fragment)并不会产生参数错误码 2,而是在 urlHeaders() 里抛异常,最终被归入 unknown、退出码 3。也就是说,“我把 URL 配错了”和“目标站隐藏了版本号”在退出码层面长得一模一样。CI 里如果对 3 采取放行策略,配置错误会被静默吞掉。这一点后面会专门用规则约束。
两种检查姿势:URL 与服务器
工具提供了两条互补的路径,恰好对应“外部可见面”和“内部真实面”。
URL 模式(phpcheck-url)读取响应头里的 Server 与 X-Powered-By。实现上有几条明确的设计边界:
for (const method of ['HEAD', 'GET']) {
const response = await fetch(url, {
method, redirect: 'manual', signal: AbortSignal.timeout(Math.ceil(timeout * 1000)),
})
headers.push(response.headers.get('server') || '', response.headers.get('x-powered-by') || '')
await response.body?.cancel()
if (![405, 501].includes(response.status)) break
}
- 先
HEAD,只有在 405 / 501 时才回退GET(测试逐条断言了['HEAD']与['HEAD','GET']两种调用序列); redirect: 'manual',不跟随跳转。若你的站点https://a.com301 到https://www.a.com,前者大概率读不到 PHP 头,结果是unknown。CI 里必须直接配置最终提供服务的那个 URL;- 不读响应体。测试特意构造了一个
Server: nginx、X-Powered-By: Express、正文写着PHP/8.4.27的响应,期望结果仍是unknown且理由是PHP version not found; - 超时默认 10 秒、上限 60 秒,
--timeout 0.1这类小数会被接受并换算成毫秒。
多个头部冲突时,取舍规则是“坏消息优先,未知次之,好消息最后”:
if (version === null || candidateStatus === 'potentially_vulnerable' || status === 'ok') {
version = match[1]
status = candidateStatus
}
if (status === 'potentially_vulnerable') break
测试覆盖了 Server: PHP/8.4.26 + X-Powered-By: PHP/8.4.27(判 8.4.26,告警)、Server: PHP/8.1.35 + X-Powered-By: PHP/8.4.27(判 8.1.35,告警)、以及 9.0.0 与 8.4.27 并存(判 9.0.0,unknown)。这条策略对闸门很友好:它不会因为一个漂亮的头而放过另一个可疑的头。
但 URL 模式的可信度天花板很低,skills/phpcheck-url/SKILL.md 自己写得很清楚:头可以被改,ok 只表示“宣称的版本达到上游修复版”,并不验证实际安装;HTTP 头也无法判断是否打了 backport。它甚至规定了措辞纪律——只能说 potentially vulnerable,绝不能说 confirmed vulnerable。
服务器模式(phpcheck-server)则要求把“版本号”换成“包版本 + 厂商公告”。它的第一条指令就是排除一个经典误判:默认 CLI 的 PHP 可能与 PHP-FPM 或 Apache 模块不是同一个安装。接着按发行版给方法:
# Debian / Ubuntu:读完整包版本并用 dpkg 比较
dpkg-query -W -f='${Package} ${Version}\n' php8.3-fpm
dpkg --compare-versions 8.3.6-0ubuntu0.24.04.13 lt 8.3.6-0ubuntu0.24.04.12
# RHEL:从二进制反查所属包,并核对 module stream
rpm -qf /usr/sbin/php-fpm
rpm -q --queryformat '%{NAME} %{EPOCHNUM}:%{VERSION}-%{RELEASE}.%{ARCH} %{VENDOR}\n' PACKAGE
dnf module list php --enabled
skills/phpcheck-server/SKILL.md 里给出了按发行版与 stream 整理的修复版本表,例如 Debian 12 的 php8.2 对应 8.2.35-1~deb12u1、Ubuntu 24.04 的 php8.3 对应 8.3.6-0ubuntu0.24.04.13、RHEL 8.10 的 PHP 7.4 对应 7.4.33-8.module+el8.10.0+25117+30337cca。这些数字的时效性有限(文档自己标注了“verified on 2026-10-22”),但方法论是稳的:版本阈值必须绑定“哪个发行版、哪个 stream、哪个公告”,不能把上游 8.2.35 直接套到 Debian 的 8.2.x 包上。
还有一条经常被忽略的收尾要求:装了修复包 ≠ 站点在跑修复包。文档要求确认实际提供服务的安装、以及更新后 worker 是否重启;无法确认时,应当把运行中站点的状态报告为 unknown。这条规矩直接决定了下面 CI 与人工流程的分界线。
把闸门插到两个节点
仓库本身只交付检查器与技能说明,不含任何流水线配置,所以下面的接入方式是围绕它的契约设计的,而不是在描述仓库里已有的文件。
节点一:提交前(pre-commit)
提交前适合做廉价、离线、必过的断言。URL 模式需要网络,不适合放在每个人的 pre-commit 里——它会因为 VPN、内网 DNS、目标站抖动而随机失败,最终逼所有人加 --no-verify。更合理的做法是把 pre-commit 限定为两类:
- 保证检查器本身可用(技能目录被改动时跑测试);
- 对本次改动涉及的部署清单做一次本地静态核对。
#!/bin/sh
# .githooks/pre-commit
set -eu
# 1) 检查器与测试一起演进:改了 skill 目录就必须让 49 个用例过
if git diff --cached --name-only | grep -qE '^(phpcheck\.js|phpcheck\.test\.js|skills/)'; then
node --test phpcheck.test.js || { echo "phpcheck 测试未通过,拒绝提交"; exit 1; }
fi
# 2) 断言 FIXED_IN 与部署清单里记录的基线一致(防止有人手改阈值不升级版本)
node -e '
const fs = require("node:fs")
const src = fs.readFileSync("skills/phpcheck-url/scripts/phpcheck.js", "utf8")
const m = /FIXED_IN = (\{[^}]*\})/.exec(src)
const fixed = Function("return " + m[1])()
const expected = { "8.2": 35, "8.3": 36, "8.4": 27, "8.5": 12 }
for (const k of Object.keys(expected)) {
if (fixed[k] !== expected[k]) { console.error("FIXED_IN 与基线不符:", k, fixed[k]); process.exit(1) }
}
' || exit 1
第二段看起来像“把常量抄了两遍”,但它防的是一个真实故障模式:FIXED_IN 是硬编码在源码里的,一旦有人为了“让流水线变绿”而调低阈值,所有下游判断同时失真。提交前把它和基线钉住,比在评审里靠肉眼发现要可靠。
node --test 在这台机器上跑完 49 个用例约 88 秒(每个用例都会 spawn 一个子进程并起本地 HTTP server,其中几条依赖 1.5 秒级的超时路径)。对 pre-commit 来说偏重,实践中可以只在 skills/ 变更时触发,或者把完整测试留给 CI。
节点二:合并前(pre-merge)
合并前才是真正的闸门,因为这时你有干净的环境、可控的网络、以及“必须给出结论”的压力。
#!/bin/sh
# scripts/gate.sh —— 在 PR 流水线中执行
set -u
STATUS=0
for target in $(cat deploy/targets.txt); do # 每行一个 https://host --json 目标
out=$(node phpcheck.js "$target" --json --timeout 15)
code=$?
echo "$out"
case "$code" in
0) : ;; # 通过
1) echo "::error::$target 版本低于修复基线"; STATUS=1 ;;
3) echo "::warning::$target 无法判定版本(可能隐藏头部或 URL 需跳转)" ;;
2) echo "::error::检查器参数错误"; STATUS=1 ;;
*) echo "::error::未知退出码 $code"; STATUS=1 ;;
esac
done
exit $STATUS
请注意这段脚本里唯一被硬性阻断的是 1 和 2,3 只记录不失败。原因很实际:unknown 太容易出现了——站点关了 X-Powered-By、入口做了 301、HEAD 被 WAF 拦成 403、内网目标在 CI 里不可达。如果 3 也阻断,第一周就会有人把整段删掉。但“不阻断”绝不等于“放过”,下面用规则把它变成待办。
至于 HTTP 模式的天然缺陷(头可伪造、无法验证 backport),落地的补救办法是在合并前跑一次服务器模式的人工/半自动核对,把结果写回 deploy/targets.txt 旁的证据文件:包名、完整版本、对应公告、worker 是否重启。工具只负责把“版本是否达标”变成机器可判定的布尔值,unknown 的收敛仍然需要一次真实登录。
阈值怎么定,才不至于天天红
把退出码直接映射成“失败/成功”是最容易崩的做法。这个工具的输出实际上有三档语义,需要三种不同的处理策略:
| 退出码 | 语义 | 建议策略 | 谁负责收敛 |
|---|---|---|---|
0 |
宣称版本 ≥ 上游修复版 | 放行,但记录基线 | 无需动作 |
1 |
版本落在受影响区间,或属于无上游补丁的旧分支 | 阻断合并(生产面向的目标);预发/内部目标可降级为告警并开单 | 资产 Owner |
2 |
参数/用法错误 | 阻断,且视为流水线 bug | 平台维护者 |
3 |
无法判定(隐藏、跳转、超时、新分支、预发布) | 不阻断,但必须产生带 Owner 与期限的工单 | 资产 Owner |
这张表里真正需要解释的是 1 的两条特殊情形。
第一条:旧分支会永久红。 由于 OLDER_BRANCHES 无条件返回 potentially_vulnerable,一台跑 8.1.x 的机器无论怎么打补丁,在这个工具眼里都是 1。这不是缺陷,而是事实的上游状态:8.1 已停止维护,官方只给了最小源码 backport。正确做法不是给这类目标加豁免,而是把它变成升级工单——闸门的价值恰恰在于它不会因为“补丁号很大”而自我安慰。
第二条:发行版 backport 会被误伤。 一台 Ubuntu 22.04 上已经装了 8.1.2-1ubuntu2.28(该发行版公告里的修复版)的机器,URL 模式读到 PHP/8.1.2,仍然返回 1。这就是 URL 模式的结构性局限,文档也承认“HTTP 头无法判断是否包含 backport”。此时应当用服务器模式核对包版本,并把结论以证据形式记录,而不是修改工具的判断。
至于扫描频率,建议拆成两条独立链路:
- 合并前:只扫这次改动影响的目标,追求快,
--timeout 15; - 定时:每天或每周扫全量,并把
--json结果落盘归档。版本会漂移(重建镜像、换基础镜像、运维手工升级),合并前的那一次通过不能代表下周还通过。
额外一条实践建议:把 phpcheck.js 的版本号(--version 当前是 1.0.0)一并写进归档记录。判定阈值内嵌在源码里,只有把“用哪个版本的规则判的”记下来,历史结论才可复现。
与既有静态检查的分工
接了这道闸门之后,最常见的组织性误解是“我们已经有 PHPStan 和 Dependabot 了,为什么还要它”。三者的输入根本不同:
| 工具类别 | 输入 | 能发现 | 不能发现 |
|---|---|---|---|
| PHPStan / Psalm / PHPCS | PHP 源码 | 类型错误、可疑调用、编码规范 | 解释器自身缺陷 |
composer audit / Dependabot |
composer.lock、依赖清单 |
第三方包 CVE | PHP 二进制与 mod_php 模块 |
phpcheck URL 模式 |
Server / X-Powered-By |
对外宣称的解释器版本 | 真实安装、backport、配置缓解 |
phpcheck 服务器模式 |
包版本 + 厂商公告 | 已安装包是否含修复;worker 是否重启 | 应用逻辑漏洞 |
这张表也解释了为什么它不能替代 SAST:它连一行 PHP 代码都不读。反过来,SAST 也无法告诉你 mod_php 是不是 8.4.26。真正需要警惕的是把 phpcheck 当成“安全扫描”的全部——它只覆盖一个具体的 CVE 家族,而且明确声明不发送 exploit 探测(这是设计原则,SKILL.md 里重复了两遍)。
另一个容易被忽略的边界:不要用 URL 模式去扫共享主机或第三方托管站点。头部可由托管方随意配置,读到 ok 也不代表你的租户实例安全;这种情况下应当要求托管方出具包版本证据,否则结论只能是 unknown。
误报抑制与规则更新的现实约束
最后谈两个运维层面最容易腐化的部分。
豁免必须带证据和到期日
因为旧分支永远返回 1、backport 又会被 URL 模式误伤,团队一定会需要豁免机制。这里唯一可接受的形式是证据化豁免:
# deploy/exceptions.yaml
- target: https://legacy.example.com
reason: "Ubuntu 22.04 php8.1 已安装 8.1.2-1ubuntu2.28(USN-8948-1),URL 头只暴露 8.1.2"
evidence: "dpkg-query -W php8.1-fpm => 8.1.2-1ubuntu2.28;FPM worker 已于 2026-10-22 03:10 重启"
owner: platform-oncall
expires: 2026-12-31
三条硬规则:必须写清核对方式(否则下一个人无法复核)、必须有 Owner、必须有到期日。到期后豁免自动失效,闸门重新变红——这正是我们想要的:豁免是延期还款,不是债务核销。
要避免的反模式是“按目标永久忽略”或“按版本号前缀忽略”。前者会让一台机器在换镜像后再也没人看,后者会在 8.1.35 这种看似很高的补丁号上制造安全幻觉——测试里 8.1.99 依然判 potentially_vulnerable,就是在提醒这件事。
规则更新只能靠升级,不能靠改阈值
FIXED_IN 与 OLDER_BRANCHES 都是常量,skills/phpcheck-server/SKILL.md 里的厂商版本表也是带日期的快照。这意味着规则更新有唯一的正确路径:拿到新的官方公告 → 更新常量与文档 → 补测试 → 升版本号 → 重新部署检查器。
phpcheck.test.js 在这里承担了“契约锁定”的角色。它用显式夹具固定了四个分支的边界(8.2.34、8.3.35、8.4.26、8.5.11 全部告警,各加一个补丁号后全部通过),固定了旧分支的 12 个版本,固定了预发布与未知分支的 9 种写法,还固定了 GET 回退、双头冲突、纯文本输出措辞。任何一次阈值改动都会撞上这些断言,改动者必须同时解释“为什么这个边界变了”。这比在代码评审里争论要有效得多。
这也解释了 CONTRIBUTING.md 里那句略显冷冰冰的声明:项目不接受外部代码贡献,只收 bug 报告与非代码反馈。对一个安全判定工具来说,这个策略有其合理性——阈值是可被滥用的开关,收紧合并权限等于收紧了“谁能把红线往下调”。代价是规则更新依赖官方维护者的节奏,使用方必须自己承担“我的检查器是不是最新”的巡检责任,例如在定时任务里比对 --version 与预期版本。
还有一个悬而未决的现实问题:unknown 会持续存在。PHP 官方在 10 月 23 日又追加了一条关于 session 上传进度的信息性公告(CVE-2026-115560,建议在下一个常规版本前保持 session.upload_progress.enabled=0),这类“配置层面的缓解”完全落在版本检查的能力之外。工具只能回答“版本够不够”,而“FPM 是否重启过”“memory_limit 是否被应用覆盖”“post_max_size 是否收窄”这类问题,仍然需要一次真实的服务器侧核对。把这道闸门理解为把最容易漏、最机械的那一项变成自动化,而不是“安全已经做完”,才是它能长期留在流水线里的前提。
一条可执行的最小落地路径
如果今天就要在现有项目里落地,顺序建议是:
- 把 phpcheck.js 与
skills/目录整体加入仓库(或按技能方式独立分发),确认 Node ≥ 18,跑一次node --test phpcheck.test.js; - 建
deploy/targets.txt,只放最终提供服务的 URL,避免 301; - CI 里按退出码分流:
1与2阻断,3产出工单,0记录归档; - 对每个
unknown目标做一次服务器模式核对,把包名、完整版本、公告编号、worker 重启时间写进证据文件; - 给所有豁免加
owner与expires; - 把“检查器版本 + 全量扫描结果”纳入每周巡检,规则更新只走“改常量 + 补测试 + 升版本”这一条路。
PHP2Shell 之后还会有下一个引擎级漏洞。真正能复用的不是这份 99 行的脚本,而是它带来的那个习惯:把“我们跑的是什么版本”变成一条有退出码的断言,并让它在每次提交和每次合并时都被执行一次。 这类断言越多,安全就越不依赖某个人的记忆。