mig5/cspresso.cafe
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Hugo site now

Browse source
This commit is contained in:
Miguel Jacq 2026-01-06 09:51:05 +11:00
parent aceb297d4f
commit 995092af42
Signed by: mig5
GPG key ID: 59B3F0C24135C6A9
34 changed files with 1309 additions and 85 deletions
Download patch file Download diff file Expand all files Collapse all files

308
src/content/_index.html Normal file
View file

@ -0,0 +1,308 @@
---
title: "cspresso - Brew a Content Security Policy"
description: "cspresso crawls a site with headless Chromium (Playwright) and emits a draft Content-Security-Policy based on what loads."
---
<main>
<header class="hero py-5">
<div class="container py-4">
<div class="row align-items-center g-4">
<div class="col-lg-6">
<div class="kicker mb-3"><i class="bi bi-cup-hot"></i> Brew a Content Security Policy</div>
<h1 class="display-5 fw-800 lh-1 mb-3" style="letter-spacing:-0.03em;">Turn real page loads into a CSP you can ship.</h1>
<p class="lead mb-4">
cspresso crawls up to <em>N</em> same‑origin pages with headless Chromium (Playwright), watches the assets that load,
and emits a <strong>draft</strong> <code>Content-Security-Policy</code> header.
</p>
<div class="d-flex flex-wrap gap-2 mb-4">
<a class="btn btn-dark btn-lg" href="#quickstart"><i class="bi bi-rocket-takeoff"></i> Quickstart</a>
<a class="btn btn-outline-dark btn-lg" href="docs.html"><i class="bi bi-journal-text"></i> Docs</a>
<a class="btn btn-outline-secondary btn-lg" href="evaluate.html"><i class="bi bi-shield-check"></i> Evaluate</a>
<a class="btn btn-outline-secondary btn-lg" href="https://pypi.org/project/cspresso/" target="_blank" rel="noreferrer"><i class="bi bi-box-seam"></i> PyPI</a>
</div>
<div class="d-flex flex-wrap gap-2">
<span class="chip">--json</span>
<span class="chip">--evaluate</span>
<span class="chip">--bypass-csp</span>
<span class="chip">--include-sourcemaps</span>
</div>
</div>
<div class="col-lg-6">
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#heroCode"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="heroCode">pipx install cspresso
cspresso https://example.com --max-pages 10
# visited: https://example.com/
Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.jsdelivr.net; ...;</code></pre>
</div>
<div class="mt-3 small text-secondary">
Remember: it’s only a starting point: crawls may not hit every flow, and inline hashing/nonces require care.
</div>
</div>
</div>
</div>
</header>
<section id="quickstart" class="py-5 border-top">
<div class="container">
<div class="row g-4 align-items-start">
<div class="col-lg-4">
<h2 class="section-title fw-bold mb-2">Quickstart</h2>
</div>
<div class="col-lg-12">
<div class="row g-3">
<div class="col-lg-6">
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#qs1"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0">
<code id="qs1">
cspresso https://mig5.net \
--ignore-non-html \
--max-pages 10
</code>
</pre>
</div>
</div>
<div class="col-lg-6">
<div class="callout p-4 h-100">
<div class="fw-semibold mb-2">What you’ll get</div>
<div class="text-muted">
A header line you can paste into your vhost, or parseable info with <code>--json</code>
</div>
<hr>
<div class="small text-secondary">
Tip: if an existing CSP might block loads during analysis, add <code>--bypass-csp</code>.
</div>
</div>
</div>
<div class="col-12">
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#qs2"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="qs2"># Evaluate a candidate CSP (Report-Only) and fail CI on violations
cspresso https://mig5.net \
--bypass-csp \
--evaluate "default-src 'self'; img-src 'none';" \
--json
{
[...]
"violations": [
{
"console": true,
"disposition": "report",
"documentURI": "https://mig5.net/",
"text": "Loading the image 'https://mig5.net/logo.svg' violates the following Content Security Policy directive: \"img-src 'none'\". The policy is report-only, so the violation has been logged but no further action has been taken.",
"type": "info"
},
{
"console": true,
"disposition": "report",
"documentURI": "https://mig5.net/static/mig5.asc",
"text": "Applying inline style violates the following Content Security Policy directive 'default-src 'self''. Either the 'unsafe-inline' keyword, a hash ('sha256-4Su6mBWzEIFnH4pAGMOuaeBrstwJN4Z3pq/s1Kn4/KQ='), or a nonce ('nonce-...') is required to enable inline execution. Note that hashes do not apply to event handlers, style attributes and javascript: navigations unless the 'unsafe-hashes' keyword is present. Note also that 'style-src' was not explicitly set, so 'default-src' is used as a fallback. The policy is report-only, so the violation has been logged but no further action has been taken.",
"type": "info"
}
]
}
# exit code: 1 if violations detected</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</section>
<section class="py-5" id="how">
<div class="container">
<div class="row g-4 align-items-start">
<div class="col-lg-5">
<h2 class="section-title display-6 fw-bold mb-2">How it works</h2>
<p class="text-muted mb-0">
cspresso lets the browser do the hard part: execute the page, watch what it loads, and distill origins into directives.
</p>
</div>
<div class="col-lg-7">
<div class="row g-3">
<div class="col-md-6">
<div class="card feature-card h-100"><div class="card-body p-4">
<div class="icon-pill mb-3"><i class="bi bi-globe2"></i></div>
<div class="fw-semibold mb-1">Crawl</div>
<div class="text-muted">Visit up to <code>--max-pages</code> same-origin pages and let the app’s JS run.</div>
</div></div>
</div>
<div class="col-md-6">
<div class="card feature-card h-100"><div class="card-body p-4">
<div class="icon-pill mb-3"><i class="bi bi-activity"></i></div>
<div class="fw-semibold mb-1">Observe</div>
<div class="text-muted">Track scripts, styles, images, fonts, frames, and “connect-like” requests.</div>
</div></div>
</div>
<div class="col-md-6">
<div class="card feature-card h-100"><div class="card-body p-4">
<div class="icon-pill mb-3"><i class="bi bi-shield-lock"></i></div>
<div class="fw-semibold mb-1">Draft a CSP</div>
<div class="text-muted">Emit a baseline policy plus observed origins per directive.</div>
</div></div>
</div>
<div class="col-md-6">
<div class="card feature-card h-100"><div class="card-body p-4">
<div class="icon-pill mb-3"><i class="bi bi-check2-square"></i></div>
<div class="fw-semibold mb-1">Evaluate</div>
<div class="text-muted">Inject a candidate as Report‑Only and capture violations with an exit code for CI.</div>
</div></div>
</div>
</div>
<div class="mt-3 small text-secondary">
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.
</div>
</div>
</div>
</div>
</section>
<section class="py-5 bg-light" id="flags">
<div class="container">
<div class="row g-3 align-items-end mb-3">
<div class="col-lg-8">
<h2 class="section-title display-6 fw-bold mb-2">Popular flags</h2>
<p class="text-muted mb-0">A few options that tend to matter in real deployments.</p>
</div>
</div>
<div class="row g-3">
<div class="col-md-6 col-lg-4"><div class="card feature-card h-100"><div class="card-body p-4">
<div class="fw-semibold mb-2"><span class="chip">--bypass-csp</span></div>
<div class="text-muted">Strip existing CSP response headers so they don’t block discovery or evaluation.</div>
</div></div></div>
<div class="col-md-6 col-lg-4"><div class="card feature-card h-100"><div class="card-body p-4">
<div class="fw-semibold mb-2"><span class="chip">--evaluate</span></div>
<div class="text-muted">Inject a candidate policy as Report‑Only and exit 1 if any violations are detected.</div>
</div></div></div>
<div class="col-md-6 col-lg-4"><div class="card feature-card h-100"><div class="card-body p-4">
<div class="fw-semibold mb-2"><span class="chip">--include-sourcemaps</span></div>
<div class="text-muted">Heuristically discover sourcemap origins and add them to <code>connect-src</code>.</div>
</div></div></div>
<div class="col-md-6 col-lg-4"><div class="card feature-card h-100"><div class="card-body p-4">
<div class="fw-semibold mb-2"><span class="chip">--upgrade-insecure-requests</span></div>
<div class="text-muted">Emit <code>upgrade-insecure-requests</code> in the proposed policy.</div>
</div></div></div>
<div class="col-md-6 col-lg-4"><div class="card feature-card h-100"><div class="card-body p-4">
<div class="fw-semibold mb-2"><span class="chip">--browsers-path</span></div>
<div class="text-muted">Control where Playwright installs Chromium (handy for AppImage/CI caches).</div>
</div></div></div>
<div class="col-md-6 col-lg-4"><div class="card feature-card h-100"><div class="card-body p-4">
<div class="fw-semibold mb-2"><span class="chip">--json</span></div>
<div class="text-muted">Machine-readable output: CSP, visited URLs, notes, and evaluation violations.</div>
</div></div></div>
</div>
</div>
</section>
<section class="py-5" id="install">
<div class="container">
<div class="row g-3 align-items-end mb-3">
<div class="col-lg-8">
<h2 class="section-title display-6 fw-bold mb-2">Install</h2>
<p class="text-muted mb-0">pipx, pip, Poetry, or a standalone AppImage from Releases.</p>
</div>
<div class="col-lg-4 text-lg-end">
<a class="btn btn-outline-dark" href="https://git.mig5.net/mig5/cspresso/releases" target="_blank" rel="noreferrer"><i class="bi bi-download"></i> Releases</a>
</div>
</div>
<ul class="nav nav-pills gap-2" id="installTabs" role="tablist">
<li class="nav-item" role="presentation"><button class="nav-link active" id="inst1-tab" data-bs-toggle="pill" data-bs-target="#inst1" type="button" role="tab">pipx / pip</button></li>
<li class="nav-item" role="presentation"><button class="nav-link" id="inst2-tab" data-bs-toggle="pill" data-bs-target="#inst2" type="button" role="tab">Poetry</button></li>
<li class="nav-item" role="presentation"><button class="nav-link" id="inst3-tab" data-bs-toggle="pill" data-bs-target="#inst3" type="button" role="tab">AppImage</button></li>
</ul>
<div class="tab-content mt-3">
<div class="tab-pane fade show active" id="inst1" role="tabpanel" aria-labelledby="inst1-tab">
<div class="row g-3">
<div class="col-lg-6">
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#inst1code"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="inst1code"># Recommended
pipx install cspresso
# Or plain pip (use a venv)
pip install cspresso</code></pre>
</div>
</div>
<div class="col-lg-6">
<div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Playwright browsers</div>
<div class="text-muted">
cspresso can auto-install Chromium for Playwright if it isn’t present. By default it installs into <code>./.pw-browsers</code>
for deterministic builds and easy CI caching.
</div>
<hr>
<div class="small text-secondary">
Override with <code>--browsers-path</code> or <code>PLAYWRIGHT_BROWSERS_PATH</code>.
</div>
</div>
</div>
</div>
</div>
<div class="tab-pane fade" id="inst2" role="tabpanel" aria-labelledby="inst2-tab">
<div class="row g-3">
<div class="col-lg-6">
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#inst2code"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="inst2code">poetry add cspresso</code></pre>
</div>
</div>
<div class="col-lg-6">
<div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Linux deps</div>
<div class="text-muted">
If Chromium won’t start due to missing libraries, try <code>--with-deps</code> (may require elevated privileges).
</div>
</div>
</div>
</div>
</div>
<div class="tab-pane fade" id="inst3" role="tabpanel" aria-labelledby="inst3-tab">
<div class="row g-3">
<div class="col-lg-6">
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#inst3code"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="inst3code">chmod +x cspresso.AppImage
./cspresso.AppImage https://example.com \
--browsers-path "$HOME/.cache/cspresso/pw-browsers"</code></pre>
</div>
</div>
<div class="col-lg-6">
<div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Tip</div>
<div class="text-muted">
AppImages mount read-only - use <code>--browsers-path</code> to install browsers into a writable cache directory.
</div>
<hr>
<div class="small text-secondary">
Verify releases with the mig5 GPG key (fingerprint <code>00AE817C24A10C2540461A9C1D7CDE0234DB458D</code>).
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</section>
</main>

