Automatically generate a CSP for your site.

cspresso crawls up to N same‑origin pages with headless Chromium (Playwright), watches the assets that load, and emits a draft Content-Security-Policy header.

Docs Evaluate PyPI

--json --evaluate --bypass-csp --include-sourcemaps

pipx install cspresso
cspresso https://mig5.net --max-pages 10

# visited: https://mig5.net/
Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.jsdelivr.net; ...;

How it works

cspresso lets the browser do the hard part: execute the page, watch what it loads, and distill origins into directives.

It uses Playwright (a tool designed to run a browser in 'headless' mode, originally to help automate performing frontend testing of websites) to visit the website in the background and learn what directives of a Content-Security Policy would be needed in order to set such a header and still have the website function properly.

It can also evaluate a provided CSP against a site and see if normal use of the site would trigger violations of the policy, before you ship it.

Crawl

Visit up to --max-pages same-origin pages and let the app’s JS run.

Observe

Track scripts, styles, images, fonts, frames, and “connect-like” requests.

Draft a CSP

Emit a baseline policy plus observed origins per directive.

Evaluate

Inject a candidate as Report‑Only and capture violations with an exit code for CI.

Inline script/style is tricky: nonces must be generated per response, and hashes must match bytes exactly. cspresso reports what it sees, but you should review and tighten before enforcing.

Popular flags

A few options that tend to matter in real deployments.

--bypass-csp

Strip existing CSP response headers so they don’t block discovery or evaluation.

--evaluate

Inject a candidate policy as Report‑Only and exit 1 if any violations are detected.

--include-sourcemaps

Heuristically discover sourcemap origins and add them to connect-src.

--upgrade-insecure-requests

Emit upgrade-insecure-requests in the proposed policy.

--browsers-path

Control where Playwright installs Chromium (handy for AppImage/CI caches).

--json

Machine-readable output: CSP, visited URLs, notes, and evaluation violations.

Install

pipx, pip, Poetry, or a standalone AppImage from Releases.

Releases

# Recommended
pipx install cspresso

# Or plain pip (use a venv)
pip install cspresso

Playwright browsers

cspresso can auto-install Chromium for Playwright if it isn’t present. By default it installs into ./.pw-browsers for deterministic builds and easy CI caching.

Override with --browsers-path or PLAYWRIGHT_BROWSERS_PATH.

poetry add cspresso

Linux deps

If Chromium won’t start due to missing libraries, try --with-deps (may require elevated privileges).

chmod +x cspresso.AppImage
./cspresso.AppImage https://example.com \
  --browsers-path "$HOME/.cache/cspresso/pw-browsers"

Tip

AppImages mount read-only - use --browsers-path to install browsers into a writable cache directory.

Verify releases with the mig5 GPG key (fingerprint 00AE817C24A10C2540461A9C1D7CDE0234DB458D).