Last updated on 18th May 2026

Vulnerability scan checks

Vulnerability scan checks are a type of Deployment Check that runs a vulnerability scanner against your project's source on the build server before any build commands execute. If the scanner finds vulnerabilities at or above your chosen severity threshold, the deployment is aborted and the deploy log surfaces a summary of the findings.

Vulnerability scan checks are part of the Deployment Checks beta. Enable beta features on your account to see them in the project sidebar.

When does the scan run?

Unlike SSH and HTTP pre-build checks, which run on the deployment worker before any build resources are spent, vulnerability scans run on the build server after the source has been uploaded but before your build commands execute. This is the only time and place the scanner has access to the full checked-out repository.

The trade-off is that a failed scan still costs you the build-server startup time (typically a few seconds). The pay-off is that you do not need to install or maintain a scanner anywhere — Snyk and Trivy are bundled into the build image, and if for any reason they are not available, the runner installs the pinned version on the fly.

A failed scan aborts the deployment before your build commands run, so you do not waste build minutes on a build whose output will be rejected.

Supported scanners

Trivy

Trivy is an open-source vulnerability scanner from Aqua Security. It needs no account, no API key, and works out of the box.

Pick Trivy if you want a zero-configuration starting point, or if your team has not invested in a paid scanner.

Snyk

Snyk is a commercial vulnerability scanner. It requires a Snyk API token, which you supply by setting a SNYK_TOKEN environment variable on the project or the account.

To set up the token:

  1. In your Snyk account, copy your API token from the User Settings page.
  2. In DeployHQ, open your project's Environment Variables page.
  3. Add a new variable named SNYK_TOKEN with the token as its value.
  4. Save the check.

Pick Snyk if your team already has a Snyk subscription and wants the findings to flow into your existing Snyk dashboard.

Custom

The custom scanner option lets you run any CLI that emits SARIF. You provide the command and the path it writes its SARIF output to. We read the SARIF file to produce the findings summary that appears in your deploy log.

Use this for scanners like Grype, OWASP Dependency-Check, or any commercial tool not directly supported.

Severity thresholds

Every scanner emits findings tagged with a severity. You choose the lowest severity that should fail the deploy:

  • Low or higher — fail on anything the scanner produces. Most strict.
  • Medium or higher — fail on medium, high, and critical findings.
  • High or higher — fail only on high or critical findings. Recommended starting point.
  • Critical only — fail only on critical findings. Least strict.

Scanners differ in how they assign severity, so a finding labelled "high" by Snyk and one labelled "high" by Trivy are not directly comparable. If you switch scanners, expect to retune your threshold.

Configuring a scan check

  1. Open your project and pick Deployment Checks from the sidebar.
  2. Click New Check.
  3. Pick Pre-build as the stage (vulnerability scans run pre-build only).
  4. Pick Vulnerability scan as the type.
  5. Pick a scanner.
  6. Set the path to scan — usually . for the project root, or a sub-path like ./packages/api for monorepos.
  7. Pick a severity threshold.
  8. Save.

Two quick-start templates are available from the empty-state on the Deployment Checks index page: one for Trivy and one for Snyk. They prefill the form with sensible defaults so you can save and try the check in seconds.

Reading the deploy log

When a scan runs, you will see a new step in the deploy log titled Running vulnerability scan checks. Inside it, each check produces:

  • A header line naming the scanner and the path being scanned.
  • The raw scanner output, streamed line by line. The scanner's SARIF JSON blob is collapsed to a placeholder in the UI to keep the log readable — the full raw output is still in the downloaded log.
  • A parsed findings table with columns for Severity, Package, Installed, Fix, Advisory (the CVE or rule identifier), and Title. Rows are sorted with the most urgent first (CRITICAL → HIGH → MEDIUM → LOW). Up to 50 rows are shown; if a scan finds more, the header reads "showing 50 of 73".
  • A summary line with the total finding count and the top five rule identifiers.

On a passing scan the summary reads no findings or shows the counts below your threshold. On a failing scan, the deploy aborts and the failure message names the check.

Two convenience actions appear on the step header when a scan fails:

  • Download logs — saves the full step log as a .txt file, including the raw SARIF JSON your scanner produced. Useful when you want to feed the output into another tool.
  • Explain error — sends the scan output to the AI explanation helper, which summarises the failure and suggests fixes (typically: which packages to upgrade and to which versions). This is the same helper used on build-command failures.

Troubleshooting

The deploy log says "Snyk authentication failed". You have not set the SNYK_TOKEN environment variable on the project or account, or the token is invalid. Generate a fresh token in Snyk and set it as a project or account environment variable.

The scan completes but I see no findings summary. The scanner did not write a SARIF file to the expected path. For custom scanners, double-check the SARIF output path you configured. For Snyk and Trivy, this usually means the scanner exited with an error before producing output — check the raw scanner output for the underlying error.

The scan times out. Increase the check's timeout. Large projects with many dependencies can take several minutes to scan. The default is 300 seconds; the hard cap is 600.

I want to ignore specific findings. For Snyk, commit a .snyk policy file at the path you are scanning — Snyk picks it up automatically. For Trivy, use a .trivyignore file. For custom scanners, follow that scanner's own ignore mechanism.

Limitations in this release

  • Vulnerability scans run at the pre-build stage only. Image scans against a built artifact are not yet supported.
  • Scans run on the filesystem of the checked-out source. Scanning a separate registry image is not supported.
  • Snyk authentication uses the SNYK_TOKEN environment variable — we do not yet have a dedicated Snyk integration model.

These constraints will be revisited in future releases. If your use case bumps into them, let us know.