Мониторинг вашего веб-приложения с помощью Reporting API

Используйте API для создания отчетов, чтобы отслеживать нарушения безопасности, устаревшие вызовы API и многое другое.

Maud Nalpas

Некоторые ошибки возникают только в рабочей среде. Вы не увидите их локально или во время разработки, потому что реальные пользователи , реальные сети и реальные устройства меняют правила игры. API для отчетов помогает выявлять некоторые из этих ошибок — например, нарушения безопасности или устаревшие и скоро устаревающие вызовы API на вашем сайте — и передает их на указанную вами конечную точку.

Это позволяет указывать, что именно вы хотите отслеживать, используя HTTP-заголовки, и управляется браузером .

Настройка API для создания отчетов обеспечит вам уверенность в том, что вы будете знать о подобных ошибках, с которыми сталкиваются пользователи, и сможете их исправить.

В этой статье рассматривается, что может делать этот API и как его использовать. Давайте начнём!

Обзор

Предположим, что на вашем сайте, site.example , есть политика Content-Security-Policy и политика Document-Policy. Не знаете, для чего они нужны? Ничего страшного, вы все равно сможете понять этот пример.

Вы решаете отслеживать свой сайт, чтобы знать, когда нарушаются эти правила, а также потому, что хотите следить за устаревшими или即将 устаревшими API, которые может использовать ваш код.

Для этого необходимо настроить заголовок Reporting-Endpoints и сопоставить имена этих конечных точек с помощью директивы report-to в политиках там, где это необходимо.

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

Происходит нечто непредвиденное, и эти правила нарушаются некоторыми вашими пользователями.

Примеры нарушений

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 , загружается файлом 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;

Браузер генерирует отчет о нарушении CSP, отчет о нарушении политики документа и отчет об устаревании, в которых фиксируются эти проблемы.

С небольшой задержкой — до минуты — браузер отправляет отчеты на конечную точку, настроенную для данного типа нарушений. Отчеты отправляются внеполосным способом самим браузером (а не вашим сервером или вашим сайтом).

Конечная точка (точки) получает (получают) эти отчеты.

Теперь вы можете получить доступ к отчетам по этим конечным точкам и отслеживать, что пошло не так. Вы готовы приступить к устранению проблемы, затрагивающей ваших пользователей.

Пример отчета

{
  "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"
}

Варианты использования и типы отчетов

API для создания отчетов можно настроить таким образом, чтобы он помогал отслеживать множество типов важных предупреждений или проблем, возникающих на вашем сайте:

Отчеты

Как выглядят отчёты?

Браузер отправляет отчеты на настроенную вами конечную точку. Он отправляет запросы следующего вида:

POST
Content-Type: application/reports+json

В состав этих запросов входит список отчетов.

Пример списка отчетов

[
  {
    "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"
  }
]

Вот данные, которые вы можете найти в каждом из этих отчетов:

Отчеты аккредитованных специалистов

Конечные точки формирования отчетов, имеющие тот же источник , что и страница, генерирующая отчет, получают учетные данные (cookie) в запросах, содержащих отчеты.

Учетные данные могут предоставить полезную дополнительную информацию об отчете; например, вызывает ли учетная запись конкретного пользователя ошибки постоянно или определенная последовательность действий, выполняемых на других страницах, вызывает отчет на этой странице.

Когда и как браузер отправляет отчеты?

Отчеты отправляются внеполосным способом с вашего сайта : браузер контролирует, когда они отправляются на настроенные конечные точки. Также нет возможности контролировать, когда браузер отправляет отчеты; он автоматически захватывает, ставит в очередь и отправляет их в подходящее время.

Это означает, что при использовании API для создания отчетов практически не возникает проблем с производительностью.

Отчеты отправляются с задержкой — до минуты — чтобы увеличить вероятность отправки отчетов партиями. Это экономит пропускную способность сети пользователя, что особенно важно на мобильных устройствах. Браузер также может задерживать доставку, если он занят обработкой более приоритетных задач или если пользователь в это время находится в медленной или перегруженной сети.

Вопросы, касающиеся третьих сторон и собственных интересов.

Отчеты, генерируемые в связи с нарушениями или устареванием функций на вашей странице , будут отправляться на настроенные вами конечные точки. Это включает нарушения, совершенные сторонними скриптами, работающими на вашей странице.

