Supervisa tu aplicación web con la API de informes

Usa la API de Reporting para supervisar incumplimientos de seguridad, llamadas a la API obsoletas y mucho más.

Maud Nalpas

Algunos errores solo ocurren en producción. No los verás de forma local ni durante porque los usuarios, las redes y los dispositivos reales cambiar las reglas del juego. La API de Reporting ayuda a detectar algunos de estos errores, como incumplimientos de seguridad o APIs obsoletas y que pronto dejarán de estar disponibles llamadas en tu sitio y las transmite a un extremo que hayas especificada.

Te permite declarar lo que quieres supervisar mediante encabezados HTTP, y es operados por el navegador.

Configurar la API de Reporting te brinda la tranquilidad de que cuando los usuarios experimentan estos tipos de errores, los sabrás para poder corregirlos.

En esta publicación, se explica qué puede hacer esta API y cómo usarla. ¡Comencemos!

Demostración y código

Observa cómo funciona la API de Reporting a partir de Chrome 96 y versiones posteriores (Chrome Beta o Canary, a partir de octubre de 2021).

Descripción general

Supongamos que tu sitio, site.example, tiene una política de seguridad del contenido y una política de documentos. ¿No sabes qué hacen? No te preocupes, seguirás para entender este ejemplo.

Decides supervisar tu sitio para saber cuándo se incumplen estas políticas, pero también debes vigilar las APIs obsoletas o que pronto dejarán de estar disponibles tu base de código

Para hacerlo, configura un encabezado Reporting-Endpoints y asigna estos extremos a través de la directiva report-to en tus políticas cuando sea necesario.

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

Sucede algo imprevisto y estas políticas se incumplen para algunos de tus usuarios.

Ejemplos de incumplimientos

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, cargado por 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;

El navegador genera un informe de incumplimiento de la CSP, un informe de incumplimiento de la política de documentos y un informe de baja. que captan estos problemas.

Con una breve demora (de hasta un minuto), el navegador envía los informes a la extremo que se configuró para este tipo de incumplimiento. Los informes se envían fuera de banda por el navegador en sí (no por tu servidor ni por tu sitio).

Los extremos reciben estos informes.

Ahora puedes acceder a los informes en estos extremos y supervisar qué salió mal. Está todo listo para que comiences a solucionar el problema que afecta a tus usuarios.

Informe de ejemplo

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

Casos de uso y tipos de informes

La API de Reporting se puede configurar para ayudarte a supervisar muchos tipos de advertencias o problemas interesantes que ocurren en todo tu sitio:

Informes

¿Qué aspecto tienen los informes?

El navegador envía informes al extremo que configuraste. y envía solicitudes que tienen el siguiente aspecto:

POST
Content-Type: application/reports+json

La carga útil de estas solicitudes es una lista de informes.

Ejemplo de lista de informes

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

A continuación, te mostramos los datos que puedes encontrar en cada uno de estos informes:

Informes acreditados

Los extremos de informes que tienen el mismo origen que la página que genera el informe reciben las credenciales. (cookies) en las solicitudes que contienen los informes.

Las credenciales pueden proporcionar contexto adicional útil sobre el informe. para por ejemplo, si la cuenta de un usuario determinado activa errores de forma constante o si una secuencia determinada de acciones realizadas en otras páginas activa un informe en esta página.

¿Cuándo y cómo envía el navegador los informes?

Los informes se entregan fuera de banda desde tu sitio: el navegador controla cuándo se envían a los extremos configurados. Tampoco hay forma de controlar cuándo el navegador envía informes; los captura, los pone en cola y los envía automáticamente a una un momento adecuado.

Esto significa que hay poco o ningún problema de rendimiento cuando se usa la API de Reporting.

Los informes se envían con una demora (de hasta un minuto) para aumentar las posibilidades de enviar informes en lotes. Esto ahorra ancho de banda para respetar la conexión de red del usuario, lo que es especialmente importante en los dispositivos móviles. El navegador también puede retrasar la entrega si está ocupado procesando una prioridad más alta o si el usuario está en una red lenta o congestionada en ese momento.

Problemas propios y de terceros

Se enviarán los informes que se generen debido a incumplimientos o bajas que ocurran en tu página. a los extremos que configuraste. Esto incluye los incumplimientos cometidos por secuencias de comandos de terceros. que se ejecuta en tu página.

Los incumplimientos o las bajas que ocurran en un iframe de origen cruzado incorporado en tu página no se informará a sus extremos (al menos no de forma predeterminada). Un iframe puede configurar sus propios generar informes e incluso enviar informes al servicio de informes de su sitio (es decir, al de los datos de origen); pero así es al sitio enmarcado. Tenga en cuenta que la mayoría de las denuncias se generan solo si se incumple la política de una página y que las políticas de tu página y las del iframe sean diferentes.

Ejemplo con bajas

Navegadores compatibles

En la siguiente tabla, se resume la compatibilidad de los navegadores con la API de Reporting v1, es decir, con las Encabezado Reporting-Endpoints. La compatibilidad del navegador con la API de Reporting v0 (encabezado Report-To) es la igual, excepto por un tipo de informe: el registro de errores de red no es compatible con la nueva API de Reporting. Para obtener más detalles, consulta la guía de migración.

En esta tabla, solo se resume la compatibilidad con report-to con el nuevo encabezado Reporting-Endpoints. Lee las sugerencias de migración de informes de CSP si planeas migrar a Reporting-Endpoints.

Usa la API de Reporting

Decide a dónde deben enviarse los informes

Tienes estas dos opciones:

• Envía informes a un servicio de recopilador de informes existente.
• Envía informes a un recopilador de informes que crees y administres.

Opción 1: Usa un servicio de recopilador de informes existente

Estos son algunos ejemplos de servicios de recopilador de informes:

• informe-uri
• uriportes

Si conoces otras soluciones, infórmalo para informarnos, y actualizaremos esta publicación.

Además de los precios, ten en cuenta los siguientes puntos cuando selecciones un recopilador de informes: 🧐

• ¿Este recopilador admite todos los tipos de informes? Por ejemplo, no todas las soluciones de extremos de informes respaldar los informes COOP/COEP.
• ¿Puedes compartir alguna de las URLs de tu aplicación con un recopilador de informes de terceros? Incluso si el navegador quita la información sensible de estas URLs, es posible que la información sensible se filtre de esta manera. Si esto suena demasiado arriesgado para en tu aplicación, operar tu propio extremo de informes.

Opción 2: Crea y opera tu propio recopilador de informes

Crear tu propio servidor que recibe informes no es tan trivial. Para comenzar, puedes bifurcar nuestro código estándar ligero. Se creó con Express y puede recibir y mostrar informes.

1. Ve al recopilador de informes estándar.

2. Haz clic en Remix para editar para que el proyecto se pueda editar.

3. Ya tienes el clon. Puedes personalizarlo según tus propios fines.

Si no estás usando el código estándar y estás creando tu propio servidor desde cero, haz lo siguiente:

• Verifica si hay solicitudes POST con un Content-Type de application/reports+json para reconocer informes las solicitudes enviadas por el navegador a tu extremo.
• Si tu extremo se encuentra en un origen diferente al de tu sitio, asegúrate de que admita las solicitudes de comprobación previa de CORS.

Opción 3: Combina las opciones 1 y 2

Puede que un proveedor específico se encargue de algunos tipos de informes, pero que para otros.

En este caso, configura varios extremos de la siguiente manera:

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

Configura el encabezado Reporting-Endpoints

Establece un encabezado de respuesta Reporting-Endpoints. Su valor debe ser uno o una serie de valores separados por comas Pares clave-valor:

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

Si migras de la API de Reporting heredada a la nueva API, tal vez sea conveniente establecer ambos, Reporting-Endpoints y Report-To. Consulta los detalles en la guía de migración. En particular, si usas informes para Content-Security-Policy incumplimientos solo a través de la directiva report-uri, consulta los pasos de migración para los informes de CSP.

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

Claves (nombres de extremos)

Cada clave puede ser el nombre que elijas, como main-endpoint o endpoint-1. Puedes establecer distintos extremos con nombre para distintos informes tipos, por ejemplo, my-coop-endpoint, my-csp-endpoint. De esta forma, puede enrutar informes a distintos extremos según su tipo.

Si quieres recibir una intervención, una baja o una falla informes, establece un extremo llamado default.

Si el encabezado Reporting-Endpoints no define ningún extremo default, los informes de este tipo no se enviarán (aunque se generarán).

Valores (URL)

