Monitorowanie aplikacji internetowej za pomocą interfejsu API do raportowania

Interfejs API do raportowania pozwala monitorować naruszenia zabezpieczeń, wycofane wywołania interfejsu API i nie tylko.

Maud Nalpas

Niektóre błędy występują tylko w wersji produkcyjnej. Nie będą one widoczne lokalnie ani w trakcie jej trwania podczas programowania, ponieważ to prawdziwi użytkownicy, prawdziwe sieci i prawdziwe urządzenia. i tak... Interfejs Reporting API pomaga wychwytywać niektóre z tych błędów: jako naruszenia bezpieczeństwa lub interfejs API, który zostanie wycofany i wkrótce wycofany w całej witrynie i przesyła je do punktu końcowego określone dane.

Pozwala zadeklarować, co chcesz monitorować, za pomocą nagłówków HTTP. obsługiwany przez przeglądarkę.

Skonfigurowanie interfejsu API do raportowania zapewnia spokój ducha wynikający z tego, że gdy użytkownicy tego typu błędy i możesz je naprawić.

Z tego posta dowiesz się, do czego służy ten interfejs API i jak go używać. Zaczynamy!

Wersja demonstracyjna i kod

Zobacz, jak działa interfejs API do raportowania, zaczynając od Chrome 96 i nowsza wersja (Chrome beta lub Canary, dane z października 2021 r.).

Omówienie

Załóżmy, że Twoja witryna site.example ma zasady Content-Security-Policy i Document-Policy. Nie wiesz, do czego służą te funkcje? W porządku. Nadal będziesz zrozumieć ten przykład.

Postanawiasz monitorować witrynę w celu określenia, czy doszło do naruszenia tych zasad, ale także dlatego, że jeśli chcesz śledzić interfejsy API, które zostały wycofane lub wkrótce zostaną wycofane z Twojej bazy kodu.

Aby to zrobić, skonfiguruj nagłówek Reporting-Endpoints i zmapuj ten punkt końcowy 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

Dzieje się coś nieprzewidzianego i naruszenia tych zasad powodują 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 dokumentów i wycofanie raportu zawierającego te problemy.

Z niewielkim opóźnieniem (maks. minutą) przeglądarka wysyła raporty do który został skonfigurowany pod kątem tego typu naruszenia. Raporty są wysyłane spoza zakresu przez samej przeglądarki (nie przez serwer ani witrynę).

Punkty końcowe 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 zająć się rozwiązywaniem problemu, który wpływa 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ć w taki sposób, aby pomóc Ci w monitorowaniu wielu typów interesujących ostrzeżeń i problemów które mają miejsce w Twojej witrynie:

Raporty

Jak wyglądają raporty?

Przeglądarka wysyła raporty do skonfigurowanego przez Ciebie punktu końcowego. Wysyła takie żądania:

POST
Content-Type: application/reports+json

Ładunek tych żądań ma postać listy 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 zawiera każdy z tych raportów:

Raporty z danymi uwierzytelniającymi

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

Dane logowania mogą stanowić dodatkowy kontekst dotyczący raportu. w przypadku np. czy konto danego użytkownika stale wywołuje błędy, czy gdy 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 z witryny poza zakresem: to przeglądarka kontroluje, kiedy są wysyłane do skonfigurowanych punktów końcowych. Nie można też kontrolować, kiedy przeglądarka wysyła raporty; przechwytuje je, dodaje do kolejki i wysyła automatycznie w odpowiednim czasie.

Oznacza to, że podczas korzystania z interfejsu API do raportowania nie trzeba mieć żadnych problemów ze skutecznością.

Raporty są wysyłane z opóźnieniem (maksymalnie minutowym), aby zwiększyć szanse na wysyłanie raportów zbiorczo. Pozwala to zaoszczędzić przepustowość i zachować szacunek dla połączenia sieciowego użytkownika, co jest szczególnie co jest bardzo ważne w przypadku urządzeń mobilnych. Przeglądarka może też opóźniać wyświetlanie, jeśli jest zajęta przetwarzaniem wyższego priorytetu. lub jeśli użytkownik korzysta w danej chwili z wolnej lub przeciążonej sieci.

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

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

