Practical workflows

Commands for the updated CLI. Review generated permissions and scan status before using a policy.

Draft and inspect evidence

cspresso https://example.com/ --max-pages 10 --json

Review observations to see which document and resource led to a proposed permission. Requests are evidence, not proof of necessity.

Save a candidate policy

cspresso https://example.com/ --bypass-csp --header-only > candidate-csp.txt

Check the exit status, review the file, then evaluate it. Diagnostics go to stderr; incomplete scans may still emit a draft.

Evaluate a policy file

cspresso https://example.com/ --bypass-csp \
  --evaluate-file candidate-csp.txt --json

Exit 0 means completed coverage without observed violations; exit 1 means violations; exit 2 means incomplete/error.

Limit crawl scope and work

cspresso https://example.com/docs/ \
  --exclude '/logout*' --exclude '/delete/*' \
  --max-pages 20 --max-requests 1500 --scan-timeout 180 --json

Exclusions apply to top-level URLs and paths. They do not constrain all network traffic or prevent page scripts causing side effects.

Inspect source-map metadata

cspresso https://example.com/ --include-sourcemaps --json

Look at sourcemaps. Debugging metadata no longer automatically widens connect-src; some body scans are skipped for size/encoding limits.

Headed debugging

cspresso https://example.com/ --headed --settle-ms 2500

Observe loading behavior while the Chromium process sandbox stays enabled. This does not add scripted interaction coverage.

AppImage with a browser cache

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

The default is already a writable user cache. Use an explicit owned directory for a different location; do not use a shared writable cache.

Use a preinstalled browser

cspresso https://example.com/ --no-install \
  --browsers-path "$HOME/.cache/cspresso/pw-browsers"

The cache must contain the Chromium revision expected by the installed Playwright package. Explicit paths work even when installation is disabled.

Develop with Poetry 2.x

poetry sync --with dev
poetry check --lock --strict
poetry run pytest
poetry run cspresso https://example.com/ --json

Run from the source checkout with Poetry >=2.2,<3 (CI pins 2.5.1). Browser integration tests use poetry run pytest --run-browser once Chromium is installed.

Check policy size

cspresso https://example.com/ --header-budget 8192 --json

Inspect header_bytes and size notes. The threshold is advisory; confirm your server/proxy limits before deploying.