Cada valor es la URL que tú elijas, a la que se enviarán los informes. La URL según lo que decidas en el Paso 1.

Una URL de extremo:

• Debe comenzar con una barra (/). Las rutas de acceso relativas no son compatibles.
• Puede ser de origen cruzado. pero, en ese caso, no se envían las credenciales con los informes.

Ejemplos

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

Luego, puedes usar cada extremo con nombre en la política correspondiente o usar uno extremo único en todas las políticas.

¿Dónde establecer el encabezado?

En la nueva API de Reporting, la que se aborda en esta posterior— los informes se limitan a documentos. Esto significa que, para uno dado origen, documentos diferentes, como site.example/page1 y site.example/page2 puede enviar informes a diferentes extremos.

Para recibir informes sobre incumplimientos o bajas en cualquier página de tu , establece el encabezado como middleware en todas las respuestas.

Este es un ejemplo en 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();
});

Edita tus políticas

Ahora que el encabezado Reporting-Endpoints está configurado, agrega un report-to. directiva a cada encabezado de política para el que deseas recibir incumplimientos informes. El valor de report-to debe ser uno de los extremos con nombre que configurado.

Puedes usar el extremo múltiple para varias políticas o usar diferentes extremos de todas las políticas.

report-to no es necesario para la baja, la intervención y la falla. informes. Estos informes no están sujetos a ninguna política. Se generan siempre y cuando se configura un extremo default que se envía a este extremo default.

Ejemplo

# 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

Ejemplo de código

Para ver todo esto en contexto, a continuación se muestra un servidor de nodos de ejemplo que usa Express y reúne todas las piezas analizadas en este artículo. Muestra cómo configurar informes para distintos tipos de informes y mostrar los resultados.

Depura la configuración de tus informes

Generar informes de manera intencional

Cuando configures la API de Reporting, es probable que debas infringir tus políticas para verificar si los informes se generan y envían como se espera. Para ver un ejemplo de código que infringe las políticas y hace otras acciones perjudiciales generar informes de todo tipo, consulta la demostración.

Ahorra tiempo

Los informes pueden enviarse con una demora, aproximadamente un minuto, que es un tiempo largo. durante la depuración. Entiendo. Por suerte, cuando depures en Chrome, puedes usar la función experimental. --short-reporting-delay para recibir informes en cuanto se generen.

Ejecuta este comando en la terminal para activar la marca:

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

Cómo usar las Herramientas para desarrolladores

En Chrome, usa las Herramientas para desarrolladores para ver los informes que se enviaron o se enviarán.

A partir de octubre de 2021, esta función será experimental. Para usarla, sigue estos pasos:

