Migrar para a API Reporting v1

Uma nova versão da API Reporting está disponível. É mais privado e mais provável de ser suportado em todos os navegadores.

Maud Nalpas

A API Reporting informa erros que ocorrem em todo o seu site à medida que os visitantes o utilizam. Dá visibilidade das intervenções e falhas do navegador, violações da Política de Segurança de Conteúdo Violações da COOP/COEP, avisos de descontinuação e muito mais.

Uma nova versão da API Reporting está disponível. A nova API é mais enxuta e tem maior probabilidade de ser compatíveis com todos os navegadores.

Resumo

Desenvolvedores de sites

Se você já tiver a funcionalidade de geração de relatórios no seu site: migre para a v1 usando o novo cabeçalho. (Reporting-Endpoints), mas mantenha o cabeçalho legado por algum tempo (Report-To). Consulte Migração: exemplo de código.

Se você estiver adicionando a funcionalidade de relatórios ao site agora há pouco: use apenas o cabeçalho novo. (Reporting-Endpoints).

⚠️ Nos dois casos, defina o cabeçalho Reporting-Endpoints em todas as respostas que possam gerar relatórios.

Desenvolvedores de serviços de relatórios

Se você mantém um serviço de endpoint ou opera por conta própria, espere mais tráfego ou desenvolvedores externos migram para a API Reporting v1 (cabeçalho Reporting-Endpoints).

Continue lendo para conferir mais detalhes e exemplos de código.

Registro de erros de rede

Um novo mecanismo para registro de erros de rede será desenvolvido. Quando ele estiver disponível, mude da API Reporting v0 para esse novo mecanismo.

Demonstração e código

• Site de demonstração: nova API Reporting (v1)
• Código para o site de demonstração

Diferenças entre v0 e v1

O que muda?

• A superfície da API é diferente.

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

• O escopo do relatório é diferente.

• As duas APIs são compatíveis com os mesmos tipos de relatório, com uma exceção: a v1 não oferece suporte aos relatórios de erros de rede. Leia mais nas etapas de migração.
• A v0 não é e não será compatível com todos os navegadores. é mais provável que v1 seja compatível com em vários navegadores no futuro.

O que permanece inalterado

• O formato e a estrutura dos relatórios não foram alterados.
• A solicitação enviada pelo navegador ao endpoint permanece uma solicitação POST de Content-type application/reports+json
• O mapeamento de determinados endpoints para determinados tipos de relatório é suportado nas versões v0 e v1.
• A função do endpoint default não foi alterada.

• A API Reporting v1 não afeta o ReportingObserver. ReportingObserver continua tendo acesso a todos os relatórios observáveis, e o formato é idênticos.

Todas as diferenças entre v0 e v1

Desenvolvedores de endpoint: esperam mais tráfego

Se você configurou seu próprio servidor como um endpoint de relatórios ou se estiver desenvolvendo ou mantendo um Coletor como serviço de relatórios, é esperado mais tráfego para esse endpoint.

Isso ocorre porque os relatórios não são agrupados com a API Reporting v1 do que com a API Reporting v0. Portanto, à medida que os desenvolvedores de aplicativos começarem a migrar para a API Reporting v1, o número de relatórios será permanecem semelhantes, mas o volume de solicitações para o servidor de endpoint aumenta.

Desenvolvedores de aplicativos: migrar para o Reporting-Endpoints (v1)

O que você deve fazer?

Usar a nova API Reporting (v1) traz vários benefícios ✅:

• Os sinais do navegador são positivos, ou seja, que o suporte entre navegadores pode ser esperado para a v1 (ao contrário da v0, que só é suportada no Chrome e Edge).
• A API é mais enxuta.
• As ferramentas estão sendo desenvolvidas em torno da nova API Reporting (v1).

Pensando nisso:

• Caso seu site já use a API Reporting v0 com o cabeçalho Report-To, migre para o API Reporting v1 (consulte as etapas de migração). Se seu site já usa funcionalidade de relatórios para violações da Política de Segurança de Conteúdo, verifique as etapas de migração específicas para a geração de relatórios da CSP.
• Se seu site ainda não usa a API Reporting e você está adicionando a funcionalidade de relatórios: usar a nova API Reporting (v1) (o cabeçalho Reporting-Endpoints). Há uma exceção isto: se você precisar usar o registro de erros de rede, use Report-To (v0). Registro de erros de rede não é compatível com a API Reporting v1. Um novo mecanismo para o registro de erros de rede ser desenvolvida⏤ até que esteja disponível, use a API Reporting v0. Se você precisar do registro de erros de rede junto com outros tipos de relatório, use ambos Report-To (v0) e Reporting-Endpoints (v1). v0 fornece Geração de registros de erros de rede, e a v1 fornece relatórios de todos os outros tipos.

Etapas da migração

Sua meta nessa migração é não perder os relatórios conseguidos com a v0.

1. Etapa 1 (faça agora): use os dois cabeçalhos: Report-To (v0) e Reporting-Endpoints (v1).

   Com isso, você obtém:

   • Relatórios de clientes mais recentes do Chrome e do Edge graças ao Reporting-Endpoints (v1).
   • Relatórios de clientes mais antigos do Chrome e Edge graças ao Report-To (v0).

   As instâncias do navegador compatíveis com Reporting-Endpoints usarão Reporting-Endpoints. instâncias que não vão fazer a substituição por Report-To. O formato de solicitação e de relatório é o mesmo para v0 e v1.

