Skip to main content

Roll out a Content Security Policy in Report-Only mode

Ship a new Content Security Policy as Content-Security-Policy-Report-Only first, with report-uri http://localhost:8000/csp. The browser blocks nothing and reports every resource the policy would block to Buggregator. Fix the policy or the page until a full click-through brings no new reports, then rename the header to Content-Security-Policy to enforce it.

Steps

1. Start Buggregator

bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  ghcr.io/buggregator/server:latest

2. Send the draft policy as Report-Only

Write the policy you want, and add report-uri. shop is the project; leave out /shop for the default project.

http
Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self'; img-src 'self' data:; report-uri http://localhost:8000/csp/shop

In nginx, for example:

nginx
add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self'; img-src 'self' data:; report-uri http://localhost:8000/csp/shop";

3. Click through the site

Open the pages people use: sign-in, checkout, the pages with embeds and widgets. Then open http://localhost:8000. The feed gets one card per report: the page, then one line per violation, for example «script-src-elem blocked cdn.example.com/x.js». Report-only violations get a badge. The event page shows the directive, the blocked resource, the file with line and column, and the full policy. CSP reports in the menu lists only these events.

4. Fix each report

For each line, decide: the resource is yours and needed, so add its source to the directive (script-src 'self' https://cdn.example.com), or it should not load, so remove it from the page.

5. Clear and check again

Delete the old reports, update the policy and click through again. Repeat until no new reports come.

bash
curl -X DELETE http://localhost:8000/api/events \
  -H 'Content-Type: application/json' -d '{"type": "csp"}'

6. Enforce it

Rename the header to Content-Security-Policy and keep report-uri. The browser now blocks what the policy forbids, and you still see each block in Buggregator, now without the report-only badge on the feed card.

http
Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.example.com; img-src 'self' data:; report-uri http://localhost:8000/csp/shop

Why it works

With the Report-Only header, the browser checks every resource against the policy but loads it anyway, and POSTs a JSON report for each one that fails. Buggregator accepts these reports at /csp, answers the browser's CORS check and stores each request as one event. You see the full list of what the policy would break before any user meets it. report-uri also works over plain http. In Docker, publish port 8000 and keep http://localhost:8000/csp/shop: the reports come from your browser, and a browser on your machine cannot resolve a Compose service name.

Checked on with Buggregator v2.13.0

Setup in 60 seconds

No registration. No account. Start it and point your app at it.

1

Start Buggregator

One file, installed with one command. The web UI opens on port 8000. Prefer containers? Use the Docker tab.

$ curl -fsSL https://raw.githubusercontent.com/buggregator/server/master/scripts/install.sh | sh
$ HTTP_ADDR=127.0.0.1:8000 \
  SMTP_ADDR=127.0.0.1:1025 \
  VAR_DUMPER_ADDR=127.0.0.1:9912 \
  MONOLOG_ADDR=127.0.0.1:9913 \
  PROXY_ADDR=127.0.0.1:8080 \
  ~/.local/bin/buggregator

The script picks the file for your CPU: Intel/AMD or ARM.

One file for Linux, macOS and Windows, about 40 MB. Nothing else to install.

This run line keeps it on this computer. Without the *_ADDR settings it listens on all network interfaces

Rather not run a script? Download the file yourself

Runs on Windows, macOS and Linux, on Intel/AMD and ARM.

Prefer not to do it yourself? Your AI agent can set Buggregator up for you