Reporting API in PHP konfigurieren

Schritt-für-Schritt-Anleitung: Reporting API in PHP einrichten — Reporting-Endpoints definieren, CSP-Reports empfangen und auswerten.

PHP · Schritt für Schritt

Reporting API in PHP

Die Reporting API ermöglicht es Browsern, Security-Violations automatisch an einen Endpoint zu senden. Statt CSP-Verstöße, COOP-Verletzungen oder Deprecation-Warnungen nur in der Browser-Konsole zu sehen, erhalten Sie strukturierte JSON-Reports. Mit 2 von 166 Punkten im Wolf-Agents Web Security Check.

In PHP setzen Sie den Reporting-Endpoints-Header per header(). Zusätzlich brauchen Sie einen PHP-Endpoint, der die JSON-Reports entgegennimmt und verarbeitet. Die auto_prepend_file-Methode in der .user.ini garantiert, dass der Header vor jeder Ausgabe gesetzt wird — der klassische "Headers already sent"-Fehler ist damit ausgeschlossen.

Die Reporting API ersetzt den alten report-uri-Mechanismus durch report-to. Der neue Standard unterstützt Batching und funktioniert mit mehreren Security-Headern gleichzeitig (CSP, COOP, NEL). Für die Übergangszeit empfehlen wir, beide Mechanismen parallel zu nutzen.

1 Schritt 1 von 3

Reporting API in PHP konfigurieren

Drei Teile: Der Reporting-Endpoints-Header definiert die Ziel-URLs, die report-to-Direktive in CSP aktiviert das Reporting, und ein PHP-Endpoint empfängt die Reports. Auto-Prepend sorgt dafür, dass die Header global gesetzt werden.

security-headers.php Header
<?php
// security-headers.php — Reporting API

if (!headers_sent()) {
    // Reporting-Endpoints definieren
    header('Reporting-Endpoints: csp-endpoint="https://ihre-domain.de/api/csp-report", default="https://ihre-domain.de/api/reports"');

    // CSP mit report-to Direktive
    header("Content-Security-Policy: default-src 'self'; report-to csp-endpoint");

    // Weitere Header mit report-to:
    // Cross-Origin-Opener-Policy: same-origin; report-to=default
}
.user.ini Auto-Prepend
; .user.ini — Auto-Prepend für Reporting API

auto_prepend_file = "/var/www/html/security-headers.php"

; Die security-headers.php setzt Reporting-Endpoints
; global für alle PHP-Dateien.
; PHP-FPM Cache-TTL: 5 Minuten
; Nach Änderung: systemctl restart php-fpm
api/csp-report.php Report-Endpoint
<?php
// api/csp-report.php — Report-Empfänger

header('Content-Type: application/json');

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit;
}

$body = file_get_contents('php://input');
$reports = json_decode($body, true);

if (!$reports) {
    http_response_code(400);
    exit;
}

// Reports loggen oder in Datenbank speichern
foreach ($reports as $report) {
    error_log(json_encode($report));
}

http_response_code(204);
report-to vs. report-uri

Die alte report-uri-Direktive ist deprecated, wird aber noch von allen Browsern unterstützt. report-to ist der neue Standard. Für maximale Kompatibilität setzen Sie beide: report-uri /api/csp-report; report-to csp-endpoint.

2 Schritt 2 von 3

Konfiguration verifizieren

Prüfen Sie den Reporting-Endpoints-Header und testen Sie den Report-Endpoint mit einem POST-Request. Der Endpoint muss mit Status 204 antworten. Beachten Sie: PHP header() wirkt nur für PHP-Dateien — statische Dateien brauchen die Webserver-Konfiguration.

Terminal Verifizierung
# Reporting-Endpoints prüfen
curl -sI https://ihre-domain.de | grep -i reporting-endpoints

# Erwartete Ausgabe:
Reporting-Endpoints: csp-endpoint="...", default="..."

# Report-Endpoint testen:
curl -X POST https://ihre-domain.de/api/csp-report \
  -H "Content-Type: application/json" \
  -d '[{"type":"csp-violation","body":{}}]'
# Erwarteter Status: 204 No Content
Nutzen Sie den Wolf-Agents Web Security Check für eine vollständige Prüfung aller 2 Punkte der Reporting API.
3 Schritt 3 von 3

Häufige Fehler

Headers already sent

Der häufigste PHP-Fehler: header() nach einer Ausgabe aufrufen. Nutzen Sie auto_prepend_file in der .user.ini — die Header-Datei wird garantiert vor jeder Ausgabe geladen. Eine BOM vor <?php zählt als Ausgabe.

Report-Endpoint gibt nicht 204 zurück

Der Browser erwartet Status 204 (No Content) vom Report-Endpoint. Wenn PHP eine HTML-Fehlerseite oder Status 200 mit Body zurückgibt, kann der Browser das Reporting einstellen. Setzen Sie http_response_code(204) ohne Body.

CORS auf dem Report-Endpoint

Reporting-Requests von Cross-Origin-Seiten brauchen CORS-Header auf dem Endpoint. Setzen Sie Access-Control-Allow-Origin: * und Access-Control-Allow-Methods: POST auf dem Report-Endpoint.

Statische Dateien ohne Header

PHP header() wirkt nur für PHP-Dateien. Statische Assets (CSS, JS) brauchen den Reporting-Endpoints-Header über die Webserver-Konfiguration. Ohne den Header auf allen Responses fehlen Reports für statische Ressourcen.

Compliance-Relevanz

PCI DSS 4.0 — Anforderung 6.4.3 — Monitoring von Security-Policy-Violations auf Zahlungsseiten.
OWASP ASVS — V14 — Logging und Monitoring von Security-Header-Verstößen.
NIS2 — Art. 21(b) — Erkennung und Behandlung von Sicherheitsvorfällen in Echtzeit.

Wie steht Ihre Domain bei Reporting API?

Prüfen Sie es jetzt — kostenlos, ohne Registrierung, mit 166 Prüfpunkte.