无需登录 数据私有 本地保存

Reporting API 错误仪表板 - CSP/拦截报告收集

开发工具 监控 CSP Reporting API 监控 错误报告
65
0
0
0

快速开始

本教程将引导你完成从打开工具到成功接收第一份 CSP 违规报告的全部步骤，并介绍如何利用仪表板的各项功能进行 数据分析和配置验证。

第一步：获取端点地址

打开 Reporting API 错误仪表板页面后，工具会为你生成一个专属的报告接收端点地址。该地址格式通常为 https://zh.ud5.com/api/report/xxxx。请复制此地址，后续步骤中需要将其配置到你的网站 CSP 头中。

第二步：配置 CSP 报告端点

根据你的技术栈，选择以下任一方式完成配置：

方式一：通过 HTTP 响应头配置

Content-Security-Policy: default-src 'self'; report-uri https://zh.ud5.com/api/report/xxxx; report-to csp-endpoint

在服务器返回的 HTTP 响应头中添加上述 CSP 指令。report-uri 用于 v1 版本，report-to 配合 Reporting-Endpoints 头用于 v2 版本。

方式二：通过 Nginx 配置

add_header Content-Security-Policy "default-src 'self'; report-uri https://zh.ud5.com/api/report/xxxx" always;

在 Nginx 的 server 或 location 块中添加上述指令，always 参数确保所有响应都包含该头。

方式三：通过 Node.js Express 配置

app.use((req, res, next) => {
  res.setHeader('Content-Security-Policy',
    "default-src 'self'; report-uri https://zh.ud5.com/api/report/xxxx");
  next();
});

在 Express 应用中通过中间件统一设置 CSP 头，适用于所有路由。

方式四：CSP Report-Only 模式

Content-Security-Policy-Report-Only: default-src 'self'; report-uri https://zh.ud5.com/api/report/xxxx

使用 Content-Security-Policy-Report-Only 替代 Content-Security-Policy， 浏览器只会发送违规报告而不会实际阻止资源加载。这是在生产环境部署 CSP 前进行安全测试的推荐做法。

第三步：触发违规并查看报告

完成配置后，访问你的网站页面，触发一个 CSP 违规行为（例如加载一个不在白名单中的外部脚本）。几秒钟后， 刷新仪表板页面，你应该能在报告列表中看到一条新的 CSP 违规报告。报告卡片会展示 document-uri、 violated-directive、blocked-uri 等关键字段。

第四步：分析报告数据

利用仪表板提供的功能进行深入分析：

  • 查看违规类型分布图表，识别高频违规模式。
  • 使用搜索功能按关键词查找特定违规，例如搜索某个第三方脚本域名。
  • 通过筛选器按时间或类型过滤报告，聚焦当前需要解决的问题。
  • 导出 CSV 文件，与团队成员共享分析结果。

最佳实践

  • 先使用 Report-Only 模式收集数据，确认无误后再切换为强制执行模式。
  • 定期导出报告数据，建立违规趋势分析基线。
  • 关注高频违规类型，优先修复影响范围最大的策略问题。
  • 保护你的报告端点，限制 Content-Type 为 application/csp-report 或 application/reports+json。
🔧 相关工具