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 with evidence to review.

Docs Evaluate PyPI

--json --evaluate --bypass-csp --evaluate-file --header-only

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 report observed violations during the selected crawl, before you ship it. A completed scan is not a guarantee that every application flow is covered.

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 and evidence showing which documents led to suggested permissions.

Evaluate

Inject a candidate as Report‑Only and distinguish completed scans, violations and incomplete results.

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 same-origin HTML CSP response headers, not meta CSP. Chromium’s process sandbox stays enabled.

--evaluate

Evaluate a policy string or file: exit 1 for completed scans with violations, or 2 for incomplete/error scans.

--include-sourcemaps

Inspect source-map metadata without automatically granting connect-src permissions.

--upgrade-insecure-requests

Emit upgrade-insecure-requests in the proposed policy.

--browsers-path

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

--json

JSON schema v2: policy evidence, page outcomes, injection confirmation, violations and completeness.

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 missing Chromium binaries into an owned user cache, such as ~/.cache/cspresso/pw-browsers on Linux. Chromium sandboxing is enabled by default.

Override with --browsers-path or PLAYWRIGHT_BROWSERS_PATH.

# From the source checkout, Poetry >=2.2,<3
poetry sync --with dev
poetry run cspresso https://example.com/ --json

Linux deps

From a source checkout, install missing OS libraries with poetry run playwright install-deps chromium. --with-deps applies when installing missing browser binaries.

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

Tip

AppImages use the writable user-cache default. Choose another owned directory with --browsers-path if needed.

Verify releases with the mig5 GPG key (fingerprint 54A91143AE0AB4F7743B01FE888ED1B423A3BC99).