auth-header-trust-rules

A small Semgrep rule pack that flags code making authentication, authorization, or trust decisions based on HTTP request headers an attacker controls.

The canonical example of the vulnerability class is CVE-2025-29927: Next.js trusted the x-middleware-subrequest header to decide whether middleware ran, and any inbound request that supplied a crafted value could skip middleware entirely. The same shape recurs across frameworks and ecosystems.

This pack ships rules for two language families and three sub-classes of the bug. It is intended as a code-review aid, not a fully-tuned CI gate. The rules prefer recall over precision and are best run interactively, with a human making the call on each finding.

For a longer write-up of the vulnerability class and the design choices behind this pack, see bk-security.github.io.

Rule Inventory

Quick Start

Install Semgrep:

pip install semgrep

Run the pack against a target:

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

Or run a single rule:

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

Validate the rules against the bundled fixtures:

semgrep --test --config rules/ tests/

Expected output:

6/6: ✓ All tests passed

What the Rules Will and Will Not Catch

The rules match on a curated list of header names known to be dangerous when trusted. They will catch the common cases. They will not catch:

• Frameworks where the header read is hidden inside a helper function whose name does not contain the header string. A custom helper named getInternalFlag(req) that reads x-some-novel-name will pass the rules.
• Header names not on the curated list. The CVE-2025-29927 class can in principle use any header name; we err on the side of recall by including patterns like x-internal-*, x-trust-*, and x-bypass-*, but novel names will slip through.
• Auth decisions based on cookies, query parameters, or request body fields. Those are the same vulnerability class but require their own rules.
• Auth decisions based on the absence of a header. Some applications skip auth checks when a header is not present (a misconfigured allowlist pattern). The current rules are read-and-use, not absence-based.

When extending the pack for a specific codebase, the highest-value additions are usually framework-specific helper-function patterns. If a codebase has a isInternalRequest(req) helper, the rule that catches it is one line of YAML.

Adding a Rule

1. Create the rule under rules/<lang>/<name>.yaml.
2. Create a test fixture under tests/<lang>/<name>.<ext> with positive examples annotated # ruleid: <rule-id> and negative examples annotated # ok: <rule-id>.
3. Run semgrep --test --config rules/ tests/. The new rule and fixture will be picked up automatically; tests must pass before submitting a change.

License

MIT.

Author

Bruce Kang. Source for the companion blog post lives at bk-security.github.io.