cspresso.cafe/src/content/evaluate.html

---
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>