Monitorowanie aplikacji internetowej za pomocą interfejsu API do raportowania

Używaj interfejsu Reporting API do monitorowania naruszeń bezpieczeństwa, wycofanych wywołań interfejsu API i innych zdarzeń.

Maud Nalpas

Niektóre błędy występują tylko w środowisku produkcyjnym. Nie zobaczysz ich lokalnie ani podczas programowania, 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 całej witrynie, i przesyłać je do określonego przez Ciebie 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 pewność, że gdy użytkownicy napotkają tego typu błędy, będziesz o tym wiedzieć 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 nagłówki Content-Security-Policy i Document-Policy. Nie wiesz, do czego służą te opcje? 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ć Twój kod.

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

Wystąpi nieprzewidziana sytuacja, w wyniku której zasady zostaną 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, 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 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 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ć wiele rodzajów interesujących ostrzeżeń lub problemów, które występują w Twojej witrynie:

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

Ł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"
  }
]

W każdym z tych raportów znajdziesz te dane:

Raporty z potwierdzonymi kwalifikacjami

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ą dostarczać 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 raport 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. Przechwytuje je, umieszcza w kolejce i wysyła automatycznie w odpowiednim czasie.

Oznacza to, że podczas korzystania z interfejsu Reporting API nie musisz się martwić o wydajność.

Raporty są wysyłane z opóźnieniem – do minuty – aby zwiększyć szansę na wysyłanie ich w pakietach. Pozwala to oszczędzać przepustowość, aby nie obciążać połączenia sieciowego użytkownika, co jest szczególnie ważne w przypadku urządzeń mobilnych. Przeglądarka może też opóźnić dostarczenie, jeśli jest zajęta przetwarzaniem zadań o wyższym priorytecie lub jeśli użytkownik korzysta w danym momencie z wolnej lub przeciążonej sieci.

Problemy dotyczące firm zewnętrznych i firm własnych

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

Naruszenia lub wycofania, które wystąpiły w osadzonym na Twojej stronie elemencie iframe z innej domeny, nie będą zgłaszane do Twoich punktów końcowych (przynajmniej nie domyślnie). Element iframe może skonfigurować własne raportowanie, a nawet przesyłać dane do usługi raportowania Twojej witryny, czyli usługi podmiotu własnego. 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 Twojej strony i zasady elementu iframe są różne.

Przykład z wycofanymi funkcjami

Obsługa przeglądarek

W tabeli poniżej znajdziesz podsumowanie obsługi interfejsu Reporting API w wersji 1 przez przeglądarki, 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, przeczytaj wskazówki dotyczące migracji raportowania CSP.

Korzystanie z interfejsu Reporting API

Decydowanie, gdzie mają być wysyłane raporty

Dostępne są dwie opcje:

• Wysyłanie raportów do istniejącej usługi zbierania raportów.
• wysyłać raporty do kolektora raportów, który samodzielnie tworzysz i obsługujesz;

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

Przykłady usług zbierających raporty:

• report-uri
• uriports

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 zbieracz obsługuje wszystkie typy raportów? Na przykład nie wszystkie rozwiązania w zakresie punktów końcowych raportowania obsługują raporty COOP/COEP.
• Czy zgadzasz się na udostępnienie adresów URL aplikacji zewnętrznemu podmiotowi zbierającemu raporty? Nawet jeśli przeglądarka usunie z tych adresów URL informacje poufne, mogą one zostać ujawnione w ten sposób. Jeśli wydaje Ci się to zbyt ryzykowne dla Twojej aplikacji, używaj własnego punktu końcowego raportowania.

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

Zbudowanie własnego serwera, który będzie odbierać raporty, nie jest takie proste. Na początek możesz skopiować nasz lekki szablon. Został on utworzony za pomocą Express i może odbierać oraz wyświetlać raporty.

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

• Sprawdź, czy w przypadku żądań POST występuje wartość Content-Type równa application/reports+json. Dzięki temu rozpoznasz żądania raportów wysyłane przez przeglądarkę do 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 były obsługiwane przez Twoją firmę.

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"