Нарушения или устаревание, произошедшие во встроенном в вашу страницу iframe, не будут сообщаться на ваши конечные точки (по крайней мере, по умолчанию). iframe может настроить собственную систему отчетности и даже отправлять отчеты в службу отчетности вашего сайта — то есть, вашего собственного сайта; но это зависит от сайта, во встроенном iframe. Также обратите внимание, что большинство отчетов генерируются только в случае нарушения политики страницы, и что политики вашей страницы и политики iframe различаются.

Пример с устаревшими функциями

Поддержка браузеров

В следующей таблице приведена сводная информация о поддержке браузерами API отчетов версии 1 , то есть с заголовком Reporting-Endpoints . Поддержка браузерами API отчетов версии 0 (заголовок Report-To ) аналогична, за исключением одного типа отчетов: ведение журнала сетевых ошибок не поддерживается в новом API отчетов. Подробности см. в руководстве по миграции .

В этой таблице приведена сводная информация только о поддержке параметра report-to с новым заголовком Reporting-Endpoints . Если вы планируете перейти на использование заголовка Reporting-Endpoints , ознакомьтесь с рекомендациями по миграции отчетов CSP .

Использование API для создания отчетов

Определите, куда следует отправлять отчеты.

У вас есть два варианта:

• Отправляйте отчеты в существующую службу сбора отчетов.
• Отправляйте отчеты в систему сбора данных, которую вы создадите и будете использовать самостоятельно.

Вариант 1: Использовать существующий сервис сбора отчетов.

Примерами сервисов по сбору отчетов являются:

• отчет-ури
• урипорты

Если вам известны другие решения, создайте заявку, чтобы сообщить нам об этом, и мы обновим этот пост!

Помимо цены, при выборе сервиса для сбора отчетов следует учитывать следующие моменты: 🧐

• Поддерживает ли этот сборщик все типы отчетов? Например, не все решения для создания отчетов поддерживают отчеты COOP/COEP.
• Вы готовы делиться URL-адресами своего приложения с сторонним сервисом сбора отчетов? Даже если браузер удалит конфиденциальную информацию из этих URL-адресов, утечка конфиденциальных данных все равно может произойти . Если это кажется слишком рискованным для вашего приложения, используйте собственную точку доступа для формирования отчетов.

Вариант 2: Создать и запустить собственную систему сбора отчетов.

Создание собственного сервера для приема отчетов — задача не из легких. Для начала вы можете создать форк нашего легковесного шаблона. Он построен на Express и может принимать и отображать отчеты.

При создании собственного сборщика отчетов:

• Проверяйте POST запросы с Content-Type равным application/reports+json , чтобы распознать запросы на отчеты, отправляемые браузером на вашу конечную точку.
• Если ваша конечная точка находится на другом домене, отличном от вашего сайта, убедитесь, что она поддерживает предварительные запросы CORS .

Вариант 3: Объединить варианты 1 и 2

Возможно, вам захочется поручить обработку некоторых типов отчетов конкретному поставщику, а для других использовать собственное решение.

В этом случае задайте несколько конечных точек следующим образом:

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

Настройте заголовок Reporting-Endpoints

Установите заголовок ответа Reporting-Endpoints . Его значение должно представлять собой одну или несколько пар ключ-значение, разделенных запятыми:

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

Если вы переходите с устаревшего API отчетов на новый API отчетов, может быть целесообразно установить параметры Reporting-Endpoints и Report-To . Подробности см. в руководстве по миграции . В частности, если вы используете отчетность о нарушениях Content-Security-Policy только с помощью директивы report-uri , ознакомьтесь с шагами миграции для отчетности CSP .

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

Ключи (имена конечных точек)

Каждый ключ может иметь имя по вашему выбору, например, main-endpoint или endpoint-1 . Вы можете задать разные именованные конечные точки для разных типов отчетов — например, my-coop-endpoint , my-csp-endpoint . Таким образом, вы можете направлять отчеты на разные конечные точки в зависимости от их типа.

Если вы хотите получать сообщения о вмешательствах , устаревании , сбоях или их комбинации, установите конечную точку с именем default .

Если в заголовке Reporting-Endpoints не указана конечная точка default , отчеты этого типа отправляться не будут (хотя они будут генерироваться).

Значения (URL-адреса)

