Monitorowanie aplikacji internetowej za pomocą interfejsu API do raportowania

Korzystaj z interfejsu Reporting API, aby monitorować naruszenia zabezpieczeń, wycofane wywołania interfejsu API i inne kwestie.

Maud Nalpas
Maud Nalpas

Niektóre błędy występują tylko w wersji produkcyjnej. Nie będą one widoczne lokalnie ani w trakcie tworzenia gry, ponieważ zmieniają ją prawdziwi użytkownicy, prawdziwe sieci i prawdziwe urządzenia. Interfejs Reporting API pomaga wychwytywać niektóre z tych błędów, np. naruszenia bezpieczeństwa lub wycofane i wkrótce wycofane wywołania interfejsu API w całej witrynie, i przekazywać je do określonego przez Ciebie punktu końcowego.

Umożliwia ona deklarowanie tego, co chcesz monitorować za pomocą nagłówków HTTP, i jest obsługiwana przez przeglądarkę.

Skonfigurowanie interfejsu Reporting API zapewni Ci spokój ducha, ponieważ gdy użytkownicy napotkają tego typu błędy, będziesz o tym wiedzieć i będziesz mógł je naprawić.

Z tego posta dowiesz się, do czego służy ten interfejs API i jak z niego korzystać. Zaczynamy.

Wersja demonstracyjna i kod

Zapoznaj się z interfejsem API do raportowania, który działa od Chrome 96 i nowszych (Chrome Beta lub Canary od października 2021 r.).

Omówienie

Schemat podsumowujący czynności opisane poniżej, od wygenerowania raportu do uzyskania przez dewelopera dostępu do raportu
Jak są generowane i wysyłane raporty.

Załóżmy, że Twoja witryna site.example ma nagłówek Content-Security-Policy i Document-Policy. Nie wiesz, do czego służą te funkcje? Nie szkodzi. Nadal będziesz rozumieć ten przykład.

decydujesz się monitorować swoją witrynę, aby wiedzieć, kiedy te zasady są naruszane, ale także dlatego, że chcesz mieć oko na wycofane lub wkrótce wycofywane interfejsy API, z których korzysta kod Twojej witryny.

Aby to zrobić, skonfiguruj nagłówek Reporting-Endpoints i w razie potrzeby zmapuj te nazwy punktów końcowych za pomocą dyrektywy report-to w zasadach.

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint

Wystąpił nieoczekiwany błąd, który spowodował naruszenie zasad przez niektórych użytkowników.

Przykłady naruszeń

index.html

<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>

script.js, wczytany przez: index.html

// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
  document
