Monitorowanie aplikacji internetowej za pomocą interfejsu API do raportowania

Używaj interfejsu Reporting API do monitorowania naruszeń zabezpieczeń, wywołań wycofanych interfejsów API i innych zdarzeń.

Maud Nalpas

Niektóre błędy występują tylko w środowisku produkcyjnym. Nie zobaczysz ich lokalnie ani podczas tworzenia, 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 zabezpieczeń lub wywołania wycofanych i wkrótce wycofywanych interfejsów API w witrynie, i przesyła je do określonego punktu końcowego.

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

Skonfigurowanie interfejsu Reporting API daje Ci pewność, że gdy użytkownicy napotkają tego typu błędy, dowiesz się o tym i będziesz mieć możliwość ich naprawienia.

Z tego posta dowiesz się, co potrafi ten interfejs API i jak z niego korzystać. Zaczynajmy!

Przegląd

Załóżmy, że Twoja witryna site.example ma zasady Content-Security-Policy i Document-Policy. Nie wiesz, co to jest? Nie szkodzi, nadal będziesz w stanie zrozumieć 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 wycofane interfejsy API, których może używać Twoja baza kodu.

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

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

Zdarza się coś nieprzewidzianego i zasady te zostają naruszone w przypadku niektórych użytkowników.

Przykłady naruszenia zasad

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 CSP, raport o naruszeniu zasad dotyczących dokumentu i raport o wycofaniu, które rejestrują te problemy.