Naruszenia lub wycofane elementy iframe umieszczone na stronie będą nie być zgłaszane do punktów końcowych (przynajmniej domyślnie nie). Element iframe może skonfigurować własny raportowanie, a nawet przesyłanie raportów do własnej – własnej – usługi raportowania; ale to już wszystko do witryny z ramką. Pamiętaj też, że większość zgłoszeń jest generowanych tylko w przypadku naruszenia zasad na stronie, oraz że zasady na Twojej stronie i w elemencie iframe różnią się od siebie.

Przykład ze wycofanymi funkcjami

Obsługa przeglądarek

Tabela poniżej zawiera podsumowanie obsługi interfejsu API do raportowania w wersji 1, tj. Reporting-Endpoints. Interfejs API do raportowania w wersji 0 (nagłówek Report-To) obsługuje przeglądarki taki sam typ raportu: logowanie błędów sieci nie jest obsługiwane w nowym interfejsie API do raportowania. Szczegółowe informacje znajdziesz w przewodniku po migracji.

Ta tabela zawiera tylko podsumowanie informacji o obsłudze pola 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 API do raportowania

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. Wykorzystanie istniejącej usługi kolektora raportów

Oto kilka przykładów usług kolektora raportów:

• identyfikator URI raportu report-uri
• uriporty

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

Wybierając moduł zbierający raporty, oprócz ceny weź pod uwagę te kwestie: 🧐

• Czy ten kolektor obsługuje wszystkie typy raportów? Na przykład nie wszystkie rozwiązania do obsługi punktów końcowych do raportowania i obsługują raporty COOP/COEP.
• Czy zgadzasz się na udostępnianie adresów URL aplikacji zewnętrznemu kolektorowi raportów? Nawet jeśli przeglądarka usuwa z tych adresów URL poufne informacje, w ten sposób mogą zostać wyciek. Jeśli wydaje się to zbyt ryzykowne dla do Twojej aplikacji, konfiguruj własny punkt końcowy raportowania.

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

Zbudowanie własnego serwera, który będzie otrzymywać raporty, nie jest takie proste. Na początek możesz utworzyć rozwidlenie lekki koncepcja. Została utworzona za pomocą szybkiej weryfikacji i może otrzymywać oraz wyświetlać raporty.

1. Otwórz schemat raportów zbierających raporty.

2. Aby udostępnić projekt do edycji, kliknij Remiksuj, aby edytować.

3. Masz już swojego klona! Możesz dostosować ją do swoich potrzeb.

Jeśli nie stosujesz schematu i tworzysz własny serwer od podstaw:

• Aby rozpoznać raporty, sprawdź POST żądań z wartością Content-Type o wartości application/reports+json wysyłanych 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 procesu wstępnego CORS.

Opcja 3: połącz opcję 1 i 2

Możesz zlecić to konkretnemu dostawcy, który zajmie się niektórymi typami raportów, ale mieć własne i innym użytkownikom.

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. Jego wartość musi składać się z jednej lub kilku wartości rozdzielanych przecinkami pary klucz-wartość:

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

Jeśli przechodzisz ze starszej wersji interfejsu Reporting API na nowy interfejs Reporting API, warto skorzystać z ustaw zarówno Reporting-Endpoints, jak i Report-To. Szczegółowe informacje znajdziesz w przewodniku po migracji. Zwłaszcza, jeśli używasz raportów Naruszenia (Content-Security-Policy) tylko za pomocą dyrektywy report-uri; zapoznaj się z procedurą migracji dotyczącą 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 być wybraną przez Ciebie nazwą, np. main-endpoint lub endpoint-1. Możesz ustawić różne nazwane punkty końcowe dla różnych raportów typy – na przykład my-coop-endpoint, my-csp-endpoint. Dzięki temu może kierować raporty do różnych punktów końcowych w zależności od ich typu.