.write('<h1>hi</h1>');
} catch (e) {
  console
.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;

Przeglądarka generuje raport o naruszeniu zasad CSP, raport o naruszeniu zasad dotyczących dokumentu i raport o wycofaniu, które zawierają te problemy.

Po krótkim opóźnieniu (do minuty) przeglądarka wysyła raporty do punktu końcowego skonfigurowanego dla tego typu naruszenia. Raporty są wysyłane poza zakresem przez samą przeglądarkę (nie przez serwer ani witrynę).

Punkty końcowe, które otrzymują te raporty.

Możesz teraz uzyskać dostęp do raportów w tych punktach końcowych i monitorować, co poszło nie tak. Możesz zacząć rozwiązywać problem, który dotyczy użytkowników.

Przykładowy raport

{
 
"age": 2,
 
"body": {
   
"blockedURL": "https://site2.example/script.js",
   
"disposition": "enforce",
   
"documentURL": "https://site.example",
   
"effectiveDirective": "script-src-elem",
   
"originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
   
"referrer": "https://site.example",
   
"sample": "",
   
"statusCode": 200
 
},
 
"type": "csp-violation",
 
"url": "https://site.example",
 
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}

Przypadki użycia i typy raportów

Interfejs Reporting API można skonfigurować tak, aby pomagał w monitorowaniu wielu rodzajów ostrzeżeń i problemów występujących w Twojej witrynie:

Typ raportu Przykład sytuacji, w której wygenerowany zostanie raport
Naruszenie zasad CSP (tylko poziom 3) Na jednej ze stron ustawiono Content-Security-Policy (CSP), ale strona próbuje wczytać skrypt, który nie jest dozwolony przez CSP.
Naruszenie zasad COOP Na stronie masz ustawiony element Cross-Origin-Opener-Policy, ale okno z innej domeny próbuje bezpośrednio wchodzić w interakcję z dokumentem.
Naruszenie zasad COEP Masz ustawiony na stronie element Cross-Origin-Embedder-Policy, ale dokument zawiera element iframe z innej domeny, który nie ma włączonej opcji ładowania dokumentów z innych domen.
Naruszenie zasad dotyczących dokumentów Na stronie znajdują się zasady dotyczące dokumentów, które uniemożliwiają użycie funkcji document.write, ale skrypt próbuje wywołać metodę document.write.
Naruszenie zasad dotyczących uprawnień Strona ma zasady dotyczące uprawnień, które uniemożliwiają używanie mikrofonu, i skrypt, który żąda wejścia audio.
Ostrzeżenie o wycofaniu Strona korzysta z interfejsu API, który został wycofany lub zostanie wycofany. Wywołuje go bezpośrednio lub za pomocą skryptu zewnętrznego najwyższego poziomu.
Interwencja Strona próbuje wykonać czynność, której przeglądarka nie uznaje ze względu na bezpieczeństwo, wydajność lub wygodę użytkowników. Przykład w Chrome: strona używa document.write w powolnych sieciach lub wywołuje navigator.vibrate w ramce z innej domeny, z którą użytkownik nie wchodził jeszcze w interakcję.
Wypadek przeglądarka ulega awarii, gdy Twoja witryna jest otwarta;

Raporty

Jak wyglądają raporty?

Przeglądarka wysyła raporty do skonfigurowanego punktu końcowego. Wysyła ona żądania o takim kształcie:

POST
Content-Type: application/reports+json

Dane tych żądań to lista raportów.

Przykładowa lista raportów

[
 
{
   
"age": 420,
   
"body": {
     
"columnNumber": 12,
     
"disposition": "enforce",
     
"lineNumber": 11,
     
"message": "Document policy violation: document-write is not allowed in this document.",
     
"policyId": "document-write",
     
"sourceFile": "https://site.example/script.js"
   
},
   
"type": "document-policy-violation",
   
"url": "https://site.example/",
   
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
 
},
 
{
   
"age": 510,
   
"body": {
     
"blockedURL": "https://site.example/img.jpg",
     
"destination": "image",
     
"disposition": "enforce",
     
"type": "corp"
   
},
   
"type": "coep",
   
"url": "https://dummy.example/",
   
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
 
}
]

Oto dane, które znajdziesz w każdym z tych raportów:

Pole Opis
age Liczba milisekund między sygnaturą czasową raportu a obecną godziną.
body Dane raportu w postaci ciągu tekstowego w formacie JSON. Pola zawarte w sekcji body raportu są określane przez jego type. ⚠️ Raporty różnych typów mają różne treści. Aby zobaczyć dokładną treść każdego typu raportu, otwórz demo punktu końcowego raportowania i postępuj zgodnie z instrukcjami, aby wygenerować przykładowe raporty.
type Typ raportu, np. csp-violation lub coep.
url Adres dokumentu lub pracownika, z którego wygenerowano raport. Dane wrażliwe, takie jak nazwa użytkownika, hasło i fragment, są usuwane z tego adresu URL.
user_agent Nagłówek User-Agent żądania, na podstawie którego został wygenerowany raport.

Raporty z danymi uwierzytelniającymi

Punkty końcowe raportowania, które mają ten sam origin co strona generująca raport, otrzymują w żądaniach zawierających raporty dane logowania (pliki cookie).

Dane logowania mogą dostarczyć przydatnych dodatkowych informacji o raporcie, np. czy konto danego użytkownika stale powoduje błędy czy też pewna sekwencja działań podejmowanych na innych stronach powoduje raportowanie tej strony.

Kiedy i jak przeglądarka wysyła raporty?

Raporty są dostarczane poza Twoją witryną: to przeglądarka decyduje, kiedy są wysyłane do skonfigurowanych punktów końcowych. Nie ma też możliwości kontrolowania, kiedy przeglądarka wysyła raporty. Przechwytuje je, dodaje do kolejki i wysyła je automatycznie w odpowiednim czasie.

Oznacza to, że podczas korzystania z interfejsu API do raportowania nie trzeba mieć żadnych problemów ze skutecznością.

Raporty są wysyłane z opóźnieniem (maksymalnie minutowym), aby zwiększyć szanse na wysyłanie raportów zbiorczych. Oszczędza to przepustowość, zapewniając szacunek dla połączenia sieciowego użytkownika, co jest szczególnie ważne w przypadku urządzeń mobilnych. Przeglądarka może też opóźnić dostarczenie, jeśli jest zajęta przetwarzaniem zadań o wyższym priorytecie lub jeśli użytkownik korzysta w danym momencie z wolnej lub zatłoczonej sieci.

Problemy z plikami cookie innych firm i własnymi plikami cookie

Raporty generowane z powodu naruszeń lub wycofanych funkcji na Twojej stronie będą wysyłane do skonfigurowanych przez Ciebie punktów końcowych. Obejmuje to naruszenia przez skrypty innych firm działające na Twojej stronie.

Naruszenia lub wycofania, które miały miejsce w ramce iframe z innego źródła osadzonego na Twojej stronie, nie będą zgłaszane do punktów końcowych (przynajmniej domyślnie). Frame iframe może skonfigurować własne raportowanie, a nawet przesyłać raporty do usługi raportowania witryny, czyli do usługi źródeł własnych. To zależy od witryny w ramce. Pamiętaj też, że większość raportów jest generowana tylko wtedy, gdy występuje naruszenie zasad dotyczących strony, a zasady strony i zasady iframe są różne.

Przykład z wycofanymi funkcjami

Jeśli na Twojej stronie skonfigurowano nagłówek Reporting-Endpoints: wycofany interfejs API wywoływany przez skrypty innych firm działające na Twojej stronie będzie zgłaszany do punktu końcowego. Interfejsy API wycofane z użycia wywoływane przez tag iframe umieszczony na stronie nie będą raportowane do punktu końcowego. Raport o wycofaniu zostanie wygenerowany tylko wtedy, gdy serwer iframe ma skonfigurowane punkty końcowe raportowania. Raport zostanie wysłany do punktu końcowego skonfigurowanego przez serwer iframe.
Jeśli na stronie masz skonfigurowaną nagłówek Reporting-Endpoints: interfejsy API wycofane, wywoływane przez skrypty innych firm działające na stronie, będą zgłaszane do punktu końcowego. Wycofany interfejs API wywoływany przez element iframe umieszczony na stronie nie zostanie zgłoszony do punktu końcowego. Raport o wycofaniu zostanie wygenerowany tylko wtedy, gdy serwer iframe skonfigurował raportowanie-punkty końcowe. Będzie on wysyłany do dowolnego punktu końcowego, który został skonfigurowany przez serwer iframe.

Obsługa przeglądarek

Tabela poniżej zawiera podsumowanie obsługi interfejsu API do raportowania w wersji 1, czyli nagłówka Reporting-Endpoints. Obsługa interfejsu Reporting API w wersji 0 (nagłówek Report-To) w przeglądarce jest taka sama, z wyjątkiem jednego typu raportu: nowy interfejs Reporting API nie obsługuje rejestrowania błędów sieci. Szczegółowe informacje znajdziesz w przewodniku po migracji.

Typ raportu Chrome Chrome na iOS Safari Firefox Edge
Naruszenie CSP (tylko na poziomie 3)* ✔ Tak ✔ Tak ✔ Tak ✘ Nie ✔ Tak
Logowanie błędów sieci ✘ Nie ✘ Nie ✘ Nie ✘ Nie ✘ Nie
Naruszenie zasad COOP/COEP ✔ Tak ✘ Nie ✔ Tak ✘ Nie ✔ Tak
Wszystkie inne rodzaje: naruszenie zasad dotyczących dokumentów, wycofanie, interwencja, awaria ✔ Tak ✘ Nie ✘ Nie ✘ Nie ✔ Tak

Ta tabela zawiera tylko podsumowanie obsługi report-to z nowym nagłówkiem Reporting-Endpoints. Jeśli chcesz przejść na Reporting-Endpoints, przeczytaj wskazówki dotyczące migracji raportów CSP.

Korzystanie z interfejsu Reporting API

Wybór miejsca wysyłania raportów

Masz 2 możliwości:

  • Wysyłanie raportów do istniejącej usługi kolektora raportów.
  • Wysyłanie raportów do kolektora raportów, który został utworzony i utrzymywany przez Ciebie.

Opcja 1. Wykorzystanie istniejącej usługi kolektora raportów

Przykłady usług zbierania raportów:

Jeśli znasz inne rozwiązania, otwórz zgłoszenie, aby nas o tym poinformować. Zaktualizujemy ten wpis.

Podczas wybierania zbieracza raportów weź pod uwagę te kwestie: 🧐

  • Czy ten kolektor obsługuje wszystkie typy raportów? Na przykład nie wszystkie rozwiązania do raportowania obsługują raporty COOP/COEP.
  • Czy zgadzasz się na udostępnianie adresów URL aplikacji zewnętrznemu systemowi zbierania raportów? Nawet jeśli przeglądarka usuwa z tych adresów URL poufne informacje, w ten sposób mogą zostać wyciek. Jeśli to jest zbyt ryzykowne dla Twojej aplikacji, uruchom własny punkt końcowy raportowania.

Opcja 2. Utwórz i używaj własnego zbieracza raportów

Zbudowanie własnego serwera, który będzie otrzymywać raporty, nie jest takie proste. Na początek możesz użyć naszego lekkiego szablonu. Została utworzona za pomocą szybkiej transmisji i może otrzymywać oraz wyświetlać raporty.

  1. Otwórz szablonowy zbiór raportów.

  2. Kliknij Remix to Edit (Zmiksuj do edycji), aby umożliwić edycję projektu.

  3. Masz już swojego klona. Możesz go dostosować do własnych potrzeb.

Jeśli nie używasz szablonu i tworzysz własny serwer od podstaw:

  • Aby rozpoznać żądania wysyłane przez przeglądarkę do punktu końcowego, sprawdź żądania POST z wartością Content-Type równą application/reports+json.
  • Jeśli punkt końcowy znajduje się w innej domenie niż Twoja witryna, upewnij się, że obsługuje żądania wstępne CORS.

Opcja 3. Połącz opcje 1 i 2

Możesz zlecić to konkretnemu dostawcy, który zajmie się niektórymi typami raportów, a w przypadku innych rozwiązań wewnętrzne.

W tym przypadku ustaw wiele punktów końcowych w ten sposób:

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

Konfigurowanie nagłówka Reporting-Endpoints

Ustaw nagłówek odpowiedzi Reporting-Endpoints. Jego wartość musi być jedną lub wieloma rozdzielonymi przecinkami parami klucz-wartość:

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Jeśli przechodzisz ze starszego interfejsu Reporting API na nowy interfejs Reporting API, warto ustawić zarówno Reporting-Endpoints, jak i Report-To. Szczegółowe informacje znajdziesz w przewodniku po migracji. Jeśli raportujesz naruszenia zasad Content-Security-Policy tylko za pomocą dyrektywy report-uri, zapoznaj się z instrukcjami migracji raportowania CSP.

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: ...

Klucze (nazwy punktów końcowych)

Każdy klucz może mieć dowolną nazwę, np. main-endpoint lub endpoint-1. Możesz ustawić różne nazwane punkty końcowe dla różnych typów raportów, np. my-coop-endpointmy-csp-endpoint. Dzięki temu możesz kierować raporty do różnych punktów końcowych w zależności od ich typu.

Jeśli chcesz otrzymywać raporty o interwencji, wycofaniu lub awariach, ustaw punkt końcowy o nazwie default.

Jeśli nagłówek Reporting-Endpoints nie definiuje punktu końcowego default, raporty tego typu nie będą wysyłane (chociaż będą generowane).

Wartości (adresy URL)

Każda wartość to wybrany przez Ciebie adres URL, pod który będą wysyłane raporty. Adres URL, który należy tu ustawić, zależy od tego, co wybierzesz w kroku 1.

Adres URL punktu końcowego:

Przykłady

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

Możesz wtedy używać każdego nazwanego punktu końcowego w odpowiedniej polityce lub jednego punktu końcowego we wszystkich zasadach.

Gdzie ustawić nagłówek?

W nowym interfejsie Reporting API, który jest opisany w tym poście, raporty są ograniczone do dokumentów. Oznacza to, że w przypadku jednego źródła różne dokumenty, takie jak site.example/page1site.example/page2, mogą wysyłać raporty do różnych punktów końcowych.

Aby otrzymywać raporty o naruszeniach lub wycofaniu się na dowolnej stronie witryny, ustaw nagłówek jako oprogramowanie pośredniczące we wszystkich odpowiedziach.

Oto przykład w Express:

const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;

app
.use(function (request, response, next) {
 
// Set up the Reporting API
  response
.set(
   
'Reporting-Endpoints',
   
`main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
 
);
 
next();
});

Edytowanie zasad

Po skonfigurowaniu nagłówka Reporting-Endpoints dodaj do każdego nagłówka zasad dyrektywę report-to, jeśli chcesz otrzymywać raporty o naruszeniach. Wartość report-to powinna być jedną z nazwanych przez Ciebie nazwanych końcówek.

Możesz używać wielu punktów końcowych na potrzeby wielu zasad lub używać różnych punktów końcowych we wszystkich zasadach.

W przypadku każdej zasady wartość parametru report-to powinna być jednym z skonfigurowanych przez Ciebie nazwanych punktów końcowych.

report-to nie jest wymagany w przypadku raportów o wycofaniu, interwencjiawarii. Te raporty nie są powiązane z żadnymi zasadami. Są one generowane, o ile tylko masz skonfigurowany punkt końcowy default i są wysyłane do tego punktu końcowego default.

Przykład

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint

Przykładowy kod

Aby pokazać to wszystko w kontekście, poniżej znajduje się przykładowy serwer węzłów, który korzysta z usługi Express i łączy wszystkie elementy omawiane w tym artykule. Znajdziesz w nim informacje o konfigurowaniu raportów pod kątem różnych typów raportów oraz o wyświetlaniu wyników.

Debugowanie konfiguracji raportowania

celowe generowanie raportów;

Podczas konfigurowania interfejsu API raportowania prawdopodobnie musisz celowo naruszyć swoje zasady, aby sprawdzić, czy raporty są generowane i wysyłane zgodnie z oczekiwaniami. Aby zobaczyć przykładowy kod, który narusza zasady i wywołuje inne nieprawidłowości, które spowodują wygenerowanie raportów wszystkich typów, obejrzyj prezentację.

Oszczędzaj czas

Raporty mogą być wysyłane z opóźnieniem – około minuty, co jest długim czasem podczas debugowania. 😴 Na szczęście podczas debugowania w Chrome możesz użyć flagi --short-reporting-delay, aby otrzymywać raporty zaraz po ich wygenerowaniu.

Aby włączyć tę flagę, uruchom w terminalu to polecenie:

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

Korzystanie z Narzędzi deweloperskich

W Chrome możesz wyświetlić w Narzędziach dla deweloperów raporty, które zostały lub zostaną wysłane.

Od października 2021 r. ta funkcja jest eksperymentalna. Aby z niej skorzystać, wykonaj te czynności:

  1. Użyj Chrome w wersji 96 lub nowszej (możesz to sprawdzić, wpisując w przeglądarce chrome://version)
  2. Wpisz lub wklej chrome://flags/#enable-experimental-web-platform-features na pasku adresu w Chrome.
  3. Kliknij Włączono.
  4. Ponownie uruchom przeglądarkę.
  5. Otwórz Narzędzia deweloperskie w Chrome.
  6. W Narzędziach deweloperskich w Chrome otwórz Ustawienia. W sekcji Eksperymenty kliknij Włącz panel interfejsu Reporting API w panelu Aplikacje.
  7. Załaduj ponownie Narzędzia deweloperskie.
  8. Załaduj ponownie stronę. Raporty wygenerowane przez stronę, w której są otwarte Narzędzia deweloperskie, będą widoczne w panelu Aplikacja w Narzędziach deweloperskich w Chrome, w sekcji Interfejs Reporting API.
Zrzut ekranu pokazujący listę raportów w Narzędziach deweloperskich
W Narzędziach deweloperskich w Chrome wyświetlane są raporty wygenerowane na Twojej stronie i ich stan.

Stan raportu

Kolumna Stan informuje, czy raport został wysłany.

Stan Opis
Success Przeglądarka wysłała raport, a punkt końcowy odpowiedział kodem powodzenia (200 lub inny kod odpowiedzi o powodzeniu 2xx).
Pending Przeglądarka próbuje obecnie wysłać raport.
Queued Raport został wygenerowany i przeglądarka nie próbuje go wysyłać. Raport ma postać Queued w jednym z tych 2 przypadków:
  • Raport jest nowy, a przeglądarka czeka na sprawdzenie, czy pojawi się kolejny raport, zanim spróbuje go wysłać.
  • Raport nie jest nowy. Przeglądarka próbowała już go wysłać, ale się nie udało, więc czeka na kolejną próbę.
MarkedForRemoval Po kilku próbach (Queued) przeglądarka przestała próbować wysłać raport i wkrótce usunie go z listy raportów do wysłania.

Raporty są usuwane po pewnym czasie, niezależnie od tego, czy zostały wysłane.

Rozwiązywanie problemów

Czy raporty nie są tworzone lub wysyłane do Twojego punktu końcowego zgodnie z oczekiwaniami? Oto kilka wskazówek, które pomogą Ci rozwiązać ten problem.

Raporty nie są generowane

Raporty wyświetlane w Narzędziach deweloperskich zostały wygenerowane prawidłowo. Jeśli oczekiwanego raportu nie widać na tej liście:

  • Sprawdź report-to w swoich zasadach. Jeśli będzie ono błędnie skonfigurowane, raport nie zostanie wygenerowany. Aby rozwiązać ten problem, przejdź do sekcji Edytowanie zasad. Dodatkowym sposobem na rozwiązanie tego problemu jest sprawdzenie konsoli Narzędzi deweloperskich w Chrome: jeśli w konsoli pojawi się błąd związany z oczekiwanym naruszeniem, oznacza to, że zasady są prawdopodobnie prawidłowo skonfigurowane.
  • Pamiętaj, że na tej liście będą widoczne tylko raporty wygenerowane dla otwartego w DevTools dokumentu. Przykład: jeśli Twoja witryna site1.example umieszcza element iframe site2.example, który narusza zasady, i generuje raport, raport ten pojawi się w Narzędziach deweloperskich tylko wtedy, gdy otworzysz element iframe w osobnym oknie i otworzysz w nim elementy deweloperskie.

Raporty są generowane, ale nie są wysyłane i odbierane

Co zrobić, jeśli raport jest widoczny w Narzędziach dla programistów, ale nie jest odbierany przez punkt końcowy?

  • Używaj krótkich opóźnień. Być może nie widzisz raportu, ponieważ nie został on jeszcze wysłany.
  • Sprawdź konfigurację nagłówka Reporting-Endpoints. Jeśli wystąpi problem, raport, który został wygenerowany prawidłowo, nie zostanie wysłany. W tym przypadku stan zgłoszenia w Narzędziach dla programistów pozostanieQueued (może się ono zmienić na Pending, a potem szybko znów na Queued, gdy zostanie podjęta próba dostarczenia). Oto kilka typowych błędów, które mogą to powodować:

  • Punkt końcowy jest używany, ale nie jest skonfigurowany. Przykład:

Kodowanie z błędem
 Document-Policy: document-write=?0;report-to=endpoint-1;
 
Reporting-Endpoints: default="https://reports.example/default"

Zgłoszenia naruszeń zasad dotyczących dokumentów powinny być wysyłane na adres endpoint-1, ale ta nazwa punktu końcowego nie jest skonfigurowana w Reporting-Endpoints.

  • Brak punktu końcowego default. Niektóre typy raportów, np. raporty o wycofaniu i interwencji, będą wysyłane tylko do punktu końcowego o nazwie default. Więcej informacji znajdziesz w artykule Konfigurowanie nagłówka Reporting-Endpoints.

  • Sprawdź składnię nagłówków zasad pod kątem problemów, np. brakujących cudzysłowów. Zobacz szczegóły

  • Sprawdź, czy punkt końcowy może obsługiwać przychodzące żądania.

    • Upewnij się, że punkt końcowy obsługuje żądania wstępne CORS. Jeśli nie, nie będzie ono otrzymywać raportów.

    • Przetestuj działanie punktu końcowego. Zamiast ręcznego generowania raportów możesz emulować przeglądarkę, wysyłając do punktu końcowego żądania, które wyglądają tak samo jak te wysyłane przez przeglądarkę. Wykonaj zapytanie:

    curl --header "Content-Type: application/reports+json" \
     
    --request POST \
     
    --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \
      YOUR_ENDPOINT

    Punkt końcowy powinien zwrócić kod powodzenia (200 lub inny kod odpowiedzi powodzenia 2xx). Jeśli tego nie zrobi, oznacza to, że wystąpił problem z jego konfiguracją.

Tylko raporty

Nagłówki zasad -Report-Only i Reporting-Endpoints działają ze sobą.

Punkty końcowe skonfigurowane w Reporting-Endpoints i wyszczególnione w polu report-toContent-Security-Policy, Cross-Origin-Embedder-PolicyCross-Origin-Opener-Policy będą otrzymywać raporty o naruszeniu tych zasad.

Punkty końcowe skonfigurowane w Reporting-Endpoints można też określić w polu report-to w Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only i Cross-Origin-Opener-Policy-Report-Only. Otrzymają oni też raporty o naruszeniu tych zasad.

W obu przypadkach wysyłane są raporty, ale nagłówki -Report-Only nie egzekwują zasad: nic się nie zepsuje ani nie zostanie zablokowane, ale otrzymasz raporty o tym, co byłoby zepsute lub zablokowane.

ReportingObserver

Interfejs ReportingObserver JavaScript API pomoże Ci obserwować ostrzeżenia po stronie klienta.

ReportingObserver i nagłówek Reporting-Endpoints generują raporty, które wyglądają tak samo, ale mają nieco inne zastosowania.

Użyj ReportingObserver, jeśli:

  • Chcesz tylko monitorować wycofane elementy lub interwencje w zakresie przeglądarek. ReportingObserver wyświetla ostrzeżenia po stronie klienta, np. o wycofaniach i interwencjach w przeglądarce, ale w odróżnieniu od Reporting-Endpoints nie obejmuje innych typów raportów, np. o naruszeniu zasad CSP lub zasad COOP/COEP.
  • Musisz reagować na te naruszenia w czasie rzeczywistym. ReportingObserver umożliwia dołączenie wywołania zwrotnego do zdarzenia naruszenia.
  • Chcesz dołączyć do raportu dodatkowe informacje, aby ułatwić debugowanie, za pomocą niestandardowego wywołania zwrotnego.

Kolejną różnicą jest to, że usługa ReportingObserver jest konfigurowana tylko po stronie klienta. Możesz jej używać nawet wtedy, gdy nie masz kontroli nad nagłówkami po stronie serwera i nie możesz ustawić zasady Reporting-Endpoints.

Więcej informacji

Baner powitalny autorstwa Nine Koepfer / @enka80 na Unsplash, zmodyfikowany. Dziękujemy Ianowi Clellandowi, Eiji Kitamurze i Milici Mihajlija za sprawdzenie i zaproponowanie poprawek do tego artykułu.