Konfigurowanie nagłówka Reporting-Endpoints

Ustaw nagłówek odpowiedzi Reporting-Endpoints. Musi to być jedna lub kilka par klucz-wartość rozdzielonych przecinkami:

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

Jeśli migrujesz ze starszej wersji interfejsu Reporting API do nowej, warto ustawić oba parametry: Reporting-Endpoints i Report-To. Szczegółowe informacje znajdziesz w przewodniku po migracji. Jeśli używasz raportowania naruszeń za pomocą tylko dyrektywy report-uri, zapoznaj się z krokami migracji w przypadku raportowania CSP.Content-Security-Policy

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ć wybraną przez Ciebie 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, wycofaniu lub awariach albo ich kombinację, 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 nie są obsługiwane.
• Może być wysyłany z innej domeny, 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"

Każdy nazwany punkt końcowy możesz następnie wykorzystać w odpowiednich zasadach 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 wycofywaniu funkcji 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, w przypadku których chcesz otrzymywać raporty o naruszeniach. Wartość report-to powinna być jednym z nazwanych punktów końcowych, które zostały przez Ciebie 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 potrzebny w przypadku raportów o wycofaniu, interwencji i awarii. Te raporty nie są powiązane z żadnymi zasadami. Są one generowane, dopóki skonfigurowany jest 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 będziesz musiał(a) 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 jest długim czasem podczas 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 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 z niej skorzystać, wykonaj te czynności:

1. Używaj Chrome w wersji 96 lub nowszej (sprawdź, wpisując chrome://version w przeglądarce).
2. Wpisz lub wklej chrome://flags/#enable-experimental-web-platform-features w 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 Aplikacja.
7. Załaduj ponownie Narzędzia deweloperskie.
8. Załaduj ponownie stronę. Raporty wygenerowane na stronie, 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 wysyłane do 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 oczekiwany raport nie pojawia się na tej liście:

• Sprawdź report-to w swoich zasadach. Jeśli ta opcja jest nieprawidłowo skonfigurowana, raport nie zostanie wygenerowany. Aby to naprawić, otwórz stronę 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 dotyczący oczekiwanego naruszenia, oznacza to, że zasady są prawdopodobnie prawidłowo skonfigurowane.
• Pamiętaj, że na tej liście będą się wyświetlać tylko raporty wygenerowane dla dokumentu, w którym są otwarte Narzędzia deweloperskie. Przykład: jeśli Twoja witryna site1.example zawiera 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 docierają do odbiorcy

Co zrobić, jeśli raport jest widoczny w Narzędziach dla programistów, ale 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 tym przypadku stan raportu w Narzędziach deweloperskich pozostanie Queued (może się zmienić na Pending, a potem szybko wrócić do Queued, gdy zostanie podjęta próba dostarczenia). Oto kilka typowych błędów, które mogą powodować ten problem:

• 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, takie jak 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 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 może otrzymywać raportów.

  • Sprawdź działanie punktu końcowego. W tym celu 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 zgłoszenie

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

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

Interfejs ReportingObserver JavaScript API może pomóc w obserwowaniu ostrzeżeń po stronie klienta.

ReportingObserver i nagłówek 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 przeglądarki. ReportingObserver wyświetla ostrzeżenia po stronie klienta, np. o wycofaniu funkcji i interwencjach przeglądarki, ale w przeciwieństwie do Reporting-Endpoints nie rejestruje innych typów raportów, np. o naruszeniach CSP czy 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, za pomocą niestandardowego wywołania zwrotnego.

Kolejna różnica polega na tym, że ReportingObserver jest konfigurowany 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ć Reporting-Endpoints.

Więcej informacji

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

Baner powitalny: Nine Koepfer / @enka80 na stronie Unsplash, po edycji. Dziękujemy Ianowi Clellandowi, Eijiemu Kitamurze i Milicy Mihajliji za sprawdzenie tego dokumentu i sugestie.