155
src/content/docs.html Normal file
View file

@ -0,0 +1,155 @@
---
title: "cspresso Docs"
description: "Docs for cspresso: crawl a site with headless Chromium and generate a draft Content-Security-Policy; evaluate candidates in Report-Only mode."
---
<main class="py-5">
<div class="container">
<div class="row g-4">
<div class="col-lg-3">
<div class="sticky-lg-top" style="top: 90px;">
<div class="fw-semibold mb-2">On this page</div>
<div class="list-group small">
<a class="list-group-item list-group-item-action" href="#install">Install</a>
<a class="list-group-item list-group-item-action" href="#run">Run</a>
<a class="list-group-item list-group-item-action" href="#output">Output</a>
<a class="list-group-item list-group-item-action" href="#inline">Inline scripts &amp; styles</a>
<a class="list-group-item list-group-item-action" href="#evaluate">Evaluate (Report-Only)</a>
<a class="list-group-item list-group-item-action" href="#flags">Flags</a>
</div>
<div class="mt-3 small text-secondary">
Prefer canonical docs? See the <a class="link-secondary" href="https://git.mig5.net/mig5/cspresso#readme" target="_blank" rel="noreferrer">README</a>.
</div>
</div>
</div>
<div class="col-lg-9">
<header class="mb-4">
<div class="kicker mb-2"><i class="bi bi-journal-text"></i> Docs</div>
<h1 class="display-6 fw-800 mb-2">Usage</h1>
<p class="text-secondary mb-0">
cspresso crawls up to <code>--max-pages</code> same-origin pages in Chromium, observes what loads, and emits a draft CSP.
</p>
</header>
<section id="install" class="mb-5">
<h2 class="section-title fw-bold">Install</h2>
<div class="row g-3">
<div class="col-lg-7">
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#docinst"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="docinst"># Recommended
pipx install cspresso
# Or plain pip (use a venv)
pip install cspresso
# An AppImage is also available on the
# git repo Releases page.
</code></pre>
</div>
</div>
<div class="col-lg-5">
<div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Python + Playwright</div>
<div class="text-muted">
You need Python 3.10+ and Playwright’s Chromium. cspresso can auto-install Chromium if missing.
</div>
<hr>
<div class="small text-secondary">
Verify Releases artifacts with the mig5 key:
<a class="link-secondary" href="https://mig5.net/static/mig5.asc" target="_blank" rel="noreferrer">https://mig5.net/static/mig5.asc</a>
(fingerprint <code>00AE817C24A10C2540461A9C1D7CDE0234DB458D</code>).
</div>
</div>
</div>
</div>
</section>
<section id="run" class="mb-5">
<h2 class="section-title fw-bold">Run</h2>
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#docrun"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="docrun">cspresso https://example.com --max-pages 10</code></pre>
</div>
<div class="mt-3 text-secondary">
The crawl stays on the same origin (it follows internal links) and will wait for <code>networkidle</code> plus a small “settle”
delay to catch late fetches.
</div>
</section>
<section id="output" class="mb-5">
<h2 class="section-title fw-bold">Output</h2>
<p class="text-secondary">
Default output prints visited URLs as comments and then the proposed header line.
Use <span class="chip">--json</span> for machine-readable output.
</p>
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#docjson"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="docjson">cspresso https://example.com --json</code></pre>
</div>
</section>
<section id="inline" class="mb-5">
<h2 class="section-title fw-bold">Inline scripts &amp; styles</h2>
<div class="callout p-4">
<div class="fw-semibold mb-2">Why this is hard</div>
<div class="text-muted">
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 <code>style="..."</code> and <code>on*</code> attributes,
browsers require <code>'unsafe-hashes'</code> for hashes to apply.<br/>Not to worry, cspresso will detect these and generate the hashes
in its response, offering them as <code>style-src-attr</code> options or with <code>unsafe-hashes</code> for older browsers.
</div>
</div>
</section>
<section id="evaluate" class="mb-5">
<h2 class="section-title fw-bold">Evaluate (Report-Only)</h2>
<p class="text-secondary">
Provide a CSP string to <span class="chip">--evaluate</span> and cspresso will inject it as
<code>Content-Security-Policy-Report-Only</code> on HTML responses during the crawl. If any violations are detected, it exits with code <code>1</code>.
</p>
<p class="text-secondary">This is a great way of testing a cspresso-brewed CSP before actually adding it to your site.</p>
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#doceval"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="doceval">cspresso https://example.com \
--bypass-csp \
--evaluate "default-src 'self'; script-src 'self' https://cdn.jsdelivr.net;" \
--json</code></pre>
</div>
<div class="mt-3 small text-secondary">
Recommendation: use <code>--bypass-csp</code> with <code>--evaluate</code> so existing CSP enforcement doesn’t change the page’s behaviour during testing.
</div>
</section>
<section id="flags">
<h2 class="section-title fw-bold">Flags</h2>
<p class="text-secondary">A condensed reference of the most-used options:</p>
<div class="row g-3">
<div class="col-md-6"><div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Crawling</div>
<div class="text-muted"><span class="chip">--max-pages</span> <span class="chip">--timeout-ms</span> <span class="chip">--settle-ms</span> <span class="chip">--headed</span></div>
</div></div>
<div class="col-md-6"><div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Policy shaping</div>
<div class="text-muted"><span class="chip">--include-sourcemaps</span> <span class="chip">--upgrade-insecure-requests</span> <span class="chip">--allow-blob</span> <span class="chip">--unsafe-eval</span></div>
</div></div>
<div class="col-md-6"><div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Playwright</div>
<div class="text-muted"><span class="chip">--browsers-path</span> <span class="chip">--no-install</span> <span class="chip">--with-deps</span></div>
</div></div>
<div class="col-md-6"><div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Evaluation</div>
<div class="text-muted"><span class="chip">--bypass-csp</span> <span class="chip">--evaluate</span> <span class="chip">--ignore-non-html</span> <span class="chip">--json</span></div>
</div></div>
</div>
</section>
</div>
</div>
</div>
</main>

