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

Niektóre błędy występują tylko w wersji produkcyjnej. Nie zobaczysz ich lokalnie ani podczas rozwoju, ponieważ prawdziwi użytkownicy, prawdziwe sieci i prawdziwe urządzenia zmieniają grę. 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 on zadeklarowanie, co chcesz monitorować, za pomocą nagłówków HTTP. Jest on obsługiwany 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

Załóżmy, że Twoja witryna site.example ma nagłówek Content-Security-Policy i Document-Policy. Nie wiesz, do czego służą te opcje? Nie szkodzi, i tak zrozumiesz 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ł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, 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 pasmem przez samą przeglądarkę (nie przez Twój 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 API do raportowania można skonfigurować tak, aby pomagać w monitorowaniu wielu rodzajów interesujących ostrzeżeń i problemów występujących w całej witrynie:

Raporty

Jak wyglądają raporty?

Przeglądarka wysyła raporty do skonfigurowanego przez Ciebie 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:

Raporty z uprawnieniami

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ą zapewnić dodatkowy kontekst dla raportu. Możesz na przykład określić, czy konto danego użytkownika stale wywołuje błędy lub czy określona sekwencja działań wykonanych na innych stronach powoduje wygenerowanie raportu na tej stronie.

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 Reporting API nie ma potrzeby martwić się wydajnością.

Raporty są wysyłane z opóźnieniem (do minuty), aby zwiększyć prawdopodobieństwo wysyłania ich partiami. Pozwala to oszczędzać przepustowość, aby nie obciążać połączenia użytkownika, co jest szczególnie ważne na urządzeniach 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 wycofania się na Twojej stronie będą wysyłane do skonfigurowanych punktów końcowych. Dotyczy to również naruszeń popełnionych przez skrypty innych firm działające na Twojej stronie.

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

Przykład z wycofanymi funkcjami

Obsługa przeglądarek

Tabela poniżej zawiera informacje o obsłudze przeglądarek w przypadku interfejsu Reporting API w wersji 1, czyli z nagłówkiem 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.

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

Określanie, gdzie mają być wysyłane raporty

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 utworzonego i obsługiwanego samodzielnie.

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

Przykłady usług zbierania raportów:

• report-uri
• uriports

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 usunie poufne informacje z tych adresów URL, mogą one zostać w ten sposób ujawnione. Jeśli to jest zbyt ryzykowne dla Twojej aplikacji, uruchom własny punkt końcowy raportowania.

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

Stworzenie 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. Aby udostępnić projekt do edycji, kliknij Remiksuj, aby edytować.

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 innym punkcie początkowym niż Twoja witryna, upewnij się, że obsługuje żądania procesu wstępnego CORS.

Opcja 3. Połącz opcje 1 i 2

Możesz zlecić konkretnemu dostawcy obsługę niektórych typów raportów, ale mieć własne rozwiązanie na potrzeby innych.

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. W szczególności jeśli korzystasz z raportowania naruszeń zasad Content-Security-Policy tylko za pomocą dyrektywy report-uri, zapoznaj się z procedurą migracji do 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-endpoint i my-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ć interwencje, wycofania lub awarie, skonfiguruj 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, na który będą wysyłane raporty. Adres URL, który tutaj ustawisz, zależy od tego, co wybierzesz w kroku 1.

Adres URL punktu końcowego:

• Musi zaczynać się od ukośnika (/). Ścieżki względne nie są obsługiwane.
• Może być z innego źródła, ale w takim przypadku dane logowania nie są wysyłane wraz 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"

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/page1 i site.example/page2, mogą wysyłać raporty do różnych punktów końcowych.

Aby otrzymywać raporty o przypadkach naruszenia lub wycofanych funkcji na dowolnej stronie witryny, ustaw nagłówek jako oprogramowanie pośredniczące we wszystkich odpowiedziach.

Oto przykład w Google 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 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 przez Ciebie nazwanych punktów końcowych.

Możesz użyć tego samego punktu końcowego dla wielu zasad lub różnych punktów końcowych w różnych zasadach.

report-to nie jest wymagany w przypadku raportów o wycofaniu, interwencji i awarii. Raporty te nie są objęte ż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

Poniżej znajdziesz przykładowy serwer Node, który korzysta z Express i łączy wszystkie elementy omówione w tym artykule. Pokazuje on, jak skonfigurować raportowanie dla kilku różnych typów raportów i jak wyświetlić wyniki.

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 wykorzystuje inne rodzaje niepożądanego działania, który generuje raporty każdego typu, zapoznaj się z prezentacją.

Oszczędzaj czas

Raporty mogą być wysyłane z opóźnieniem – około minuty, czyli z 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 go użyć, wykonaj te czynności:

1. Używaj Chrome w wersji 96 lub nowszej (sprawdź to, wpisując chrome://version w przeglądarce).
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.

Stan raportu

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

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 ta 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 poprawnie skonfigurowana.
• 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 ani odbierane

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

• 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:

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

• 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.

  • Sprawdź, czy 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ą.

Powiązane mechanizmy zgłaszania

Tylko raporty

Nagłówki zasad -Report-Only i Reporting-Endpoints 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 w przypadku naruszenia 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.

Nagłówki ReportingObserver i Reporting-Endpoints generują raporty, które wyglądają tak samo, ale umożliwiają nieco inne zastosowania.

Użyj metody ReportingObserver, jeśli:

• Chcesz monitorować tylko wycofania lub interwencje w przeglądarce. 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.
• Na takie naruszenia musisz reagować w czasie rzeczywistym. ReportingObserver umożliwia dołączenie wywołania zwrotnego do zdarzenia naruszenia.
• Chcesz dołączyć do raportu dodatkowe informacje, które pomogą Ci w debugowaniu, za pomocą niestandardowego wywołania zwrotnego.

Kolejna różnica polega na tym, że ReportingObserver jest konfigurowana tylko po stronie klienta: możesz jej używać, nawet jeśli nie masz kontroli nad nagłówkami po stronie serwera i nie możesz ustawić Reporting-Endpoints.

Więcej informacji

• Przewodnik po migracji z wersji 0 interfejsu Reporting API na wersję 1
• ReportingObserver
• Specyfikacja: starsza wersja interfejsu Reporting API (wersja 0)
• Specyfikacja: nowy interfejs Reporting API (wersja 1)

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.