Vulnerability scan checks are a type of Deployment Check that runs a security scanner against your project's source on the build server before any build commands execute. Use them to gate deployments on two things: known vulnerabilities in the dependency tree (Trivy) and leaked secrets in the repository (TruffleHog). If the scanner reports findings 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 — Trivy and TruffleHog 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](https://trivy.dev) 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 for catching known CVEs, or if your team has not invested in a paid scanner. ### TruffleHog [TruffleHog](https://trufflesecurity.com/trufflehog) is an open-source secrets scanner from Truffle Security. Instead of looking for vulnerable dependencies, it walks your repository for API keys, tokens, and credentials that should not be checked in. By default, only **verified** live secrets are reported — TruffleHog has confirmed with the upstream provider (AWS, GitHub, Stripe, etc.) that the credential is active. This keeps the false-positive rate low. Unverified findings (a string that looks like a token but cannot be confirmed) do not fail the check. Pick TruffleHog if you want to catch committed credentials before they ship. Many teams run a TruffleHog pre-build check alongside a Trivy pre-build check. ### 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 Trivy and one labelled "high" by another scanner 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. Quick-start templates are available from the empty-state on the Deployment Checks index page. They prefill the form with sensible defaults so you can save and try a 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 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 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 Trivy, use a `.trivyignore` file. For TruffleHog, use the `--exclude-paths` or `--exclude-detectors` mechanism via a custom command, or accept the noise and rotate the flagged credentials. For other 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. These constraints will be revisited in future releases. If your use case bumps into them, let us know.