Ta strona została przetłumaczona przez Cloud Translation API.

Monitorowanie aplikacji internetowej za pomocą interfejsu API do raportowania

Interfejs API do raportowania umożliwia monitorowanie naruszeń zabezpieczeń, wycofanych wywołań interfejsu API itp.

Maud Nalpas

Niektóre błędy występują tylko w wersji produkcyjnej. Nie będą one widoczne lokalnie ani w trakcie tworzenia aplikacji, ponieważ wpływają na działanie gry prawdziwi użytkownicy, rzeczywiste sieci i rzeczywiste urządzenia. Interfejs Reporting API pomaga wychwytywać niektóre z tych błędów, np. naruszenia zabezpieczeń czy wycofane, a wkrótce wycofane wywołania interfejsu API w Twojej witrynie, i przesyła je do określonego przez Ciebie punktu końcowego.

Przy użyciu nagłówków HTTP możesz zadeklarować, co chcesz monitorować. Funkcja ta jest obsługiwana przez przeglądarkę.

Skonfigurowanie interfejsu API do raportowania zapewnia użytkownikom spokój ducha, ponieważ takie błędy będą Cię wiedzieć, a Ty będziesz wiedzieć, że możesz je naprawić.

Z tego posta dowiesz się, jakie możliwości daje ten interfejs API i jak z niego korzystać. Zaczynamy!

Demonstracja i kod

Zobacz, jak działa interfejs API do raportowania w wersji Chrome 96 i nowszej (wersja beta lub Canary – stan na październik 2021 r.).

Przegląd

Diagram podsumowujący poniższe kroki – od wygenerowania raportu po dostęp dewelopera — Jak raporty są generowane i wysyłane.

Załóżmy, że Twoja witryna site.example zawiera zasady zabezpieczeń zawartości i dokumentów. Nie wiesz, do czego służą? Nie szkodzi, nadal możesz zrozumieć ten przykład.

Postanawiasz monitorować witrynę, żeby wiedzieć, kiedy są naruszane te zasady, ale też dlatego, że chcesz zwrócić uwagę na wycofywane lub wkrótce wycofane interfejsy API, z których może korzystać Twoja baza kodu.

W tym celu 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

Zdarzy się coś nieprzewidzianego i naruszenie tych zasad w przypadku niektórych użytkowników.

Przykładowe naruszenia

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, wczytane 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 raporty dotyczące naruszeń zasad CSP, naruszeń zasad dotyczących dokumentów i wycofania, które rejestrują te problemy.

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

Punkty końcowe otrzymują te raporty.

Możesz teraz przeglądać raporty dotyczące tych punktów końcowych i sprawdzać, co poszło nie tak. Możesz zacząć rozwiązywać problem, który dotyczy Twoich 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ł Ci monitorować różne rodzaje interesujących ostrzeżeń i problemów, które pojawiają się w Twojej witrynie:

Typ raportu	Przykład sytuacji, w której zostanie wygenerowany raport
Naruszenie zasad CSP (tylko na poziomie 3)	Na jednej ze stron ustawiono `Content-Security-Policy` (CSP), ale strona próbuje wczytać skrypt, który nie jest dozwolony przez Twojego dostawcę CSP.
Naruszenie zasad COOP	Na stronie masz ustawiony `Cross-Origin-Opener-Policy`, ale okno z innej domeny próbuje wejść w bezpośrednią interakcję z dokumentem.
Naruszenie zasad COEP	Na stronie jest ustawiony element `Cross-Origin-Embedder-Policy`, ale dokument zawiera element iframe z innych domen, który nie ma włączonej opcji ładowania przez dokumenty z innych domen.
Naruszenie zasad dotyczących dokumentów	Strona ma zasady dotyczące dokumentu, które uniemożliwiają użycie polecenia `document.write`, ale skrypt próbuje wywołać `document.write`.
Naruszenie zasad dotyczących uprawnień	Strona ma zasady uprawnień, które uniemożliwiają korzystanie z mikrofonu, oraz 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 ją bezpośrednio lub przez skrypt zewnętrzny najwyższego poziomu.
Interwencja	Strona próbuje zrobić coś, czego przeglądarka nie powinna uwzględniać ze względów bezpieczeństwa, wydajności lub wygody użytkownika. Przykład w Chrome: strona używa polecenia `document.write` w powolnych sieciach lub wywołuje `navigator.vibrate` w ramce z innych domen, z którą użytkownik jeszcze nie wchodził w interakcję.
Wypadek	Przeglądarka ulega awarii, gdy witryna jest otwarta.