Z niewielkim opóźnieniem (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 otrzymują te raporty.

Możesz teraz uzyskać dostęp do raportów w tych punktach końcowych i sprawdzić, co poszło nie tak. Możesz zacząć rozwiązywać problem, który ma wpływ na 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 typów ostrzeżeń lub problemów, które występują w witrynie:

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

Ładunek 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 danymi logowania

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

Dane logowania mogą dostarczyć przydatnych dodatkowych informacji o raporcie, np. czy konto danego użytkownika stale powoduje błędy lub czy określona sekwencja działań podjętych na innych stronach powoduje wygenerowanie raportu na tej stronie.

Kiedy i jak przeglądarka wysyła raporty?

Raporty są dostarczane poza pasmem Twojej witryny: przeglądarka kontroluje, kiedy są wysyłane do skonfigurowanych punktów końcowych. Nie ma też możliwości kontrolowania, kiedy przeglądarka wysyła raporty. Zapisuje je, umieszcza w kolejce i wysyła automatycznie w odpowiednim czasie.

Oznacza to, że korzystanie z interfejsu Reporting API nie wpływa na wydajność.

Raporty są wysyłane z opóźnieniem (do minuty), aby zwiększyć szanse na wysyłanie ich w partiach. Pozwala to oszczędzać przepustowość, co jest szczególnie ważne w przypadku połączenia sieciowego użytkownika, zwłaszcza 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 z wolnej lub przeciążonej sieci.

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

Raporty generowane z powodu naruszeń lub wycofań występujących na Twojej stronie będą wysyłane do skonfigurowanych przez Ciebie punktów końcowych. Dotyczy to naruszeń popełnionych przez skrypty innych firm działające na Twojej stronie.

Naruszenia lub wycofania, które wystąpiły w osadzonym na stronie elemencie iframe ze współdzieleniem domen, nie będą zgłaszane do Twoich punktów końcowych (przynajmniej nie domyślnie). Ramka iframe może skonfigurować własne raportowanie, a nawet raportować do usługi raportowania Twojej witryny, czyli witryny własnej. Zależy to jednak od witryny w ramce. Pamiętaj też, że większość raportów jest generowana tylko wtedy, gdy zasady strony zostaną naruszone, a zasady strony i zasady elementu iframe są różne.

Przykład z wycofanymi funkcjami

Obsługa przeglądarek

Tabela poniżej podsumowuje obsługę interfejsu Reporting API w wersji 1 w przeglądarkach, czyli z nagłówkiem Reporting-Endpoints. Obsługa przeglądarek w przypadku interfejsu Reporting API w wersji 0 (nagłówek Report-To) jest taka sama z wyjątkiem jednego typu raportu: rejestrowanie błędów sieci nie jest obsługiwane w nowym interfejsie Reporting API. 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, zapoznaj się ze wskazówkami dotyczącymi migracji raportowania CSP.

Korzystanie z interfejsu Reporting API

Zdecyduj, gdzie mają być wysyłane raporty

Dostępne są dwie opcje:

• Wysyłaj raporty do istniejącej usługi zbierania raportów.
• wysyłać raporty do utworzonego i obsługiwanego przez siebie kolektora raportów.

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

Przykłady usług zbierających raporty:

• report-uri
• uriports
• HeaderHawk
• Sentry

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

Oprócz ceny przy wyborze narzędzia do zbierania raportów weź pod uwagę te kwestie: 🧐

• Czy ten kolektor obsługuje wszystkie typy raportów? Na przykład nie wszystkie rozwiązania dotyczące punktów końcowych raportowania obsługują raporty COOP/COEP.
• Czy zgadzasz się na udostępnianie adresów URL Twojej aplikacji podmiotowi zewnętrznemu zbierającemu raporty? Nawet jeśli przeglądarka usunie z tych adresów URL informacje poufne, mogą one wyciec w ten sposób. Jeśli to dla Ciebie zbyt ryzykowne, użyj własnego punktu końcowego raportowania.

Opcja 2. Utworzenie i obsługa własnego modułu zbierającego raporty

Zbudowanie własnego serwera, który odbiera raporty, nie jest takie proste. Na początek możesz utworzyć fork naszego lekkiego szablonu. Jest ona oparta na Express i może odbierać oraz wyświetlać raporty.

Gdy tworzysz własny moduł zbierający raporty:

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

Opcja 3. Połączenie opcji 1 i 2

Możesz chcieć, aby określony dostawca zajmował się niektórymi typami raportów, a inne raporty były generowane przez Twoje wewnętrzne rozwiązanie.

W takim przypadku ustaw kilka 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ą parą klucz-wartość lub serią takich par rozdzielonych przecinkami:

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ć oba parametry: Reporting-Endpoints i Report-To. Szczegółowe informacje znajdziesz w przewodniku po migracji. Jeśli używasz raportowania naruszeń Content-Security-Policy tylko za pomocą dyrektywy report-uri, zapoznaj się z instrukcjami migracji dotyczącymi 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, 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ć raporty o interwencjach, wycofaniach, awariach lub ich kombinacjach, 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, na który będą wysyłane raporty. Adres URL, który należy tu ustawić, zależy od decyzji podjętej w kroku 1.

Adres URL punktu końcowego:

• Musi zaczynać się od ukośnika (/). Ścieżki względne są nie obsługiwane.
• Może być współdzielony, 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żyć każdego nazwanego punktu końcowego w odpowiedniej zasadzie lub użyć jednego punktu końcowego we wszystkich zasadach.

Gdzie ustawić nagłówek?

W nowym interfejsie Reporting API, o którym piszemy w tym poście, raporty są ograniczone do dokumentów. Oznacza to, że w przypadku jednego pochodzenia 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 wycofaniach 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 dyrektywę report-to do każdego nagłówka zasad, dla którego chcesz otrzymywać raporty o naruszeniach. Wartość report-to powinna być jednym z nazwanych punktów końcowych, które zostały skonfigurowane.

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

report-to nie jest wymagane w przypadku wycofania, interwencji i awarii. Te raporty nie są powiązane z żadną zasadą. Są one generowane, dopóki jest skonfigurowany punkt końcowy default, i 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

Debugowanie konfiguracji raportowania

Celowe generowanie raportów

Podczas konfigurowania interfejsu Reporting API prawdopodobnie trzeba będzie celowo naruszyć zasady, aby sprawdzić, czy raporty są generowane i wysyłane zgodnie z oczekiwaniami.

Oszczędzaj czas

Raporty mogą być wysyłane z opóźnieniem – około minuty, co podczas debugowania jest długim czasem. 😴 Na szczęście podczas debugowania w Chrome możesz użyć flagi --short-reporting-delay, aby otrzymywać raporty natychmiast 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 użyj 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:

1. Używaj Chrome w wersji 96 lub nowszej (aby sprawdzić wersję, wpisz chrome://version w przeglądarce).
2. Wpisz lub wklej chrome://flags/#enable-experimental-web-platform-features na pasku adresu 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 aplikacji.
7. Załaduj ponownie Narzędzia deweloperskie.
8. Odśwież stronę. Raporty generowane przez stronę, na której otwarte są Narzędzia deweloperskie, będą wyświetlane w panelu Aplikacja w Narzędziach deweloperskich w Chrome w sekcji Reporting API.

Stan raportu

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

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

Rozwiązywanie problemów

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

Raporty nie zostały wygenerowane

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

• Sprawdź report-to w swoich zasadach. Jeśli jest nieprawidłowo skonfigurowany, raport nie zostanie wygenerowany. Aby to naprawić, otwórz stronę Edytuj zasady. Dodatkowym sposobem na rozwiązywanie problemów jest sprawdzenie konsoli Narzędzi deweloperskich w Chrome: jeśli w konsoli pojawi się błąd dotyczący oczekiwanego naruszenia, oznacza to, że zasady są prawdopodobnie prawidłowo skonfigurowane.
• Pamiętaj, że na tej liście będą widoczne tylko raporty wygenerowane dla dokumentu, w którym otwarte są Narzędzia deweloperskie. Przykład: jeśli Twoja witryna site1.examplezawiera element iframesite2.example, który narusza zasady i generuje raport, ten raport pojawi się w Narzędziach dla programistów tylko wtedy, gdy otworzysz element iframe w osobnym oknie i otworzysz Narzędzia dla programistów w tym oknie.

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

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

• Pamiętaj, aby używać krótkich opóźnień. Być może nie widzisz raportu, ponieważ nie został jeszcze wysłany.

• Sprawdź konfigurację nagłówka Reporting-Endpoints. Jeśli wystąpi problem, prawidłowo wygenerowany raport nie zostanie wysłany. W Narzędziach deweloperskich stan raportu pozostanie Queued (może zmienić się na Pending, a następnie szybko wrócić do 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 został 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 raporty o interwencjach, będą wysyłane tylko do punktu końcowego o nazwie default. Więcej informacji znajdziesz w artykule Konfigurowanie nagłówka Reporting-Endpoints.

• Sprawdź, czy w składni nagłówków zasad nie ma błędó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 Twój punkt końcowy obsługuje żądania wstępne CORS. Jeśli nie, nie może otrzymywać raportów.

  • Przetestuj działanie punktu końcowego. Aby to zrobić, zamiast ręcznie generować raporty, możesz emulować przeglądarkę, wysyłając do punktu końcowego żądania, które wyglądają jak te, które wysyła przeglądarka. Uruchom następujące polecenie:

  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 odpowiadać kodem powodzenia (200 lub innym kodem odpowiedzi oznaczającym powodzenie2xx). Jeśli tak się nie dzieje, oznacza to problem z jego konfiguracją.

Powiązane mechanizmy raportowania

Tylko raport

Nagłówki zasad -Report-Only i Reporting-Endpoints współpracują 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, gdy te zasady zostaną naruszone.

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. Będą też otrzymywać raporty o naruszeniach tych zasad.

W obu przypadkach wysyłane są raporty, ale nagłówki -Report-Only nie wymuszają przestrzegania zasad: nic nie zostanie uszkodzone ani zablokowane, ale otrzymasz raporty o tym, co zostałoby uszkodzone lub zablokowane.

ReportingObserver

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 przypadki użycia.

Użyj ReportingObserver, jeśli:

• Chcesz monitorować tylko wycofania lub interwencje przeglądarki. ReportingObserver wyświetla ostrzeżenia po stronie klienta, takie jak wycofanie i interwencje przeglądarki, ale w przeciwieństwie do Reporting-Endpoints nie rejestruje żadnych innych typów raportów, takich jak naruszenia CSP lub COOP/COEP.
• Musisz reagować na te naruszenia w czasie rzeczywistym. ReportingObserverumożliwia dołączenie wywołania zwrotnego do zdarzenia naruszenia.
• Chcesz dołączyć do raportu dodatkowe informacje, które pomogą w debugowaniu, używając niestandardowego wywołania zwrotnego.

Kolejna różnica polega na tym, że ReportingObserver konfiguruje się tylko po stronie klienta: możesz używać tej dyrektywy, 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 interfejsu Reporting API w wersji 0 do wersji 1
• ReportingObserver
• Specyfikacja: starsza wersja interfejsu Reporting API (wersja 0)
• Specyfikacja: nowy interfejs Reporting API (wersja 1)

Dziękujemy Ianowi Clellandowi, Eijiemu Kitamurze i Milicy Mihajliji za sprawdzenie tego dokumentu i sugestie.