Каждое значение представляет собой URL-адрес по вашему выбору, куда будут отправляться отчеты. URL-адрес, который нужно здесь указать, зависит от того, что вы выбрали на шаге 1.

URL конечной точки:

• Путь должен начинаться с косой черты ( / ). Относительные пути не поддерживаются.
• Возможна междоменная инициализация; однако в этом случае учетные данные не отправляются вместе с отчетами .

Примеры

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

Затем вы можете использовать каждую именованную конечную точку в соответствующей политике или использовать одну единственную конечную точку во всех политиках.

Где разместить заголовок?

В новом API для создания отчетов — том, который рассматривается в этой статье — отчеты привязаны к определенным документам . Это означает, что для одного заданного источника разные документы, такие как site.example/page1 и site.example/page2 , могут отправлять отчеты на разные конечные точки.

Чтобы получать сообщения о нарушениях или устаревших функциях, происходящих на любой странице вашего сайта, установите заголовок в качестве промежуточного ПО во всех ответах.

Вот пример на 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();
});

Отредактируйте свои правила

Теперь, когда заголовок Reporting-Endpoints настроен, добавьте директиву report-to к каждому заголовку политики, для которой вы хотите получать отчеты о нарушениях. Значением параметра report-to должна быть одна из именованных конечных точек, которые вы настроили.

Вы можете использовать несколько конечных точек для нескольких политик или использовать разные конечные точки для разных политик.

report-to не требуется для отчетов об устаревании , вмешательствах и сбоях . Эти отчеты не привязаны к какой-либо политике. Они генерируются до тех пор, пока настроена конечная точка default , и отправляются на эту конечную точку 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

Отладьте настройки отчетов.

Целенаправленно создавайте отчеты.

При настройке API для создания отчетов вам, вероятно, потребуется намеренно нарушить свои правила, чтобы проверить, генерируются и отправляются ли отчеты должным образом.

Экономьте время

Отчеты могут отправляться с задержкой — примерно на минуту, что довольно долго при отладке. 😴 К счастью, при отладке в Chrome можно использовать флаг --short-reporting-delay , чтобы получать отчеты сразу после их генерации.

Выполните эту команду в терминале, чтобы включить этот флаг:

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

Используйте инструменты разработчика

В Chrome используйте инструменты разработчика, чтобы просмотреть отчеты, которые были отправлены или будут отправлены.

По состоянию на октябрь 2021 года эта функция находится в экспериментальном режиме. Для её использования выполните следующие шаги:

1. Используйте Chrome версии 96 и новее (проверьте, введя chrome://version в браузере).
2. Введите или вставьте chrome://flags/#enable-experimental-web-platform-features в адресную строку Chrome.
3. Нажмите «Включено» .
4. Перезапустите браузер.
5. Откройте инструменты разработчика Chrome.
6. В инструментах разработчика Chrome откройте «Настройки». В разделе «Эксперименты» в панели «Приложение» нажмите «Включить API отчетов» .
7. Перезагрузите инструменты разработчика.
8. Перезагрузите страницу. Отчеты, созданные на странице, открытой в инструментах разработчика Chrome, будут отображаться на панели приложений в разделе «API отчетов» .

Статус отчета

В столбце «Статус» отображается информация об успешной отправке отчета.

Сообщения удаляются через некоторое время, независимо от того, были ли они успешно отправлены.

Поиск неисправностей

Отчеты не создаются или не отправляются на ваше устройство должным образом? Вот несколько советов по устранению этой проблемы.

Отчеты не формируются.

Отчеты, отображаемые в инструментах разработчика, сгенерированы корректно. Если ожидаемый вами отчет не отображается в этом списке:

• Проверьте report-to в ваших политиках. Если он настроен неправильно, отчет не будет сгенерирован. Перейдите в раздел «Редактировать политики» , чтобы исправить это. Дополнительный способ устранения неполадок — проверить консоль DevTools в Chrome: если в консоли появится ошибка, связанная с ожидаемым нарушением, это означает, что ваша политика, вероятно, настроена правильно.
• Обратите внимание, что в этом списке будут отображаться только отчеты, созданные для документа, в котором открыты инструменты разработчика. Например: если ваш сайт site1.example содержит iframe site2.example , который нарушает правила и, следовательно, генерирует отчет, этот отчет отобразится в инструментах разработчика только в том случае, если вы откроете iframe в отдельном окне и откроете инструменты разработчика для этого окна.

Отчеты создаются, но не отправляются или не принимаются.

Что делать, если вы видите отчет в инструментах разработчика, но ваша конечная точка его не получает?

• Обязательно используйте короткие задержки . Возможно, причина, по которой вы не видите отчет, заключается в том, что он еще не был отправлен!

• Проверьте конфигурацию заголовка Reporting-Endpoints . Если с ней есть проблема, корректно сгенерированный отчет не будет отправлен. В DevTools статус отчета останется Queued (он может перейти в Pending , а затем быстро вернуться в Queued при попытке доставки). Вот некоторые распространенные ошибки, которые могут привести к этому:

• Конечная точка используется, но не настроена. Пример:

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

• Отсутствует конечная точка default . Некоторые типы отчетов, такие как отчеты об устаревании и отчеты о вмешательстве, будут отправляться только на конечную точку с именем default . Подробнее см. в разделе «Настройка заголовка Reporting-Endpoints» .

• Проверьте синтаксис заголовков вашей политики на наличие ошибок, например, отсутствующих кавычек. Подробнее см . здесь.

• Убедитесь, что ваша конечная точка может обрабатывать входящие запросы.

  • Убедитесь, что ваша конечная точка поддерживает предварительные запросы CORS. В противном случае она не сможет получать отчеты.

  • Проверьте поведение вашей конечной точки. Для этого, вместо ручного создания отчетов, вы можете эмулировать браузер, отправляя на вашу конечную точку запросы, которые выглядят так, как будто их отправляет браузер. Выполните следующие действия:

  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
  

  Ваш конечный пункт должен ответить кодом успешного выполнения ( 200 или другим кодом успешного ответа 2xx ). Если этого не происходит, значит, проблема в его конфигурации.

Соответствующие механизмы отчетности

Только отчет

Заголовки политики -Report-Only и Reporting-Endpoints работают совместно.

Конечные точки, настроенные в Reporting-Endpoints и указанные в поле report-to в разделах Content-Security-Policy », Cross-Origin-Embedder-Policy и Cross-Origin-Opener-Policy , будут получать отчеты при нарушении этих политик.

Конечные точки, настроенные в Reporting-Endpoints , также могут быть указаны в поле report-to разделов Content-Security-Policy-Report-Only , Cross-Origin-Embedder-Policy-Report-Only и Cross-Origin-Opener-Policy-Report-Only . Они также будут получать отчеты при нарушении этих политик.

Хотя отчеты отправляются в обоих случаях, заголовки -Report-Only не обеспечивают соблюдение правил: ничего не сломается и не будет заблокировано, но вы будете получать отчеты о том, что могло бы сломаться или быть заблокировано.

ReportingObserver

JavaScript API ReportingObserver поможет вам отслеживать предупреждения на стороне клиента.

ReportingObserver и заголовок Reporting-Endpoints генерируют отчеты, которые выглядят одинаково, но позволяют решать несколько разные задачи.

Используйте ReportingObserver если:

• Вам нужно отслеживать только устаревшие функции или вмешательства браузера. ReportingObserver отображает предупреждения на стороне клиента, такие как устаревшие функции и вмешательства браузера, но, в отличие от Reporting-Endpoints , он не собирает никаких других типов отчетов, таких как нарушения CSP или COOP/COEP.
• Необходимо реагировать на эти нарушения в режиме реального времени. ReportingObserver позволяет прикрепить функцию обратного вызова к событию нарушения.
• Вы хотите добавить к отчету дополнительную информацию для облегчения отладки, используя пользовательскую функцию обратного вызова .

Ещё одно отличие заключается в том, что ReportingObserver настраивается только на стороне клиента: вы можете использовать его, даже если у вас нет контроля над заголовками на стороне сервера и вы не можете установить Reporting-Endpoints .

Дополнительная информация

• Руководство по миграции с Reporting API версии 0 на версию 1
• ReportingObserver
• Спецификация: устаревший API для создания отчетов (версия 0)
• Спецификация: новый API для создания отчетов (версия 1)

Главное изображение предоставлено Nine Koepfer / @enka80 на Unsplash , отредактировано. Большое спасибо Иану Клелланду, Эйдзи Китамуре и Милице Михайловиа за их отзывы и предложения по этому документу.