Jeśli chcesz otrzymać interwencję, wycofanie lub awarię 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 (ale zostaną wygenerowane).

Wartości (adresy URL)

Każda wartość to wybrany przez Ciebie adres URL, na który będą wysyłane raporty. Adres URL ustawienia w tym miejscu zależy od tego, jaki został podjęty w kroku 1.

Adres URL punktu końcowego:

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

Gdzie ustawić nagłówek?

W nowym interfejsie API do raportowania – omówionym w tym artykule post – raporty mają zakres ograniczony do dokumentów. Oznacza to, że dla danej wartości źródło, różne dokumenty, takie jak site.example/page1, site.example/page2, może wysyłać raporty do różnych punktów końcowych.

Aby otrzymywać raporty o naruszeniach lub wycofanych rozwiązaniach, odbywaj się na dowolnej stronie ustaw nagłówek jako element pośredniczący 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();
});

Edytuj zasady

Teraz, gdy nagłówek Reporting-Endpoints jest już skonfigurowany, dodaj report-to do każdego nagłówka zasad, które naruszają zasady raportów. Wartość report-to powinna być jednym z nazwanych punktów końcowych, skonfigurowany.

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

Parametr report-to nie jest potrzebny do wycofania, interwencji i awarii raportów. Raporty te nie są objęte żadnymi zasadami. Są generowane, jeśli punkt końcowy default jest skonfigurowany i wysłany 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

Aby zobaczyć to wszystko w kontekście, poniżej znajdziesz przykładowy serwer węzłów, który używa usługi Express i łączy wszystkie omówione w nim zagadnienia. Pokazuje, jak skonfiguruj raportowanie dla kilku różnych typów raportów i wyświetli wyniki.

Debugowanie konfiguracji raportowania

Celowe generowanie raportów

Podczas konfigurowania interfejsu API do raportowania prawdopodobnie musisz celowo naruszać zasad, aby sprawdzić, czy raporty są generowane i wysyłane zgodnie z oczekiwaniami. Aby zobaczyć przykładowy kod, który narusza zasady i wykorzystuje inne szkodliwe aby wygenerować wszelkiego rodzaju raporty, zapoznaj się z prezentacją.

Oszczędzaj czas

Raporty mogą być wysyłane z opóźnieniem – około minuty, czyli 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 to polecenie w terminalu:

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

Korzystanie z Narzędzi deweloperskich

Aby wyświetlić raporty, które zostały wysłane, użyj Narzędzi deweloperskich w Chrome.

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

