Dokumentacja

Raporty CSP — przewodnik konfiguracji i integracji

SiteGuardian zawiera wbudowany endpoint do przyjmowania naruszeń Content-Security-Policy oraz zdarzeń Reporting-API. Wystarczy skierować tam CSP, a naruszenia zgłaszane przez przeglądarki pojawią się w panelu monitora w ciągu kilku sekund.

1. Włącz w monitorze

Na stronie szczegółów monitora otwórz zakładkę CSP Reports i kliknij Włącz. Wygenerujemy świeży adres URL podpisany HMAC oraz gotowy do wklejenia fragment nagłówków.

2. Wklej nagłówki

Fragment zawiera trzy nagłówki. Przeglądarki obsługują je z bezpiecznym fallbackiem — można wdrożyć wszystkie trzy jednocześnie.

nginx

add_header Content-Security-Policy "default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}; report-to sg-csp" always;
add_header Reporting-Endpoints 'sg-csp="https://reports.siteguardian.io/r/{monitor_id}/{hmac}"' always;
add_header Report-To '{"group":"sg-csp","max_age":10886400,"endpoints":[{"url":"https://reports.siteguardian.io/r/{monitor_id}/{hmac}"}]}' always;

Apache

Header always set Content-Security-Policy "default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}; report-to sg-csp"
Header always set Reporting-Endpoints 'sg-csp="https://reports.siteguardian.io/r/{monitor_id}/{hmac}"'
Header always set Report-To '{"group":"sg-csp","max_age":10886400,"endpoints":[{"url":"https://reports.siteguardian.io/r/{monitor_id}/{hmac}"}]}'

Caddy

header {
    Content-Security-Policy "default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}; report-to sg-csp"
    Reporting-Endpoints `sg-csp="https://reports.siteguardian.io/r/{monitor_id}/{hmac}"`
    Report-To `{"group":"sg-csp","max_age":10886400,"endpoints":[{"url":"https://reports.siteguardian.io/r/{monitor_id}/{hmac}"}]}`
}

3. Zweryfikuj

Otwórz stronę w prawdziwej przeglądarce. W ciągu kilku sekund w zakładce CSP Reports pojawi się pierwszy bucket. Jeśli zakładka pozostaje pusta, potwierdzi to też kolejny skan nagłówków — zielona plakietka pojawia się, gdy wykryjemy Twoje CSP wskazujące nasz endpoint.

Tryb Report-Only

Zupełnie nowe CSP? Wdróż je najpierw w trybie Report-Only — nic nie jest faktycznie blokowane, ale naruszenia są raportowane. Zmień nazwę nagłówka, zachowując te same dyrektywy:

Content-Security-Policy-Report-Only: default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}

Co przechowujemy — i czego nie

• Adresy IP klientów są hashowane z solą rotowaną codziennie. Zachowujemy tylko 16-znakowy prefiks.
• Ciągi zapytań i fragmenty są usuwane z każdego adresu URL przed zapisem.
• Ciągi User-Agent są redukowane do rodziny (chrome/firefox/safari/edge/opera/other).
• Każdy bucket zachowuje maksymalnie 3 surowe próbki i 10 dotkniętych identyfikatorów URI dokumentów.
• Retencja: 180 dni (Compliance), 365 dni (Enterprise). Po tym czasie buckety wygasają przez indeks TTL. Ingest CSP wymaga planu Compliance lub wyższego.

Limity i automatyczna pauza

nginx limituje ruch na brzegu do 200 zapytań/s na źródłowy IP. Każdy monitor ma miękki limit 10 000 raportów/minutę; trzy kolejne minuty powyżej progu automatycznie wstrzymują ingest na godzinę i wysyłają e-mail do właściciela monitora. Rotacja adresu URL endpointu to awaryjny przycisk dostępny w zakładce jednym kliknięciem.

Inne typy raportów

Ten sam endpoint przyjmuje raporty NEL (Network Error Logging), Deprecation, Intervention i Expect-CT z Reporting API przeglądarki. Bez dodatkowej konfiguracji — wystarczy dodać je do grupy Report-To.

Endpointy API

Dostęp programistyczny dla pulpitów i CI:

• POST /api/v1/monitors/{id}/csp-reports/enable
• POST /api/v1/monitors/{id}/csp-reports/regenerate
• POST /api/v1/monitors/{id}/csp-reports/disable
• GET /api/v1/monitors/{id}/csp-reports?hours=24
• GET /api/v1/monitors/{id}/csp-reports/{bucket_id}
• GET /api/v1/monitors/{id}/csp-reports/trend/hourly?hours=24
• GET /api/v1/monitors/{id}/csp-reports/recommendations