Raporty

Jak wyglądają raporty?

Przeglądarka wysyła raporty do skonfigurowanego punktu końcowego. Wysyła żądania, które wyglądają tak:

POST
Content-Type: application/reports+json

Ładunkiem tych żądań jest 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 czasem bieżącym.
`body`	Rzeczywiste dane raportu zserializowane w ciągu znaków JSON. Pola zawarte w kolumnie `body` raportu określają jego `type`. ⚠️ Raporty różnego rodzaju mają różne treści. Aby zobaczyć dokładną treść poszczególnych typów raportów, sprawdź punkt końcowy raportowania demograficznego i postępuj zgodnie z instrukcjami, aby wygenerować przykładowe raporty.
`type`	Typ raportu, np. `csp-violation` lub `coep`.
`url`	Adres dokumentu lub instancji roboczej, na podstawie której został wygenerowany raport. Dane poufne, 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 wygenerowano raport.

Raporty z danymi uwierzytelniającymi

Punkty końcowe raportowania o tym samym pochodzeniu co strona generująca raport otrzymują dane uwierzytelniające (pliki cookie) w żądaniach zawierających raporty.

Dane logowania mogą dostarczać przydatny dodatkowy kontekst raportu, np. czy na koncie użytkownika regularnie pojawiają się błędy lub czy konkretna sekwencja działań podjętych na innych stronach powoduje wygenerowanie raportu na tej stronie.

Kiedy i w jaki sposób przeglądarka wysyła raporty?

Raporty są dostarczane poza witryną: o tym, kiedy są wysyłane do skonfigurowanych punktów końcowych, decyduje przeglądarka. Nie ma też sposobu na kontrolowanie, kiedy przeglądarka wysyła raporty. Automatycznie przechwytuje, dodaje do kolejki i wysyła je w odpowiednim czasie.

Oznacza to, że podczas korzystania z interfejsu API do raportowania występują niewielkie lub żadne problemy z wydajnością.

Raporty są wysyłane z opóźnieniem (do minuty), co zwiększa szanse na wysyłanie raportów partiami. Oszczędza to przepustowość, aby zapewnić zgodność z wymaganiami 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 podczas przetwarzania zadań o wyższym priorytecie lub jeśli użytkownik korzysta w tym samym czasie z wolnej lub przeciążonej sieci.

Problemy własne i własne

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

Naruszenia i wycofania, które wystąpiły w elementach iframe z innych domen umieszczonych na Twojej stronie, nie będą zgłaszane do punktów końcowych (a przynajmniej nie domyślnie). Element iframe może skonfigurować własne raporty, a nawet przesyłać raporty do Twojej witryny (własnej usługi raportowania), ale to zależy od witryny w ramce. Pamiętaj też, że większość raportów jest generowanych tylko w przypadku naruszenia zasad strony, a zasady obowiązujące na stronie i zasady dotyczące elementu iframe różnią się od siebie.

Przykład z wycofanymi elementami

Jeśli na swojej stronie masz skonfigurowany nagłówek Reporting-Endpoints: wycofany interfejs API wywoływany przez skrypty innych firm uruchomione na Twojej stronie zostanie zgłoszony do Twojego punktu końcowego. Wycofany interfejs API wywoływany przez element iframe umieszczony na stronie nie zostanie zgłoszony do Twojego punktu końcowego. Raport o wycofaniu zostanie wygenerowany tylko wtedy, gdy serwer iframe skonfigurował punkty końcowe raportowania, a zostanie on wysłany do punktu końcowego skonfigurowanego przez serwer elementu iframe. — Jeśli na stronie jest skonfigurowany nagłówek Reporting-Endpoints: wycofany interfejs API wywoływany przez zewnętrzne skrypty uruchomione na Twojej stronie zostanie zgłoszony do Twojego punktu końcowego. Wycofany interfejs API wywoływany przez element iframe umieszczony na stronie nie zostanie zgłoszony do Twojego punktu końcowego. Raport o wycofaniu zostanie wygenerowany tylko wtedy, gdy serwer iframe skonfigurował punkty końcowe raportowania, a zostanie on wysłany do punktu końcowego skonfigurowanego przez serwer elementu iframe.