1. Usas Chrome 96 y versiones posteriores (para comprobarlo, escribe chrome://version en el navegador).
2. Escribe o pega chrome://flags/#enable-experimental-web-platform-features en la barra de URL de Chrome.
3. Haz clic en Habilitado.
4. Reinicia el navegador.
5. Abra las Herramientas para desarrolladores de Chrome.
6. En las Herramientas para desarrolladores de Chrome, abre la Configuración. En Experimentos, haz clic en Habilitar el panel de la API de Reporting el panel Aplicación.
7. Vuelve a cargar Herramientas para desarrolladores.
8. Vuelve a cargar tu página. Los informes generados por la página en la que se abre Herramientas para desarrolladores se mostrarán en Herramientas para desarrolladores de Chrome Panel Application, en API de Reporting.

Estado del informe

En la columna Estado, se indica si un informe se envió correctamente.

Los informes se quitan después de un tiempo, ya sea que se envíen correctamente o no.

Soluciona problemas

¿Los informes no se generan o no se envían como se espera a su extremo? Aquí encontrarás algunas sugerencias para solucionar este problema.

Los informes no se generan.

Los informes que aparecen en Herramientas para desarrolladores se generaron correctamente. Si el informe que esperas no aparece en esta lista, haz lo siguiente:

• Verifica report-to en tus políticas. Si está mal configurado, una no se generará el informe. Ve a Edita tus políticas para solucionar el problema. Otra forma de solucionar este problema es comprobar la consola de Herramientas para desarrolladores en Chrome: si un en la consola por el incumplimiento que esperabas, esto significa que probablemente tu política configurar correctamente.
• Ten en cuenta que solo los informes que se generaron para el documento en el que está abierto Herramientas para desarrolladores aparecerán en esta lista. Ejemplo: Si tu sitio site1.example incorpora un iframe site2.example que infringe una política y, por lo tanto, genera un informe, este se mostrará en Herramientas para desarrolladores solo si abres la herramienta iframe en su propia ventana y abrir Herramientas para desarrolladores en esa ventana.

Los informes se generan, pero no se envían o no se reciben

¿Qué sucede si puedes ver un informe en Herramientas para desarrolladores, pero tu extremo no lo recibe?

• Asegúrate de usar demoras breves. Quizás no puedas ver un informe porque todavía no se envió.

• Verifica la configuración del encabezado Reporting-Endpoints. Si surge algún problema, informa que correctamente no se enviará. En las Herramientas para desarrolladores, el estado del informe permanecerá Queued (puede saltar a Pending y volver rápidamente a Queued cuando se realiza un intento de entrega en este caso. Estos son algunos de los errores comunes que pueden causar esta situación:

• El extremo se usa, pero no se configuró. Ejemplo:

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

• Falta el extremo default. Algunos tipos de informes, como la baja y la intervención informes solo se enviarán al extremo llamado default. Obtén más información en Configura el encabezado de informes de extremos.

• Busca problemas en la sintaxis de los encabezados de políticas, como comillas faltantes. Consulta los detalles.

• Verifica que tu extremo pueda controlar las solicitudes entrantes.

  • Asegúrate de que tu extremo sea compatible con las solicitudes preliminares de CORS. De lo contrario, no podrá recibir informes.

  • Probar el comportamiento del extremo Para hacerlo, en lugar de generar manualmente, puedes emular el navegador enviando a tus extremos solicitudes similares lo que enviaría el navegador. Ejecuta lo siguiente:

  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
  

  Tu extremo debería responder con un código de éxito (200 o algún otro código de respuesta correcta 2xx). Si no lo hace, hay un problema con su configuración.

Mecanismos de denuncia relacionados

Solo informes

Los encabezados de política -Report-Only y Reporting-Endpoints funcionan en conjunto.

Los extremos están configurados en Reporting-Endpoints y se especifican en el campo report-to de Content-Security-Policy: Cross-Origin-Embedder-Policy y Cross-Origin-Opener-Policy, recibirán denuncias cuando se incumplan estas políticas.

Los extremos configurados en Reporting-Endpoints también se pueden especificar en el Campo report-to de Content-Security-Policy-Report-Only: Cross-Origin-Embedder-Policy-Report-Only y Cross-Origin-Opener-Policy-Report-Only. También recibirán informes cuando se incumplan estas políticas.

Si bien los informes se envían en ambos casos, los encabezados -Report-Only no aplican el políticas: no se producirá ningún error ni se bloqueará, pero recibirás informes de lo que se habría roto o bloqueado.

ReportingObserver

La API de JavaScript de ReportingObserver puede ayudarte observar las advertencias del cliente

ReportingObserver y el encabezado Reporting-Endpoints generan informes que tienen el mismo aspecto, pero permiten casos de uso ligeramente diferentes.

Usa ReportingObserver en el siguiente caso:

• Solo quieres supervisar las bajas o las intervenciones del navegador. ReportingObserver muestra advertencias del cliente, como las bajas. e intervenciones de navegador, pero, a diferencia de Reporting-Endpoints, no capturar cualquier otro tipo de denuncia, como infracciones de CSP, COOP/COEP
• Debes reaccionar a estas infracciones en tiempo real. ReportingObserver marcas Es posible adjuntar una devolución de llamada a un evento de incumplimiento.
• Si deseas adjuntar información adicional a un informe para facilitar la depuración. mediante la devolución de llamada personalizada.

Otra diferencia es que ReportingObserver solo se configura del lado del cliente: puedes usarlo incluso si no tienes control sobre los encabezados del servidor ni establecer Reporting-Endpoints.

Lecturas adicionales

• Guía de migración de la API de Reporting v0 a v1
• ReportingObserver
• Especificación: API de Reporting heredada (v0)
• Especificación: nueva API de Reporting (v1)

Hero image de Nine Koepfer / @enka80 en Se editó Unsplash. Muchas gracias a Ian Clelland, Eiji Kitamura y Milica Mihajlija por sus opiniones y sugerencias en este artículo.