Usa la API de Reporting para supervisar las infracciones de seguridad, las llamadas a la API obsoletas y mucho más.
Algunos errores solo ocurren en la producción. No los verás de forma local ni durante el desarrollo porque los usuarios reales, las redes reales y los dispositivos reales cambian el juego. La API de Reporting ayuda a detectar algunos de estos errores, como incumplimientos de seguridad o llamadas a la API obsoletas y que pronto dejarán de estar disponibles en tu sitio, y los transmite al extremo que especificaste.
Te permite declarar lo que deseas supervisar mediante encabezados HTTP, y es el navegador que opera.
La configuración de la API de Reporting te brinda la tranquilidad de saber que, cuando los usuarios experimenten estos tipos de errores, los puedas corregir.
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 otra de documentos. ¿No sabes qué hacen? Está bien, aún podrás
comprender este ejemplo.
Decides supervisar tu sitio para saber cuándo se incumplen estas políticas y, además, para vigilar las APIs obsoletas o que pronto lo dejarán de estar disponibles que puede estar usando tu base de código.
Para hacerlo, configura un encabezado Reporting-Endpoints
y asigna estos nombres de 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
Cuando sucede algo imprevisto, se infringen estas políticas para algunos de los usuarios.
Ejemplos de incumplimiento
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 las políticas de documentos y un informe de baja que capturan estos problemas.
Con una demora breve (hasta un minuto), el navegador envía los informes al extremo que se configuró para este tipo de incumplimiento. El propio navegador envía los informes fuera de banda (no tu servidor ni tu sitio).
Los extremos reciben estos informes.
Ahora puedes acceder a los informes en estos extremos y supervisar qué salió mal. Ya puedes comenzar 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 tu sitio:
Tipo de informe | Ejemplo de una situación en la que se generará un informe |
---|---|
Incumplimiento de la CSP (solo nivel 3) | Estableciste una Content-Security-Policy (CSP) en una de tus páginas, pero la página intenta cargar una secuencia de comandos que tu CSP no permite. |
Incumplimiento de COOP | Configuraste una Cross-Origin-Opener-Policy en una página, pero una ventana de origen cruzado está intentando interactuar directamente con el documento. |
Incumplimiento de la COEP | Configuraste un Cross-Origin-Embedder-Policy en una página, pero el documento incluye un iframe de origen cruzado que no se habilitó para que los documentos de origen cruzado lo carguen. |
Incumplimiento de política del documento | La página tiene una política de documento que impide el uso de document.write , pero una secuencia de comandos intenta llamar a document.write . |
Incumplimiento de la política de permisos | La página tiene una política de permisos que impide el uso del micrófono y una secuencia de comandos que solicita la entrada de audio. |
Advertencia de baja | La página usa una API que está obsoleta o dejará de estar disponible; la llama directamente o a través de una secuencia de comandos de terceros de nivel superior. |
Intervención | La página intenta hacer algo que el navegador decide no respetar, por razones de seguridad, rendimiento o experiencia del usuario. Ejemplo en Chrome: La página usa document.write en redes lentas o llama a navigator.vibrate en un marco de origen cruzado con el que el usuario aún no interactuó. |
Accidente automovilístico | El navegador falla mientras tu sitio está abierto. |
informes
¿Qué aspecto tienen los informes?
El navegador envía informes al extremo que configuraste. Envía solicitudes con el siguiente aspecto:
POST
Content-Type: application/reports+json
La carga útil de estas solicitudes es una lista de informes.
Lista de ejemplo 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 presentamos los datos que puedes encontrar en cada uno de estos informes:
Campo | Descripción |
---|---|
age |
Es la cantidad de milisegundos entre la marca de tiempo del informe y la hora actual. |
body |
Los datos reales del informe, serializados en una cadena JSON. Los campos contenidos en el body de un informe se determinan según el type del informe. ⚠️ Los informes de diferentes tipos tienen cuerpos diferentes.
Para ver el cuerpo exacto de cada tipo de informe, consulta el extremo de informes de demostración y sigue las instrucciones para generar informes de ejemplo. |
type |
Un tipo de informe, como csp-violation o coep |
url |
La dirección del documento o trabajador desde el que se generó el informe. Los datos sensibles, como el nombre de usuario, la contraseña y el fragmento, se extraen de esta URL. |
user_agent |
El encabezado User-Agent de la solicitud a partir de la cual se generó el informe. |
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 brindar un contexto adicional útil sobre el informe; por ejemplo, si la cuenta de un usuario determinado activa errores de forma constante o si una determinada secuencia de acciones realizadas en otras páginas activa un informe en esta página.
¿Cuándo y cómo envía informes el navegador?
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, pone en cola y los envía automáticamente en un momento adecuado.
Esto significa que hay un problema de rendimiento mínimo o nulo cuando se usa la API de informes.
Los informes se envían con una demora (hasta un minuto) para aumentar las probabilidades 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 dispositivos móviles. El navegador también puede retrasar la entrega si está ocupado procesando un trabajo de mayor prioridad o si el usuario se encuentra en una red lenta o congestionada en ese momento.
Problemas propios y de terceros
Los informes que se generen debido a incumplimientos o bajas que se produzcan en tu página se enviarán a los extremos que configuraste. Esto incluye incumplimientos cometidos por secuencias de comandos de terceros que se ejecutan en tu página.
Los incumplimientos o las bajas que se produjeron en un iframe de origen cruzado incorporado en tu página no se informarán a tus extremos (al menos no de forma predeterminada). Un iframe podría configurar sus propios informes, así como generar informes al servicio de informes de tu sitio, es decir, el propio; pero eso depende del sitio enmarcado. Además, ten en cuenta que la mayoría de los informes solo se generan si se incumple la política de una página, y que las políticas de tu página y del iframe son 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 el encabezado Reporting-Endpoints
. La compatibilidad del navegador con la API de Reporting v0 (encabezado Report-To
) es la misma, excepto en un tipo de informe: no se admite el registro de errores de red en la nueva API de Reporting.
Consulta la guía de migración para obtener más detalles.
Tipo de informe | Chrome | Chrome para iOS | Safari | Firefox | Conexión de integración |
---|---|---|---|---|---|
Incumplimiento en la CSP (solo nivel 3)* | ✔ Sí | ✔ Sí | ✔ Sí | ✘ No | ✔ Sí |
Registro de errores de red | ✘ No | ✘ No | ✘ No | ✘ No | ✘ No |
Incumplimiento de COOP/COEP | ✔ Sí | ✘ No | ✔ Sí | ✘ No | ✔ Sí |
Todos los demás tipos: Incumplimiento de política de documentos, baja, intervención y falla | ✔ Sí | ✘ No | ✘ No | ✘ No | ✔ Sí |
En esta tabla, solo se resume la compatibilidad de report-to
con el nuevo encabezado Reporting-Endpoints
. Lee las sugerencias de migración de informes de la CSP si quieres migrar a Reporting-Endpoints
.
Usa la API de informes
Decide dónde enviar 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 compiles y operes por tu cuenta.
Opción 1: Usa un servicio de recopilador de informes existente
Algunos ejemplos de servicios de recopilador de informes son los siguientes:
Si conoces otras soluciones, abre un problema 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 es compatible con todos los tipos de informes? Por ejemplo, no todas las soluciones de extremos de informes admiten informes COOP/COEP.
- ¿Te gustaría compartir alguna de las URLs de tu aplicación con un recopilador de informes externo? Incluso si el navegador quita la información sensible de estas URLs, es posible que esta información se filtre de esta manera. Si esto parece demasiado riesgoso para tu aplicación, opera tu propio extremo de informes.
Opción 2: Crea y administra tu propio recopilador de informes
Crear tu propio servidor que reciba informes no es tan trivial. Para comenzar, puedes bifurcar nuestro código estándar liviano. Se basa en Express y puede recibir y mostrar informes.
Dirígete al recopilador de informes estándar.
Haz clic en Remix to Edit para que el proyecto sea editable.
Ahora tienes tu clonación. Puedes personalizarlo para tus propios fines.
Si no usas el código estándar y estás compilando tu propio servidor desde cero, haz lo siguiente:
- Verifica si hay solicitudes
POST
con unContent-Type
deapplication/reports+json
para reconocer las solicitudes de informes que envió el navegador a tu extremo. - Si tu extremo se encuentra en un origen diferente al de tu sitio, asegúrate de que sea compatible con las solicitudes de comprobación previa de CORS.
Opción 3: Combina las opciones 1 y 2
Puedes permitir que un proveedor específico se encargue de algunos tipos de informes, pero que tengas una solución interna 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 pares clave-valor separados por comas:
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 de Reporting, recomendamos que configures tanto Reporting-Endpoints
como Report-To
. Consulta los detalles en la guía de migración. En particular, si informas por incumplimientos de Content-Security-Policy
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 un nombre que elijas, como main-endpoint
o endpoint-1
.
Puedes decidir establecer extremos con nombre diferentes para distintos tipos de informes, por ejemplo, my-coop-endpoint
, my-csp-endpoint
. Con esto, puedes enrutar informes a diferentes extremos según su tipo.
Si deseas recibir informes de intervención, baja o fallas, configura 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 sí se generarán).
Valores (URLs)
Cada valor es una URL que eliges, a la que se enviarán los informes. La URL que se establecerá aquí dependerá de lo que hayas decidido en el paso 1.
Una URL de extremo:
- Debe comenzar con una barra (
/
). Las rutas de acceso relativas no son compatibles. - Pueden ser de origen cruzado, pero, en ese caso, las credenciales no se envían 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 un solo extremo en todas las políticas.
¿Dónde se debe establecer el encabezado?
En la nueva API de Reporting, la que se aborda en esta publicación, los informes se limitan a los documentos. Esto significa que, para un origen determinado, diferentes documentos, como site.example/page1
y site.example/page2
, pueden enviar informes a extremos diferentes.
Para recibir un informe por incumplimientos o bajas que ocurren en cualquier página de tu sitio, configura el encabezado como middleware en todas las respuestas.
Aquí tienes 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 una directiva report-to
a cada encabezado de política para el que desees recibir informes de incumplimientos. El valor de report-to
debe ser uno de los extremos con nombre que configuraste.
Puedes usar extremos múltiples para varias políticas o usar extremos diferentes en varias políticas.
report-to
no es necesario para los informes de baja, intervención y falla. Estos informes no están sujetos a ninguna política. Se generan siempre que se haya configurado un extremo default
y se envíen 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 ejemplo de un servidor de nodos que usa Express y reúne todas las partes que se analizan en este artículo. Se muestra cómo configurar informes para varios tipos de informes diferentes y se muestran los resultados.
Depura la configuración de tus informes
Genera informes de manera intencional
Cuando configures la API de Reporting, es probable que debas infringir intencionalmente tus políticas para verificar si los informes se generan y envían como esperas. Para ver un ejemplo de código que incumple las políticas y hace otras acciones perjudiciales que generarán informes de todo tipo, consulta la demostración.
Ahorrar tiempo
Los informes pueden enviarse con una demora, de aproximadamente un minuto, que es un tiempo largo durante la depuración. ⁑ Afortunadamente, cuando realizas una depuración en Chrome, puedes usar la marca --short-reporting-delay
para recibir informes en cuanto se generen.
Ejecuta este comando en la terminal para activar esta 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 los que se enviarán.
A partir de octubre de 2021, esta función es experimental. Para usarla, sigue estos pasos:
- Usa la versión 96 de Chrome o una posterior (para verificar, escribe
chrome://version
en tu navegador) - Escribe o pega
chrome://flags/#enable-experimental-web-platform-features
en la barra de URL de Chrome. - Haz clic en Habilitado.
- Reinicia el navegador.
- Abra las Herramientas para desarrolladores de Chrome.
- En las Herramientas para desarrolladores de Chrome, abra la Configuración. En Experimentos, haz clic en Habilitar el panel de la API de informes en el panel Aplicación.
- Vuelve a cargar Herramientas para desarrolladores.
- Vuelve a cargar tu página. Los informes generados por la página en la que está abierta Herramientas para desarrolladores se mostrarán en el panel Aplicación de las Herramientas para desarrolladores de Chrome, en la sección API de Reporting.
Estado del informe
La columna Estado te indica si un informe se envió correctamente.
Estado | Descripción |
---|---|
Success |
El navegador envió el informe y el extremo respondió con un código de éxito (200 o algún otro código de respuesta de éxito 2xx ). |
Pending |
El navegador está intentando enviar el informe. |
Queued |
Se generó el informe y el navegador no está intentando enviarlo. Un informe aparece como Queued en uno de estos dos casos:
|
MarkedForRemoval |
Después de reintentarlo durante un tiempo (Queued ), el navegador dejó de intentar enviar el informe y pronto lo quitará de su lista de informes para enviar. |
Los informes se quitan después de un tiempo, sin importar si se enviaron o no correctamente.
Solución de problemas
¿Los informes no se generan o no se envían como se espera a su extremo? Estas son algunas sugerencias para solucionar este problema.
No se generan informes
Los informes que aparecen en Herramientas para desarrolladores se generaron correctamente. Si el informe que esperas no aparece en esta lista, haz lo siguiente:
- Revisa la
report-to
en tus políticas. Si está mal configurada, no se generará un informe. Para solucionar este problema, ve a Edita tus políticas. Otra forma de solucionar el problema es revisar la consola de Herramientas para desarrolladores en Chrome. Si aparece un error en la consola con el incumplimiento que esperabas, significa que es probable que la política esté configurada correctamente. - Ten en cuenta que solo se mostrarán en esta lista los informes que se generaron para el documento en el que están abiertas las Herramientas para desarrolladores. Por ejemplo, si tu sitio
site1.example
incorpora un iframesite2.example
que infringe una política y, por lo tanto, genera un informe, este informe se mostrará en Herramientas para desarrolladores solo si abres el iframe en su propia ventana y abres 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 utilizar demoras breves. Tal vez no puedas ver un informe porque aún no se envió.
Verifica la configuración del encabezado
Reporting-Endpoints
. Si hay un problema, no se enviará un informe que se generó correctamente. En las Herramientas para desarrolladores, el estado del informe seguirá siendoQueued
(puede saltar aPending
y, luego, regresar rápidamente aQueued
cuando se realice un intento de entrega) en este caso. Estos son algunos errores comunes que pueden causar este problema:El extremo se usa, pero no se configura. 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 los informes de baja y de intervención, solo se enviarán al extremo llamadodefault
. Obtén más información en Configura el encabezado de Reporting-Endpoints.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 admita las solicitudes de comprobación previa de CORS. De lo contrario, no podrá recibir informes.
Probar el comportamiento de tu extremo Para ello, en lugar de generar informes de forma manual, puedes emular el navegador enviando solicitudes a tu extremo que se parecen a las que enviaría el navegador. Ejecuta este comando:
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 respuesta correcta (
200
o algún otro código de respuesta exitoso2xx
). Si no es así, hay un problema con la configuración.
Mecanismos de denuncia relacionados
Solo informes
Los encabezados de la política -Report-Only
y Reporting-Endpoints
funcionan en conjunto.
Los extremos configurados en Reporting-Endpoints
y especificados en el campo report-to
de Content-Security-Policy
, Cross-Origin-Embedder-Policy
y Cross-Origin-Opener-Policy
recibirán informes 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 denuncias cuando se incumplan estas políticas.
Si bien los informes se envían en ambos casos, los encabezados -Report-Only
no aplican las políticas: nada fallará ni se bloqueará realmente, pero recibirás informes de lo que podría haberse bloqueado o bloqueado.
ReportingObserver
La API de JavaScript de ReportingObserver
puede ayudarte a observar las advertencias del cliente.
ReportingObserver
y el encabezado Reporting-Endpoints
generan informes que se ven iguales, pero habilitan 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 intervenciones de navegador y bajas, pero, a diferencia deReporting-Endpoints
, no captura ningún otro tipo de informes, como incumplimientos de CSP o COOP/COEP. - Debes reaccionar ante estas infracciones en tiempo real.
ReportingObserver
permite adjuntar una devolución de llamada a un evento de incumplimiento. - Si deseas adjuntar información adicional a un informe para ayudar en la depuración, mediante la devolución de llamada personalizada.
Otra diferencia es que ReportingObserver
solo está configurado del cliente: puedes usarlo incluso si no tienes control de los encabezados del servidor y no puedes configurar Reporting-Endpoints
.
Lecturas adicionales
- Guía de migración de la versión 0 de la API de Reporting a la versión 1
- ReportingObserver
- Especificación: API de informes heredados (v0)
- Especificación: nueva API de Reporting (v1)
Hero image de Nine Koepfer / @enka80 en Unsplash, editada. Muchas gracias a Ian Clelland, Eiji Kitamura y Milica Mihajlija por sus opiniones y sugerencias en este artículo.