1. Użyj Chrome w wersji 96 lub nowszej (możesz to sprawdzić, wpisując w przeglądarce chrome://version)
2. Wpisz lub wklej chrome://flags/#enable-experimental-web-platform-features na pasku adresu URL Chrome.
3. Kliknij Włączone.
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. Odśwież stronę. Raporty wygenerowane przez stronę, na której są otwarte Narzędzia deweloperskie, będą są dostępne w Narzędziach deweloperskich w Chrome Panel aplikacji w sekcji Reporting API.

Stan raportu

Kolumna Stan informuje, czy udało się wysłać raport.

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

Rozwiązywanie problemów

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

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 błąd jest skonfigurowany, nie zostanie wygenerowany. Przejdź do sekcji Edytowanie zasad, aby napraw to. Dodatkowym sposobem rozwiązania tego problemu jest sprawdzenie konsoli w Narzędziach deweloperskich w Chrome: w konsoli pojawi się komunikat o spodziewanym naruszeniu zasad, oznacza to, że Twoja zasada poprawnie skonfigurowane.
• Pamiętaj, że otwarte są tylko raporty wygenerowane dla dokumentu Narzędzia deweloperskie, które pojawiają się na tej liście. Przykład: jeśli Twoja witryna site1.example umieszcza element iframe site2.example który narusza zasady i dlatego generuje raport, wyświetli się w Narzędziach deweloperskich tylko wtedy, gdy otworzysz iframe w osobnym oknie i otwórz w nim Narzędzia deweloperskie.

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

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

• Zachowaj krótkie opóźnienia. Być może dlatego, że nie widzisz raportu, nie wysłano jeszcze!

• Sprawdź konfigurację nagłówka Reporting-Endpoints. Jeśli występują jakieś problemy, zgłoś, został prawidłowo wygenerowany, nie zostanie wysłany. W Narzędziach deweloperskich stan raportu pozostanie bez zmian Queued (może przejść do Pending, a następnie szybko z powrotem do Queued przy próbie dostarczenia w tym przypadku. 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. dotyczące wycofania 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.

• Poszukaj problemów ze składnią nagłówków zasad, np. brakujących cudzysłowów. Zobacz szczegóły

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

  • Sprawdź, czy punkt końcowy obsługuje żądania wstępne CORS. Jeśli tego nie zrobi, nie będzie mogła otrzymywać raportów.

  • Przetestuj działanie punktu końcowego. W tym celu zamiast generowania ręcznie, możesz emulować przeglądarkę, wysyłając do punktów końcowych żądania, które wyglądają co 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 inny kod odpowiedzi o powodzeniu 2xx). Jeśli tak nie jest, występuje problem z jego konfiguracją.

Powiązane mechanizmy zgłaszania

Tylko raport

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 metody Content-Security-Policy, Cross-Origin-Embedder-Policy i Cross-Origin-Opener-Policy będzie otrzymywać zgłoszenia w przypadku naruszenia tych zasad.

Punkty końcowe skonfigurowane w Reporting-Endpoints można też określić w parametrze report-to – pole Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only i Cross-Origin-Opener-Policy-Report-Only Będą także otrzymywać zgłoszenia w przypadku naruszenia tych zasad.

Chociaż raporty są wysyłane w obu przypadkach, nagłówki -Report-Only nie wymuszają parametru zasad: nic nie zostanie uszkodzone ani zablokowane, ale otrzymasz z raportami o tym, co zostało uszkodzone lub zablokowane.

ReportingObserver

Interfejs ReportingObserver JavaScript API może Ci pomóc ostrzeżenia 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 metody ReportingObserver, jeśli:

• Chcesz tylko monitorować wycofane elementy lub interwencje w zakresie przeglądarek. ReportingObserver wyświetla ostrzeżenia po stronie klienta, np. o wycofaniu i interwencji przeglądarek, ale w przeciwieństwie do Reporting-Endpoints rejestrować wszelkie inne typy zgłoszeń, np. naruszenia zasad dotyczących CSP lub COP/COEP.
• Na takie naruszenia musisz reagować w czasie rzeczywistym. ReportingObserver marki możesz dołączyć wywołanie zwrotne do zdarzenia naruszenia.
• chcesz dołączyć do zgłoszenia dodatkowe informacje, które ułatwią debugowanie, za pomocą niestandardowego wywołania zwrotnego.

Kolejna różnica polega na tym, że usługa ReportingObserver jest skonfigurowana tylko po stronie klienta: można go używać nawet wtedy, gdy nie ma kontroli nad nagłówkami po stronie serwera i nie ustaw Reporting-Endpoints.

Więcej informacji

• Przewodnik po migracji z interfejsu Reporting API z wersji 0 do wersji 1
• ReportingObserver
• Specyfikacja: starszy interfejs API do raportowania (v0)
• Specyfikacja: nowy interfejs API do raportowania (v1)

Baner powitalny: Nine Koepfer / @enka80, Unsplash, edytowano. Dziękujemy Ianowi Clellandowi, Eiji Kitamurze i Milice Mihajlija za opinie i sugestie związane z tym artykułem.