security smoke tests for known URLs

Catch preview regressions before they ship.

surface-audit sends a small, bounded set of safe probes at staging and preview URLs, then turns the result into CI-friendly output: console, JSON, Markdown, HTML, and SARIF.

Install from PyPI Use the action

boundedknown target URL

regressionbaseline and diff

CI-nativeSARIF and gates

publishedPyPI, GHCR, Action

The problem

Preview environments move faster than security review.

A deployment can change headers, cookies, redirects, TLS behavior, CORS policy, or exposed files without changing application logic. Those changes are easy to miss in ordinary tests and too noisy for a full crawler on every pull request.

surface-audit keeps the workflow narrow. It is not a full DAST platform and not a replacement for human security review. It answers one direct question: did this known URL get less safe?

The workflow

Run, compare, gate.

01Point at previewUse the URL your deploy system already produced.

02Scope explicitlyKeep probes bounded to approved hosts.

03Compare to baselineFocus on findings that are new or worse.

04Fail on signalGate only at the severity threshold you choose.

pipx install surface-audit

surface-audit scan https://preview.example.com \
  --scope-host preview.example.com \
  --baseline reports/baseline.json \
  --fail-on HIGH \
  --output reports/preview.sarif \
  --format sarif

GitHub Actions

Use the moving major tag, or pin the exact release.

@v1 is the stable 1.x action line. It moves to the newest compatible release, so users get patch and minor fixes. @v1.0.2 is an exact release tag for workflows that need maximum reproducibility.

- name: Run surface-audit
  uses: dev-ugurkontel/surface-audit@v1
  with:
    target: ${{ steps.preview.outputs.url }}
    scope-hosts: preview.example.com
    output: reports/surface-audit.sarif
    format: sarif
    fail-on: HIGH

Version surfaces

There are four names because there are four distribution surfaces.

PyPI1.0.2 is the Python package version.

GitHub Releasev1.0.2 marks the exact release commit and assets.

GitHub Actionv1 moves to the latest compatible 1.x action release.

GHCR1, 1.0, 1.0.2, and latest are container image tags.

Sample report

Readable locally, structured in automation.

Target: https://preview.example.com/
Summary: HIGH 1  MEDIUM 2  LOW 1

HIGH     security-headers     Missing Content-Security-Policy header
MEDIUM   auth-cookies         Cookie 'sessionid' missing SameSite
MEDIUM   security-txt         Missing /.well-known/security.txt
LOW      directory-listing    Auto-generated index page exposed

Outputs

Inspect the artifact before wiring it into CI.

Console sampleHuman-readable terminal output. HTML sampleShareable single-file report. SARIF sampleCode scanning compatible JSON.

Docs

Start small, then go deeper only when needed.

READMEPositioning, quick start, and common paths. RecipesPreview gates, baselines, SARIF, MCP, and Docker. Release processPyPI, GHCR, GitHub Releases, and action tags. SupportWhere to ask, propose, or report privately.