2. Etapa 2 (faça agora): o cabeçalho Reporting-Endpoints precisa estar definido em todas as respostas pode gerar relatórios.

   Na v0, é possível definir endpoints de relatórios somente em algumas respostas e em outros documentos. (páginas) dessa origem usariam esse "ambiente" endpoint do Google Cloud. Na v1, por causa da diferença entre escopo, é necessário definir o cabeçalho Reporting-Endpoints em todas as respostas que podem gerar e detecção de ameaças.

3. Etapa 3 (começar mais tarde): depois que todos ou a maioria dos usuários tiverem atualizado para o Chrome ou o Edge mais recente instalações (96 e mais recentes), remova Report-To (v0) e mantenha apenas Reporting-Endpoints.

   Uma exceção: se você precisa de relatórios do registro de erros de rede, mantenha Report-To até que um novo está em vigor para o registro de erros de rede.

Veja exemplos de código no manual de migração.

Etapas de migração para os relatórios de CSP

A Content-Security-Policy pode ser usada de duas formas relatórios de violação podem ser configurados:

• Apenas com o cabeçalho da CSP usando a diretiva report-uri. Ele oferece um amplo suporte a navegadores, Chrome, Firefox, Safari e Edge. Os relatórios são enviados com o tipo de conteúdo application/csp-report e têm um formato específico do CSP. Esses relatórios são chamados de "Relatórios de nível 2 da CSP" e fazer não dependem da API Reporting.
• Com a API Reporting, isso é feito pelo cabeçalho Report-To (legado) ou pela versão mais recente Reporting-Endpoints (v1). Isso só é compatível com o Chrome e o Edge. As solicitações de relatório têm mesmo formato que outras solicitações da API Reporting e o mesmo tipo de conteúdo application/reports+json.

O uso da primeira abordagem (apenas report-uri) não é mais recomendado e o uso da segunda tem alguns benefícios. Em particular, ele permite que você use uma única maneira de configurar relatórios para todos os tipos, além de definir um endpoint genérico, porque todas as solicitações de relatório geradas pela API Reporting ⏤CSP e outras⏤ têm o mesmo formato application/reports+json.

No entanto, apenas alguns navegadores são compatíveis com report-to. Portanto, é recomendável manter report-uri com a abordagem da API Reporting (Report-To ou melhor, Reporting-Endpoints) para receber denúncias de violação da CSP de vários navegadores. Em um navegador que reconheça report-uri e report-to, report-uri será ignorado se report-to está presente. Em um navegador que reconhece apenas report-uri, apenas report-uri será considerado.

1. Etapa 1 (fazer agora): se você ainda não adicionou, adicione report-to ao lado de report-uri. Navegadores compatíveis apenas com o report-uri (Firefox) usarão report-uri e navegadores que também suporte report-to(Chrome, Edge) usará report-to. Para especificar os endpoints nomeados, você vai usar em report-to, use os cabeçalhos Report-To e Reporting-Endpoints. Isso garante que você receba de clientes Chrome e Edge de clientes mais antigos e novos.

2. Etapa 3 (começar mais tarde): depois que todos ou a maioria dos usuários tiverem atualizado para o Chrome ou o Edge mais recente instalações (96 e mais recentes), remova Report-To (v0) e mantenha apenas Reporting-Endpoints. Manter report-uri, então você ainda vai receber relatórios sobre os navegadores compatíveis apenas com esse recurso.

Veja exemplos de código para essas etapas em Migração de relatórios da CSP.

Migração: exemplo de código

Visão geral

Se você estiver usando a API Reporting (v0) legada para receber relatórios de violação de uma COOP (cabeçalho Cross-Origin-Opener-Policy), um COEP (Cross-Origin-Embedder-Policy) ou uma política de documentos (cabeçalho Document-Policy): não é necessário mudar esses cabeçalhos de política durante a migração. à API Reporting v1. Você precisa migrar do cabeçalho Report-To legado para o novo. Cabeçalho Reporting-Endpoints.

Se você estiver usando a API Reporting (v0) legada para receber relatórios de violação de uma CSP (cabeçalho Content-Security-Policy), pode ser necessário ajustar seu Content-Security-Policy como parte migração para a nova API Reporting (v1).

Migração básica

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

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

Com a v1, ainda é possível enviar tipos de relatórios específicos para endpoints específicos. Mas você pode ter apenas um URL por endpoint.

Observar todas as páginas

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

Migração de relatórios da CSP

Content-Security-Policy: ...; report-uri https://reports.example/main

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

Leitura adicional

• Monitorar seu aplicativo da Web com a API Reporting (postagem principal sobre a API Reporting)
• Especificação: API Reporting legada (v0)
• Especificação: nova API Reporting (v1)

Imagem principal de Nine Koepfer / @enka80 no Unsplash, editada. Muito obrigado ao Ian Clelland, Eiji Kitamura e Milica Mihajlija por suas avaliações e sugestões sobre o assunto artigo.