Obsługiwane przeglądarki

W tabeli poniżej znajdziesz podsumowanie dotyczące obsługi przez przeglądarki interfejsu API do raportowania w wersji 1, który zawiera nagłówek Reporting-Endpoints. Obsługa interfejsu Reporting API w wersji 0 (nagłówek Report-To) przez przeglądarki jest taka sama z wyjątkiem jednego typu raportu: Network Error Logging nie jest obsługiwany w nowym interfejsie Reporting API. Szczegółowe informacje znajdziesz w przewodniku po migracji.

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

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

Korzystanie z interfejsu API do raportowania

Zdecyduj, dokąd mają być wysyłane raporty

Masz 2 możliwości:

Wysyłaj raporty do istniejącej usługi kolektora raportów.
Wysyłanie raportów do kolektora raportów, który samodzielnie utworzysz i który będziesz obsługiwać.

Opcja 1. Użyj istniejącej usługi kolektora raportów

Przykłady usług gromadzenia raportów:

Jeśli znasz inne rozwiązania, otwórz problem, aby nas o tym poinformować, a zaktualizujemy ten post.

Oprócz ceny weź pod uwagę te kwestie: 🧐

Czy ten kolektor obsługuje wszystkie typy raportów? Na przykład nie wszystkie punkty końcowe do raportowania obsługują raporty COOP/COEP.
Czy możesz udostępniać adresy URL swojej aplikacji zewnętrznej firmie zbierającej raporty? Nawet jeśli przeglądarka usuwa poufne informacje z tych adresów URL, mogą one zostać w ten sposób wyciek. Jeśli wydaje się to zbyt ryzykowne dla Twojej aplikacji, skorzystaj z własnego punktu końcowego raportowania.

Opcja 2. Utwórz i obsługuj własny kolektor raportów

Stworzenie własnego serwera, który będzie odbierać raporty, nie jest aż tak proste. Na początek możesz rozwidleć naszą lekką płytkę gotową. Jest oparta na usłudze Express i może odbierać i wyświetlać raporty.

Przejdź do schematu kolektorów raportów.
Aby umożliwić edytowanie projektu, kliknij Zremiksuj do edycji.
Masz już swojego klon. Możesz go dostosować do swoich potrzeb.

Jeśli nie korzystasz z szablonu i tworzysz własny serwer od podstaw:

Sprawdź, czy nie ma żądań POST z Content-Type o wartości application/reports+json, by rozpoznać żądania raportów wysyłane przez przeglądarkę do punktu końcowego.
Jeśli punkt końcowy znajduje się w innym punkcie początkowym niż Twoja witryna, upewnij się, że obsługuje żądania procesów wstępnych CORS.

Opcja 3. Połącz opcje 1 i 2

Niektóre typy raportów możesz obsługiwać samodzielnie, ale dla innych masz własne rozwiązanie.

W takim 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"

Skonfiguruj nagłówek `Reporting-Endpoints`

Ustaw nagłówek odpowiedzi Reporting-Endpoints. Jego wartość musi być 1 lub ciągiem rozdzielonych przecinkami par 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, warto ustawić zarówno Reporting-Endpoints, jak i Report-To. Szczegółowe informacje znajdziesz w przewodniku po migracji. Jeśli do zgłaszania naruszeń zasad Content-Security-Policy używasz tylko dyrektywy report-uri, zapoznaj się z instrukcjami migracji raportów 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 być 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-endpoint, my-csp-endpoint. Pozwala to kierować raporty do różnych punktów końcowych w zależności od ich typu.

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

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

