Skip to content

About

The Public Web / Marketing Site for CSP Tool

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

18 Commits

Folders and files

Repository files navigation

CSP Tool

Sponsor Aleph Void

CSP Tool is an open-source browser extension for inspecting, editing, and overriding Content Security Policies in real time. Available for Chrome and Firefox.

Website: https://csptool.net

Features

  • Live CSP Inspection — Instantly view the active Content Security Policy from HTTP headers or meta tags on any page.
  • Visual Editor — Add, edit, toggle, and remove directives using a clean visual interface. No more hand-editing raw header strings.
  • Header Override — Replace server-sent CSP headers entirely using the declarativeNetRequest API for full control to tighten or loosen any policy.
  • Violation Tracking — Monitor CSP violations as they happen. See the blocked resource, violated directive, and timestamps in real time.
  • Multiple Configurations — Save and switch between named CSP configurations with URL patterns so the right policy applies to the right environment.
  • 15 Languages — Full internationalization with support for English, Chinese, Spanish, German, French, Italian, Portuguese, Japanese, Korean, Russian, Polish, Arabic, Filipino, Hebrew, and Hindi.

How It Works

CSP Tool offers two modes for applying policy changes:

Mode 1: Meta Tag Mode (Default)

Injects or modifies a <meta> tag in the page DOM to apply your policy changes.

  • No page reload required
  • Great for loosening policies during development
  • Cannot tighten policies already set by HTTP headers

Mode 2: Header Override Mode (Advanced)

Intercepts and replaces the actual HTTP Content-Security-Policy response header before the browser processes it.

  • Full control — tighten or loosen any policy
  • Can inject CSP on pages with no existing policy
  • Requires a page reload after changes

Typical Workflow

  1. Inspect — Open the extension popup to see the active CSP on the current page.
  2. Edit — Add, modify, or toggle directives using the visual editor.
  3. Apply — Click Apply to push the new policy to the page instantly.
  4. Debug — Check the Errors tab for violations and iterate until clean.

Editor

The editor supports all 28 CSP directives from the specification:

  • Fetch directives — default-src, script-src, style-src, img-src, font-src, connect-src, media-src, object-src, frame-src, child-src, worker-src, manifest-src
  • Document directives — base-uri, sandbox
  • Navigation directives — form-action, frame-ancestors, navigate-to
  • Reporting — report-uri, report-to

Each directive can be toggled on/off without losing its value, or deleted entirely. The Reset button restores the original policy from the page.

Configurations & URL Patterns

Create multiple named configurations and assign URL patterns (glob syntax) to each:

https://example.com/*
https://*.staging.example.com/*
*://localhost:3000/*

CSP Tool automatically activates the matching configuration based on the current page URL.

Violation Tracking

The Errors tab captures securitypolicyviolation events in real time. Each violation shows:

  • Error message
  • Violated directive
  • Blocked URI
  • Timestamp

Capturing Violations with csptool-receiver

csptool-receiver is a self-hosted Express 5 application that receives browser-generated CSP reports, persists them in SQLite, and displays them in a live Vue 3 dashboard. It works alongside CSP Tool or independently with a site's reporting headers.

CSP Violation Receiver dashboard showing a date filter, live connection status, and received script-src reports

The screenshot has its receiver hostname redacted. The dashboard provides a date filter, a copyable reporting endpoint, report details with raw JSON and source locations, and 13 interface languages. Socket.io updates connected dashboards as reports arrive; SQLite retains reports across server restarts.

Start locally

Clone the receiver repository, enter its directory, and use Node 24 or 26 (24 is the default):

nvm use
npm ci
npm start

Open http://localhost:3000. Configure PORT, HOST, and DB_PATH as needed; defaults are 3000, 0.0.0.0, and ./violations.db. After switching Node versions, rerun npm ci to install the matching native SQLite binary.

Connect CSP Tool

  1. Open the target page and the CSP Tool toolbar popup.
  2. Add report-uri http://localhost:3000/violations to the policy. Disable any existing report-to directive for this local legacy setup; supporting browsers may ignore report-uri when report-to is present.
  3. Click Apply, exercise the page, and inspect incoming reports in the receiver dashboard.

Use a reachable HTTPS endpoint for remote or HTTPS deployments. localhost refers to the browser user's machine. The extension's Errors tab displays DOM violation events, including those from matching child frames; these events do not establish successful HTTP report delivery. The receiver shows reports actually received over HTTP.

Configure modern reporting

report-to names a reporting group, not an endpoint URL. Configure the tested site's response headers together:

Content-Security-Policy: default-src 'self'; report-to csp-endpoint
Reporting-Endpoints: csp-endpoint="https://reports.example.com/violations"

A group name alone does not send reports. Reporting API delivery may be batched by the browser. For legacy reporting, use report-uri https://reports.example.com/violations in the CSP instead.

Deploy and query reports

  • Ubuntu 26 installer: sudo ./install.sh reports.example.com configures a dedicated Node runtime, a systemd service, nginx HTTPS, and certificate renewal. It can reuse a matching Let's Encrypt certificate or issue one through Cloudflare DNS-01 with the required credentials. Follow the server installation guide for DNS, certificates, upgrades, and backups. Installed data is stored separately from releases at /var/lib/csptool-receiver/violations.db.
  • Docker: the repository includes a Dockerfile and a Compose example. Mount persistent storage for SQLite and configure HTTPS for remote use.
  • API: POST /violations accepts legacy application/csp-report and modern application/reports+json payloads and returns 204 on success. GET /violations?since=YYYY-MM-DD returns reports newest first, defaulting to today. GET /healthz provides a health check.
  • Access controls: the dashboard and GET API have no built-in authentication. Restrict access at your deployment layer when reports should not be public.
  • Integration check: install both sibling projects under the same Node version, then run npm run test:receiver from csptool. This checks a real legacy browser report, persistence, Socket.io delivery, and the modern payload contract using a temporary database; it does not verify browser scheduling of modern Reporting API delivery.

Installation

Install for free from your browser's extension store:

Tech Stack

Built with Vue 3, TypeScript, and Tailwind CSS.

Related Projects

License

Open source. Contributions and bug reports are welcome on GitHub.

Created by Aleph Void LLC. © 2026 CSP Tool.

About

The Public Web / Marketing Site for CSP Tool

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages