-
-
-
-
-
-
-
-
- On this page
-
-
-
- Prefer canonical docs? See the README.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Docs
- Usage
-
- cspresso crawls up to --max-pages same-origin pages in Chromium, observes what loads, and emits a draft CSP.
-
Install
-
-
-
-
-
-
-
- # Recommended
-pipx install cspresso
-
-# Or plain pip (use a venv)
-pip install cspresso
-
-# An AppImage is also available on the
-# git repo Releases page.
-
-
-
-
-
- Python + Playwright
-
- You need Python 3.10+ and Playwright’s Chromium. cspresso can auto-install Chromium if missing.
-
- -
- Verify Releases artifacts with the mig5 key:
- https://mig5.net/static/mig5.asc
- (fingerprint
- 00AE817C24A10C2540461A9C1D7CDE0234DB458D).
- Run
-
-
-
- cspresso https://example.com --max-pages 10
- The crawl stays on the same origin (it follows internal links) and will wait for
- networkidle plus a small “settle”
- delay to catch late fetches.
- Output
-- Default output prints visited URLs as comments and then the proposed header line. - Use --json for machine-readable output. -
-
-
-
- cspresso https://example.com --jsonInline scripts & styles
-
-
- Why this is hard
-
- If the page uses nonces, you must generate a new nonce per HTML response and inject it into both the CSP header and the HTML tags.
- Hashes only work when inline content is stable byte-for-byte. For
Not to worry, cspresso will detect these and generate the hashes - in its response, offering them as
- style="..." and on* attributes,
- browsers require 'unsafe-hashes' for hashes to apply.Not to worry, cspresso will detect these and generate the hashes - in its response, offering them as
style-src-attr options or with unsafe-hashes for older browsers.
- Evaluate (Report-Only)
-
- Provide a CSP string to --evaluate and cspresso will inject it as
- Content-Security-Policy-Report-Only on HTML responses during the crawl. If any violations are detected, it exits with code 1.
-
This is a great way of testing a cspresso-brewed CSP before actually adding it to your site.
- -
-
-
-
- cspresso https://example.com \
- --bypass-csp \
- --evaluate "default-src 'self'; script-src 'self' https://cdn.jsdelivr.net;" \
- --json
- Recommendation: use
- --bypass-csp with --evaluate so existing CSP enforcement doesn’t change the page’s behaviour during testing.
- Flags
-A condensed reference of the most-used options:
- -
-
-
-
-
-
-
-
-
Crawling
- --max-pages --timeout-ms --settle-ms --headed
-
-
Policy shaping
- --include-sourcemaps --upgrade-insecure-requests --allow-blob --unsafe-eval
-
-
Playwright
- --browsers-path --no-install --with-deps
-
-
Evaluation
- --bypass-csp --evaluate --ignore-non-html --json
-