100
src/content/evaluate.html Normal file
View file

@ -0,0 +1,100 @@
---
title: "cspresso Evaluate"
description: "Evaluate a candidate Content-Security-Policy by injecting it as CSP Report-Only and failing if violations are detected."
---
<main class="py-5">
<div class="container">
<header class="mb-4">
<div class="kicker mb-2"><i class="bi bi-shield-check"></i> Evaluate</div>
<h1 class="display-6 fw-800 mb-2">Test a CSP before you enforce it</h1>
<p class="text-secondary mb-0">
Use <span class="chip">--evaluate</span> to inject a candidate policy as <code>Content-Security-Policy-Report-Only</code>,
collect violations, and fail the run if anything would break.
</p>
</header>
<section class="mb-5">
<div class="row g-3">
<div class="col-lg-7">
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ev1"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="ev1">cspresso https://example.com \
--bypass-csp \
--evaluate "default-src 'self'; script-src 'self' https://cdn.jsdelivr.net;" \
--json</code></pre>
</div>
</div>
<div class="col-lg-5">
<div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Exit codes</div>
<div class="text-muted">
<div><code>0</code> → no Report‑Only violations detected</div>
<div><code>1</code> → violations detected (ideal for CI gates)</div>
</div>
<hr>
<div class="small text-secondary">
Tip: keep your CSP string quoted; it usually contains spaces and semicolons.
</div>
</div>
</div>
</div>
</section>
<section class="mb-5">
<h2 class="section-title fw-bold">Why <code>--bypass-csp</code> matters</h2>
<p class="text-secondary">
If the target site already sets an enforcing CSP, it can block loads and change runtime behaviour.
That can hide potential violations in your candidate policy. Using <code>--bypass-csp</code> strips existing CSP headers
on HTML responses during the crawl.
</p>
<div class="callout p-4">
<div class="fw-semibold mb-2">Safety note</div>
<div class="text-muted">
Bypassing CSP means you’re letting the page execute without those protections. Run evaluation only on sites you trust,
or in a sandboxed environment.
</div>
</div>
</section>
<section class="mb-5">
<h2 class="section-title fw-bold">CI example (GitHub Actions)</h2>
<div class="codeblock">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#gha"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="gha">- name: Evaluate CSP
run: |
pipx install cspresso
cspresso https://example.com \
--bypass-csp \
--evaluate "default-src 'self'; script-src 'self' https://cdn.jsdelivr.net;" \
--json</code></pre>
</div>
<div class="mt-3 small text-secondary">
If you cache Playwright browsers, set <code>--browsers-path</code> to a persistent directory.
</div>
</section>
<section>
<h2 class="section-title fw-bold">Troubleshooting</h2>
<div class="row g-3">
<div class="col-md-6">
<div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Sourcemaps causing connect-src noise</div>
<div class="text-muted">
DevTools often fetches sourcemaps even when headless browsing doesn’t. If you want to model those requests,
use <code>--include-sourcemaps</code> to add sourcemap origins to <code>connect-src</code>.
</div>
</div>
</div>
<div class="col-md-6">
<div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Non-HTML crawled resources</div>
<div class="text-muted">
If your site has downloadable files on the same origin, consider <code>--ignore-non-html</code> to avoid edge cases
like browser “word-wrap” injected styles affecting hashes.
</div>
</div>
</div>
</div>
</section>
</div>
</main>

