auth-header-trust-rules

一个小的 Semgrep 规则包，用于标记基于攻击者控制的 HTTP 请求头做出认证、授权或信任决策的代码。

该漏洞类的典型示例是 CVE-2025-29927：Next.js 信任 x-middleware-subrequest 头来决定中间件是否运行，任何提供了精心构造值的入站请求都可以完全跳过中间件。同样的模式在各个框架和生态系统中反复出现。

此规则包涵盖了两种语言系列和该漏洞的三个子类。它旨在作为代码审查辅助工具，而非完全调优的 CI 门禁。规则偏向于召回率而非精确度，最好以交互方式运行，由人工对每个发现做出判断。

如需更详细地了解该漏洞类以及此包背后的设计选择，请参阅 bk-security.github.io。

规则清单

快速开始

安装 Semgrep：

pip install semgrep

针对目标运行规则包：

semgrep --config /path/to/auth-header-trust-rules/rules /path/to/target

或者运行单条规则：

semgrep --config /path/to/auth-header-trust-rules/rules/nodejs/header-flag-auth-bypass.yaml /path/to/target

针对捆绑的测试夹具验证规则：

semgrep --test --config rules/ tests/

预期输出：

6/6: ✓ All tests passed

规则能捕获和不能捕获的内容

规则匹配于一个已知在受信任时危险的头部名称精选列表。它们能捕获常见情况。它们不会捕获：

• 框架中头部读取隐藏在辅助函数内，且函数名称不包含头部字符串的情况。名为 getInternalFlag(req) 的自定义辅助函数若读取 x-some-novel-name 将逃过规则。
• 不在精选列表中的头部名称。CVE-2025-29927 类原则上可以使用任何头部名称；我们通过包含诸如 x-internal-*、x-trust-* 和 x-bypass-* 等模式来偏向召回率，但新名称仍会漏过。
• 基于 cookie、查询参数或请求体字段的认证决策。这些属于同一漏洞类，但需要单独的规则。
• 基于头部缺失的认证决策。某些应用在头部不存在时跳过认证检查（错误的允许列表模式）。当前规则是读取并使用，而非基于缺失。

在为特定代码库扩展此包时，最高价值的添加通常是特定框架的辅助函数模式。如果代码库有一个 isInternalRequest(req) 辅助函数，捕获它的规则只需一行 YAML。

添加规则

1. 在 rules/<lang>/<name>.yaml 下创建规则。
2. 在 tests/<lang>/<name>.<ext> 下创建测试夹具，其中包含标注为 # ruleid: <rule-id> 的正例和标注为 # ok: <rule-id> 的反例。
3. 运行 semgrep --test --config rules/ tests/。新规则和夹具将被自动识别；在提交更改前测试必须通过。

许可证

MIT。

作者

Bruce Kang。配套博文的源代码位于 bk-security.github.io。