Ważne: wbrew swojej nazwie default nie jest zastępczym punktem końcowym. Jeśli na przykład skonfigurujesz report-to my-endpoint w domenie Document-Policy i pominiesz definiowanie my-endpoint w usłudze Reporting-Endpoints, raporty o naruszeniach (Document-Policy) zostaną wygenerowane, ale nie będą wysyłane, ponieważ przeglądarka nie wie, dokąd je przekierować.

Wartości (adresy URL)

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

URL punktu końcowego:

Musi zaczynać się od ukośnika (/). Ścieżki względne nie są obsługiwane.
Mogą być pochodzące z innych domen, ale w takim przypadku dane logowania nie są wysyłane z raportami.

Przykłady

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

Następnie możesz używać każdego nazwanego punktu końcowego w odpowiedniej zasadzie lub jednego punktu końcowego we wszystkich zasadach.

Gdzie ustawić nagłówek?

W nowym interfejsie Reporting API, omówionym w tym poście, raporty są ograniczone do dokumentów. Oznacza to, że w przypadku danego źródła różne dokumenty, np. site.example/page1 i site.example/page2, mogą wysyłać raporty do różnych punktów końcowych.

Aby otrzymywać raporty o naruszeniach lub wycofanych elementach witryny na dowolnej stronie, 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();
});

Uwaga: różni się to od starszej wersji interfejsu Reporting API (nagłówek Report-To), w której można ustawić punkt końcowy „ambient” dla jednej strony i automatycznie otrzymywać raporty dotyczące dowolnej strony w tym samym źródle. Jeśli przechodzisz ze starszego interfejsu Reporting API na nowy, zapoznaj się z przewodnikiem po migracji.

Edytuj zasady

Po skonfigurowaniu nagłówka Reporting-Endpoints dodaj dyrektywę report-to do każdego nagłówka zasad, w przypadku którego chcesz otrzymywać raporty o naruszeniach. Wartość report-to powinna być jednym ze skonfigurowanych nazwanych punktów końcowych.

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

Dla każdej zasady wartość report-to powinna być jednym ze skonfigurowanych nazwanych punktów końcowych.

Parametr report-to nie jest potrzebny do raportowania wycofywania, interwencji i raportów o awariach. Raporty te nie są powiązane z żadnymi zasadami. Aby były generowane, musisz mieć skonfigurowany punkt końcowy default i wysyłać go 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

Ostrzeżenie: prawidłowe uzyskanie składni report-to może być trudne, ponieważ nie wszystkie zasady korzystają z tej samej struktury nagłówka. W zależności od zasady prawidłową składnią może być report-to=main-endpoint lub report-to main-endpoint. Otwórz prezentację, aby zobaczyć przykłady kodu.

Przykładowy kod

Aby pokazać wszystkie te informacje w kontekście, poniżej przedstawiamy przykładowy serwer węzłów, który korzysta z usługi Express i łączy wszystkie elementy omówione w tym artykule. Omawia w nim, jak skonfigurować raportowanie dla kilku różnych typów raportów, a następnie wyświetla wyniki.

Debugowanie konfiguracji raportowania

Celowe generowanie raportów

Podczas konfigurowania interfejsu Reporting API prawdopodobnie musisz celowo naruszać swoje zasady, aby sprawdzić, czy raporty są generowane i wysyłane zgodnie z oczekiwaniami. Aby zobaczyć przykładowy kod, który narusza zasady i robi inne szkodliwe działania, które będą generować raporty różnego typu, obejrzyj prezentację.

Nie trać czasu

Raporty mogą być wysyłane z opóźnieniem – około minuty, czyli długi czas debugowania. 😴 Na szczęście podczas debugowania w Chrome możesz użyć flagi --short-reporting-delay, aby otrzymywać raporty od razu 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 użyć Narzędzi deweloperskich, aby wyświetlić raporty, które zostały wysłane lub zostaną wysłane.

Od października 2021 r. ta funkcja jest eksperymentalna. Aby go użyć, wykonaj te czynności:

Używaj Chrome w wersji 96 lub nowszej (sprawdź, wpisując w przeglądarce chrome://version)
Wpisz lub wklej chrome://flags/#enable-experimental-web-platform-features na pasku adresu URL w Chrome.
Kliknij Włączone.
Ponownie uruchom przeglądarkę.
Otwórz Narzędzia deweloperskie w Chrome.
W Narzędziach deweloperskich w Chrome otwórz Ustawienia. W sekcji Eksperymenty kliknij Włącz panel interfejsu API do raportowania w panelu Aplikacja.
Załaduj ponownie Narzędzia deweloperskie.
Załaduj ponownie stronę. Raporty generowane przez stronę, na której są otwarte Narzędzia deweloperskie, znajdują się w panelu Aplikacja w Narzędziach deweloperskich w Chrome, w sekcji Reporting API.

Zrzut ekranu z listą raportów w Narzędziach deweloperskich — Narzędzia deweloperskie w Chrome wyświetlają 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 wysłał w odpowiedzi kod powodzenia (`200` lub inny kod odpowiedzi powodzenia `2xx`).
`Pending`	Przeglądarka podejmuje obecnie próbę wysłania raportu.
`Queued`	Raport został wygenerowany, a przeglądarka obecnie nie próbuje go wysłać. Raport ma postać `Queued` w jednym z tych 2 przypadków: Raport jest nowy, a przed próbą jego wysłania przeglądarka czeka, aby sprawdzić, czy pojawi się więcej raportów. Raport nie jest nowy. Przeglądarka próbowała już wysłać ten raport, ale zakończyła się niepowodzeniem i czeka, zanim spróbujesz ponownie.
`MarkedForRemoval`	Po pewnym czasie ponawiania prób (`Queued`) przeglądarka przestała próbować wysyłać raport i wkrótce usunie go z listy raportów do wysłania.

Raporty są usuwane po pewnym czasie, bez względu na to, czy zostały wysłane.

Ważne: stan Queued nie zawsze dostarcza przydatnych informacji, ponieważ nie wskazuje dokładnie, czy wysyłanie zakończyło się niepowodzeniem, czy też nie podjęto jeszcze próby. Korzystanie z krótkich opóźnień w raportowaniu pomaga: raport, który w tym przypadku pozostaje Queued, prawdopodobnie oznacza błąd wysyłania.

Rozwiązywanie problemów

Czy raporty nie są generowane lub wysyłane do punktu końcowego zgodnie z oczekiwaniami? Oto kilka wskazówek, jak rozwiązać ten problem.

Raporty nie są generowane

Raporty, które pojawiają się w Narzędziach deweloperskich, zostały prawidłowo wygenerowane. Jeśli oczekiwanego raportu nie ma na tej liście:

Sprawdź zasady report-to. Jeśli konfiguracja jest nieprawidłowa, raport nie zostanie wygenerowany. Aby rozwiązać ten problem, przejdź do sekcji Edytowanie zasad. Dodatkowym sposobem rozwiązania tego problemu jest sprawdzenie konsoli Narzędzi deweloperskich w Chrome: jeśli w konsoli pojawi się błąd dotyczący oczekiwanego naruszenia, oznacza to, że zasada jest prawdopodobnie nieprawidłowo skonfigurowana.
Pamiętaj, że na tej liście pojawią się tylko raporty wygenerowane dla dokumentu, w którym są otwarte Narzędzia deweloperskie. Na przykład: jeśli w Twojej witrynie site1.example umieszczono element iframe site2.example, który narusza zasady, i generuje raport, ten raport pojawi się w Narzędziach deweloperskich tylko wtedy, gdy otworzysz element iframe w osobnym oknie i w tym oknie otworzysz Narzędzia deweloperskie.

Raporty są generowane, ale nie są wysyłane lub nie.

Co zrobić, jeśli widzisz raport w Narzędziach deweloperskich, ale punkt końcowy go nie otrzymuje?

Ważne: raport jest wysyłany poza określoną przeglądarkę, a nie przez konkretną witrynę, dlatego żądania POST zawierające raporty nie są wyświetlane w panelu Sieć w Narzędziach dla deweloperów.

Stosuj krótkie opóźnienia. Nie widzisz raportu, bo nie został on jeszcze wysłany.
Sprawdź konfigurację nagłówka Reporting-Endpoints. Jeśli są z nim jakieś problemy, raporty, które zostały wygenerowane prawidłowo, nie zostaną wysłane. W tym przypadku w Narzędziach deweloperskich stan raportu to Queued (może przeskoczyć do Pending, a następnie szybko wrócić do Queued po próbie dostarczenia). Oto kilka typowych błędów, które mogą ją spowodować:
Punkt końcowy jest używany, ale nie został skonfigurowany. Przykład:

Błędny kod

 Document-Policy: document-write=?0;report-to=endpoint-1;
 Reporting-Endpoints: default="https://reports.example/default"

Raporty o naruszeniu zasad dotyczących dokumentów należy wysyłać do usługi 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 interwencjach, będą wysyłane tylko do punktu końcowego o nazwie default. Więcej informacji znajdziesz w artykule Konfigurowanie nagłówka Reporting-Endpoints (Punkty końcowe raportowania).
Poszukaj problemów ze składnią nagłówków zasad, na przykład brakujących cudzysłowów. Zobacz szczegóły

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

Upewnij się, że punkt końcowy obsługuje żądania procesów wstępnych CORS. Jeśli tak nie jest, nie może otrzymywać raportów.
Przetestuj zachowanie punktu końcowego. W tym celu zamiast generować raporty ręcznie, możesz emulować przeglądarkę, wysyłając do punktu końcowego żądania, które wyglądają tak, jak wysyłałaby ją przeglądarka. 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 odpowiedzieć kodem powodzenia (200 lub innym kodem powodzenia 2xx). W przeciwnym razie występuje problem z jego konfiguracją.

Powiązane mechanizmy zgłaszania

Tylko raportowanie

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

Punkty końcowe skonfigurowane w Reporting-Endpoints i określone w polu report-to w Content-Security-Policy, Cross-Origin-Embedder-Policy i Cross-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 także raporty o naruszeniu tych zasad.

Chociaż raporty są wysyłane w obu przypadkach, nagłówki -Report-Only nie egzekwują zasad: nic nie zostanie uszkodzone ani zablokowane, ale będziesz otrzymywać raporty o tym, co zostało uszkodzone lub zablokowane.

Uwaga: jeśli używasz nagłówka -Report-Only i skonfigurowano punkty końcowe raportowania za pomocą starszego nagłówka Report-To, w miarę możliwości przejdź na Reporting-Endpoints. Więcej informacji znajdziesz w przewodniku po migracji.

`ReportingObserver`

Interfejs ReportingObserver JavaScript API ułatwia obserwowanie ostrzeżeń po stronie klienta.

ReportingObserver i nagłówek Reporting-Endpoints generują raporty, które wyglądają tak samo, ale różnią się nieco w zależności od zastosowania.

Użyj operatora ReportingObserver, jeśli:

Chcesz tylko monitorować wycofywania lub działania przeglądarki. ReportingObserver wyświetla ostrzeżenia po stronie klienta, takie jak informacje o wycofaniach działań i interwencjach przeglądarki, ale w przeciwieństwie do Reporting-Endpoints nie rejestruje żadnych innych typów raportów, takich jak naruszenia CSP czy COOP/COEP.
Na te naruszenia musisz reagować w czasie rzeczywistym. ReportingObserver umożliwia dołączenie wywołania zwrotnego do zdarzenia związanego z naruszeniem zasad.
Chcesz dołączyć do raportu dodatkowe informacje, które pomogą Ci w debugowaniu – użyj niestandardowego wywołania zwrotnego.

Kolejna różnica polega na tym, że interfejs ReportingObserver jest skonfigurowany tylko po stronie klienta. Możesz go używać nawet wtedy, gdy nie masz kontroli nad nagłówkami po stronie serwera i nie możesz ustawić atrybutu Reporting-Endpoints.

Więcej informacji

Baner powitalny od Nine Koepfer / @enka80 na kanale Unsplash, edytowany. Dziękujemy Ianowi Clellandowi, Eiji Kitamurze i Milicy Mihajlija za ich opinie i sugestie dotyczące tego artykułu.