Security smoke tests for known URLs

Give every preview deployment a fast, credible security gate.

surface-audit is built for teams that already know the target URL and want deterministic security checks before promote-to-production time. It scans a bounded surface, produces CI-friendly reports, and keeps the result explainable.

Install from PyPI Open recipes Release flow

Preview and staging scans without crawler sprawl
Baseline and diff workflows for regression-focused gating
SARIF, Markdown, HTML, and JSON output for CI and review surfaces

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

Summary: HIGH 1  MEDIUM 2  LOW 1

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

Primary fit Preview security gate

Known URL, bounded probes, clear findings.

CI output SARIF, Markdown, JSON

Works in code scanning, PR summaries, and pipelines.

Delivery PyPI, GHCR, GitHub Action

Install the CLI, use the image, or drop in the action.

Trusted Publishing Sigstore signing CycloneDX SBOM GitHub Action GHCR image MCP allow-list

Delivery path

How teams use it in a real release flow

The product is most useful when it sits between “preview environment is ready” and “this build can be promoted.” The goal is not breadth. The goal is a dependable regression signal.

Point it at a known URL

Use the staging or preview address you already trust as the deployment target.

Run a bounded scan

Scope hosts explicitly, keep concurrency polite, and emit machine-readable output.

Compare against a baseline

Use baseline suppression or explicit report diff to focus on regressions.

Fail only when it matters

Gate on new HIGH+ findings, upload SARIF, and keep the result visible in review.

Integrations

Drop it into the stack you already have

GitHub Action

- 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

MCP server

pip install "surface-audit[mcp]"
surface-audit mcp-serve \
  --allow-host staging.example.com \
  --allow-host preview.example.com

Trust surface

Built to be easy to justify in CI

Release hygiene

Tagged releases publish to PyPI, GitHub Releases, and GHCR.

Supply-chain signals

Trusted Publishing, Sigstore signatures, and CycloneDX SBOMs are in the flow.

Safe automation story

MCP access is constrained by explicit host allow-lists rather than open-ended browsing.

Focused operating model

The core stays narrow: smoke tests, not a sprawling crawler or exploit platform.

Positioning

Use it when the question is “did this deployment make things worse?”

Great fit

Preview, staging, or pre-production URLs
Teams that want a deterministic gate in CI
Security regression tracking with baseline or diff
Output that feeds code scanning, dashboards, or PR comments

Use other tools when

You need crawling or spidering
You need authenticated browser or session flows
You need exploit confirmation
You want a giant template corpus over a narrow, stable story

Artifact previews

Inspect representative outputs before you wire the tool into CI

These samples show the three report surfaces most teams evaluate first: terminal output for humans, HTML for quick sharing, and SARIF for code scanning integrations.

Console Open sample

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

HTML Open sample

<title>surface-audit Report</title>
Target: https://preview.example.com/
Duration: 3.00s
Findings: 4

HIGH    security-headers
MEDIUM  auth-cookies
MEDIUM  security-txt
LOW     directory-listing

SARIF Open sample

{
  "version": "2.1.0",
  "runs": [
    {
      "tool": { "driver": { "name": "surface-audit" } },
      "results": [
        { "ruleId": "surface-audit/security-headers" },
        { "ruleId": "surface-audit/auth-cookies" }
      ]
    }
  ]
}

Docs and support

Start with the README, then go deeper only when you need to

README Core positioning, quick start, GitHub Action, and output overview. Recipes Preview gates, baseline mode, diff workflows, MCP, and container usage. Architecture Layering, extension points, and the boundaries of the core project. Plugin template Starter package for a third-party check with entry points and tests. Support When to open an issue, when to use Discussions, and where security reports go.