This package provides a middleware for Express.js that automatically configures the Reporting API on existing policy headers and an endpoint to help you collect your own reports using the Reporting API.
Automatically sets up reporting for the following headers and features supporting the Reporting API
Content-Security-Policy
(CSP)Content-Security-Policy-Report-Only
Permissions-Policy
Permissions-Policy-Report-Only
Cross-Origin-Opener-Policy
(COOP)Cross-Origin-Opener-Policy-Report-Only
Cross-Origin-Embedder-Policy
(COEP)Cross-Origin-Embedder-Policy-Report-Only
NEL
(Network Error Logging)- Deprecation Reports
- Intervention Reports
- Crash Reports
Supports "CSP Level 2 Reports" in browsers browsers not supporting the Reporting API.
Retrofitting a policy on a large website is hard to get right first. The solution is to use -Report-Only
policies that will not enforce them and break your website. These headers and their enforcing equivalents supports reporting, which makes all policy violations gets sent to you so you can adjust your policies to not break functionality.
$ npm install reporting-api
import { reportingEndpoint } from 'reporting-api';
import express from 'express';
const app = express();
// The reporting endpoint.
// Use `use` to support CORS preflight request if you are receiving reports from another origin
app.use('/reporting-endpoint', reportingEndpoint({
allowedOrigins: '*', // Allow reports from all origins
onReport(report) {
// Collect the reports and do what you want with them
console.log('Report received', {
isEnforced: report.body.type === 'enforce',
type: report.type,
body: report.body,
});
}
}));
// Set the security headers
app.get('/*', (req, res, next) => {
// Set a CSP that disallows inline scripts.
res.setHeader('Content-Security-Policy', "script-src 'self'");
// COOP policy that disallows link in new tab
res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
// COEP policy that disallows external resources that does not use CORS or CORP (Cross-Origin-Resource-Policy)
res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
// Setup headers alternative 1
setupReportingHeaders('/reporting-endpoint')(req, res);
return next();
});
// Setup headers alternative 2
app.get('/*', setupReportingHeaders('/reporting-endpoint', {
includeDefaultReporters: true,
enableNetworkErrorLogging: true,
version: '1',
}));
//
app.get('/test', (req, res) => {
res.writeHead(200, {
'Content-Type': 'text/html; charset=utf8'
});
// The script will not run and instead generate a csp-violation report
// Clicking the link will trigger a COOP report
// Loading the image will trigger a COEP report
res.end(`Hello World!
<script>alert(1)</script>
<a href="https://google.com" target="_blank">Trigger COOP</>
<img src="https://lh3.googleusercontent.com/wAPeTvxh_EwOisF8kMR2L2eOrIOzjfA5AjE28W5asyfGeH85glwrO6zyqL71dCC26R63chADTO7DLOjnqRoXXOAB8t2f4C3QnU6o0BA">
`);
});
app.listen(8080);
Note
The policy headers must be set before the reportingEndpointHeader middleware so the middleware is able to append the reporter to the policy headers.
$ curl -I localhost:8080/test
Reporting-Endpoints: default=/test-endpoint
Content-Security-Policy: default-src 'self'; report-to default; report-uri /reporting-endpoint?src=report-uri
Cross-Origin-Opener-Policy: same-origin; report-to="default"
Cross-Origin-Embedder-Policy: require-corp; report-to="default"
Hello World!
<script>alert(1)</script>
<a href="https://google.com" target="_blank">Trigger COOP</>
<img src="https://lh3.googleusercontent.com/wAPeTvxh_EwOisF8kMR2L2eOrIOzjfA5AjE28W5asyfGeH85glwrO6zyqL71dCC26R63chADTO7DLOjnqRoXXOAB8t2f4C3QnU6o0BA">
Tip
The Reporting API is also accessible in some browsers using the ReportingObserver
if (typeof ReportingObserver !== 'undefined') {
const myObserver = new ReportingObserver(reportList => {
reportList.forEach(report => {
console.log(report.body);
});
});
myObserver.observe();
}
Note
Set the allowedOrigins
option on your reporting endpoint to allow cross origin reports.
- Permissions-Policy reporting
- Reporting API v0 and Reporting API v1 differences
- Migrating from v0 to v1
- Reporting API v0 (Report-To)
- Reporting API v1 (Reporting-Endpoints)
Permissions-Policy
reports to thedefault
reporting group ifreport-to
is not set.report-to
group MUST be in double quotes (eg.report-to="group"
) in COOP AND COEP headers to be used.Document-Policy
andDocument-Policy-Report-Only
is doesn't look that supported or well documented, is it supersceded by Permissions-Policy?- Safari sends reports in the format
body: { ... }
instead of an array of reports and it doesn't include anage