87
src/content/recipes.html Normal file
View file

@ -0,0 +1,87 @@
---
title: "cspresso Recipes"
description: "cspresso recipes: common commands for crawling, debugging, sourcemaps, AppImage usage, and CI evaluation."
aliases:
- "examples.html"
---
<main class="py-5">
<div class="container">
<header class="mb-4">
<div class="kicker mb-2"><i class="bi bi-lightning-charge"></i> Recipes</div>
<h1 class="display-6 fw-800 mb-2">Practical workflows</h1>
<p class="text-secondary mb-0">A handful of commands that cover most real-world cspresso usage.</p>
</header>
<div class="row g-4">
<div class="col-lg-6">
<h2 class="section-title fw-bold">Draft a CSP</h2>
<div class="codeblock mb-3">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#r1"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="r1">cspresso https://example.com --max-pages 10</code></pre>
</div>
<div class="text-secondary">
Start here, then audit the output. Crawls won’t cover every flow (auth-only pages, conditional loads, A/B tests, etc.).
</div>
</div>
<div class="col-lg-6">
<h2 class="section-title fw-bold">Headed debugging</h2>
<div class="codeblock mb-3">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#r2"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="r2">cspresso https://example.com --headed --settle-ms 2500</code></pre>
</div>
<div class="text-secondary">
Useful when the site does delayed loads or you want to visually confirm what’s happening during the crawl.
</div>
</div>
<div class="col-lg-6">
<h2 class="section-title fw-bold">Sourcemaps &amp; <code>connect-src</code></h2>
<div class="codeblock mb-3">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#r3"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="r3">cspresso https://example.com --include-sourcemaps</code></pre>
</div>
<div class="text-secondary">
If browsers/devtools fetch <code>*.map</code> files from a CDN, this helps make sure the CDN origin lands in <code>connect-src</code>.
</div>
</div>
<div class="col-lg-6">
<h2 class="section-title fw-bold">Upgrade insecure requests</h2>
<div class="codeblock mb-3">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#r4"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="r4">cspresso https://example.com --upgrade-insecure-requests</code></pre>
</div>
<div class="text-secondary">
Handy during migrations when you still have a few stray HTTP URLs.
</div>
</div>
<div class="col-lg-6">
<h2 class="section-title fw-bold">AppImage (writable browser cache)</h2>
<div class="codeblock mb-3">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#r5"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="r5">./cspresso.AppImage https://example.com \
--browsers-path "$HOME/.cache/cspresso/pw-browsers"</code></pre>
</div>
<div class="text-secondary">
AppImages mount read-only. Set <code>--browsers-path</code> so Playwright can install Chromium into a writable directory.
</div>
</div>
<div class="col-lg-6">
<h2 class="section-title fw-bold">CI gate with <code>--evaluate</code></h2>
<div class="codeblock mb-3">
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#r6"><i class="bi bi-clipboard"></i> Copy</button>
<pre class="terminal mb-0"><code id="r6">cspresso https://example.com \
--bypass-csp \
--evaluate "default-src 'self'; script-src 'self' https://cdn.jsdelivr.net;" \
--json</code></pre>
</div>
<div class="text-secondary">
Exits <code>1</code> if the candidate policy would be violated - great for PR checks.
</div>
</div>
</div>
</div>
</main>

