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 wykrywać niektóre z tych błędów, np. naruszenia bezpieczeństwa lub wycofane i wkrótce wycofywane wywołania interfejsu API w witrynie, a następnie przesyła je do określonego 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

Interfejs Reporting API działa od wersji Chrome 96 i nowszych (od października 2021 r. w przypadku wersji beta lub Canary).

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? To nie problem, nadal możesz zrozumieć ten przykład.

decydujesz się monitorować swoją witrynę, aby wiedzieć, kiedy te zasady są naruszane, ale też 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 mapuj nazwy punktów końcowych za pomocą dyrektywy report-to w swoich 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ło coś nieoczekiwanego i zasady zostały naruszone 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, wczytano 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 dotyczących tych punktów końcowych i sprawdzić, 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:

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:

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ą dostarczyć przydatnych dodatkowych informacji o raporcie, np. czy konto danego użytkownika wywołuje błędy w ciągły sposób, 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ą: 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, umieszcza w kole i wysyła automatycznie w odpowiednim momencie.

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 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 wycofania się na Twojej stronie będą wysyłane do skonfigurowanych punktów końcowych. Dotyczy to naruszeń popełnionych 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 strony, a zasady strony i ramki iframe są różne.

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 przenieść się do 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 zbierania raportów.
• Wysyłanie raportów do kolektora raportów, który został utworzony i utrzymywany przez Ciebie.

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 zbyt ryzykowne dla Twojej aplikacji, uruchom własny punkt końcowy raportowania.

Opcja 2. Utwórz i używaj własnego zbieracza 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. Jest ono oparte na Express i może odbierać oraz wyświetlać raporty.

1. Otwórz szablonowy program do zbierania raportów.

2. Kliknij Remixuj do edycji, aby umożliwić edycję projektu.

3. Masz już klon! 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ć 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. 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-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, pod 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 tematem tego artykułu, 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 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 reguły do dyrektywy 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żyć tego samego punktu końcowego dla wielu zasad lub używać różnych punktów końcowych w różnych zasadach.

report-to nie jest wymagany w przypadku raportów o wycofaniu, interwencji i awarii. 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

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 będziesz musiał 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.

W październiku 2021 r. ta funkcja była w wersji eksperymentalnej. Aby z niej korzystać, 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 Aplikacja.
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 raport, którego oczekujesz, nie jest widoczny na tej liście:

• Sprawdź report-to w swoich zasadach. Jeśli konfiguracja jest nieprawidłowa, raport nie zostanie wygenerowany. Aby to zrobić, przejdź do sekcji Edytuj zasady. 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 zawiera element iframe site2.example, który narusza zasady i generuje raport, ten raport pojawi się w Narzędziach dla programistów tylko wtedy, gdy otworzysz iframe w oddzielnym oknie i otworzysz Narzędzia dla programistów w tym oknie.

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

Co zrobić, jeśli widzisz raport w Narzędziach dla programistów, ale Twoje urządzenie końcowe 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.

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

  • Przetestuj zachowanie 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ą razem.

Punkty końcowe skonfigurowane w Reporting-Endpoints i wyszczególnione 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 też raporty o naruszeniu tych zasad.

W obu przypadkach wysyłane są raporty, ale nagłówki -Report-Only nie powodują egzekwowania 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 może pomóc w obserwowaniu ostrzeżeń 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 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.
• 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ą niestandardowej funkcji 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 Milicy Mihajlija za sprawdzenie i zaproponowane zmiany w tym artykule.