73
src/content/security.html Normal file
View file

@ -0,0 +1,73 @@
---
title: "cspresso Security"
description: "Security notes for cspresso: it runs a real browser; what bypassing existing CSP means; and how to use it safely."
---
<main class="py-5">
<div class="container">
<header class="mb-4">
<div class="kicker mb-2"><i class="bi bi-shield-lock"></i> Security</div>
<h1 class="display-6 fw-800 mb-2">Security notes</h1>
<p class="text-secondary mb-0">
cspresso runs a real browser. That’s the point - and also the main safety consideration.
</p>
</header>
<div class="row g-12">
<div class="col-lg-12">
<section class="mb-12">
<h2 class="section-title fw-bold">What cspresso does</h2>
<p class="text-secondary">
cspresso launches Chromium via Playwright and loads your target pages. The site’s JavaScript and CSS execute like a normal browser session.
Network requests are observed to build a draft CSP, and (optionally) a candidate policy is injected as Report‑Only to capture violations.
</p>
</section>
<section class="mb-12">
<h2 class="section-title fw-bold">About <code>--bypass-csp</code></h2>
<div class="callout p-4">
<div class="fw-semibold mb-2">It can change risk</div>
<div class="text-muted">
Bypassing CSP strips existing CSP headers on HTML responses. This option is provided in order to avoid the outcome of the rendering negatively influencing what cspresso thinks a good CSP should be.
If a site is compromised, CSP might have been limiting what injected scripts could do (that's the whole point of a CSP!); bypassing removes that layer.
</div>
<hr>
<div class="small text-secondary">
Recommendation: only use <code>--bypass-csp</code> on sites you trust, or run cspresso inside a sandboxed environment (VM/container).
</div>
</div>
</section>
<section class="mb-12">
<h2 class="section-title fw-bold">Data handling</h2>
<p class="text-secondary">
cspresso’s primary output is a policy string and metadata (visited URLs, notes, and - in evaluation mode - detected violations).
Treat the output as sensitive if your site URLs or CSP reveal internal endpoints.
</p>
</section>
<section>
<h2 class="section-title fw-bold">Hardening tips</h2>
<div class="row g-3">
<div class="col-md-6"><div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Prefer CI / disposable environments</div>
<div class="text-muted">Running in CI makes it easy to isolate and to cache Chromium via <code>--browsers-path</code>.</div>
</div></div>
<div class="col-md-6"><div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Limit crawl scope</div>
<div class="text-muted">Keep <code>--max-pages</code> small and start from a stable landing page to reduce surprises.</div>
</div></div>
<div class="col-md-6"><div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Review before enforcing</div>
<div class="text-muted">cspresso emits a draft. Tighten directives (especially <code>script-src</code>/<code>connect-src</code>) and consider nonces.</div>
</div></div>
<div class="col-md-6"><div class="callout p-4 h-100">
<div class="fw-semibold mb-2">Verify releases</div>
<div class="text-muted">mig5 key: <a class="link-secondary" href="https://mig5.net/static/mig5.asc" target="_blank" rel="noreferrer">https://mig5.net/static/mig5.asc</a><br>Fingerprint: <code>00AE817C24A10C2540461A9C1D7CDE0234DB458D</code></div>
</div></div>
</div>
</section>
</div>
</div>
</div>
</main>