Run a scan

A scan checks a repository's commits and turns what it finds into findings. You start it from the web app, the CLI or the GraphQL API, and follow it live in the tasks bar until it finishes.

What it is for

Run a scan when you connect a repository, before a release, or whenever you want an up-to-date picture of a repository's secrets, personal data and vulnerable dependencies. To run scans on a fixed cadence instead, see Schedule recurring scans. To scan from a pipeline, see GitHub Action.

How it works

A scan covers every commit on every branch, or only the commits on the branches you choose, leaving out files that match your ignore paths. What it finds becomes findings, each with a severity and a category (see Scan categories), and the repository's security score is updated when the scan finishes. Each commit is scanned once per scanner, so scanning a repository again only checks its new commits.

Which findings come from which commits

Secret and personal-data findings are recorded for every commit scanned. Dependency findings are recorded only for the last commit, the head of the default branch, because that is the code you ship.

What you can set

• Workspace: the git workspace the repository belongs to. Repositories and tokens are scoped to it.
• Repository: the repository to scan.
• Git Token: optional. Leave it blank to scan with Vulnara's default access, which reaches public repositories only. The first valid token linked to the git workspace is filled in for you. A token is required to create issues.
• Branches: leave empty to scan every commit across all branches (full history). Add one or more branch names to scan only those branches' commits. The list offers the repository's real branches, and you can also type a name.
• What to scan for: the categories the scan covers. Every category your workspace may run is selected by default. Each category you keep queues every scanner that serves it, so one category can produce more than one scan.
• Create issues: open an issue in the repository for the findings. Needs a git token.
• Auto-remediate: open a pull request that fixes findings. Needs Create issues. See AI remediation.

Do it

1. In the web app, choose New Scan in the sidebar, then Repository. You can also start a scan from a repository's row on the Repositories screen, or with New scan in a git workspace.
2. Pick the git workspace and repository, and optionally a git token and branches.
3. Keep or remove categories under What to scan for, and choose whether to create issues.
4. Choose Start scan. Vulnara opens Repository Scans and the scan appears in the tasks bar.

A category that resolves to three scanners and queues two of them is reported as a partial start rather than as a plain success, so you can see that part of it did not run. The message says why: a scanner your plan's limit held back is reported as the plan's limit, and any other scanner that did not start is reported as one that could not be started, so you are not told to wait for a limit that did not apply. Started scans, refused categories and skipped scanners are counted separately.

Run a scan again

To re-run a scan, choose Redo Scan on it under Repository Scans, or Re-run with Auto-Remediation on a finished scan. A re-run repeats exactly the scanners that produced the scans you chose, once each, rather than every scanner in their categories. The form names the categories those scanners cover and offers no category picker.

From the CLI or the API

From the CLI, name a category:

vulnara start_repository_category_scan --repositoryId <repository-id> --category SECRETS --branch main

--category takes SAST, SCA, SECRETS or PII, in either case, and any other value is refused. Web applications are not scanned this way; see Scan a web application. vulnara scan_categories lists the categories your workspace may run.

With GraphQL, startRepositoryCategoryScan takes a category and queues every scanner serving it. It answers with requested, how many scanners the category resolved to, queued, how many started, the id of each scan it started, and one skipped entry, with its reason, for each scanner that did not start. List the categories your workspace may run with scanCategories.

mutation StartScan($input: StartRepositoryCategoryScanInput!) {
  startRepositoryCategoryScan(input: $input) {
    requested
    queued
    scanResultIds
    skipped {
      reason
    }
  }
}

The older startRepositoryScan names one scanner by id and still works. It is what the GitHub Action's scan-tools input and the CLI's start_repository_scan --dockerScanToolId send. List the ids your workspace may run with vulnara docker_scan_tools or dockerScanTools; they are opaque identifiers.

See start_repository_category_scan and start_repository_scan for every CLI flag. To follow or stop a scan outside the web app, use tasks, taskEvents and cancelTask, or the CLI commands tasks and cancel_task.

Follow the progress

The tasks bar shows each running scan with the commits scanned out of the total. The total reads as calculating until Vulnara has listed the commits. Once enough progress has been made, it shows an estimated time remaining. If some commits fail to scan, the task is shown in a warning state while the rest carry on.

You can filter the tasks bar by type (network, web, repository, organisation) and sort by newest or by progress. Finished tasks are collapsed into their own section. The tasks bar also shows git workspace imports, and when an import fails it shows the reason under the task. See Connect a git provider.

Cancel or dismiss

• Cancel: stops a scan that has not finished, after you confirm. Scanning stops at the next commit and the scan is marked cancelled.
• Dismiss: removes a failed task from the tasks bar. A running task cannot be dismissed; cancel it instead.

Good to know

• A scan is marked failed when there were commits to scan and none of them could be scanned, for example when a private repository cannot be cloned because no valid token was given. An empty repository finishes successfully, because there was nothing to scan.
• Disabled repositories cannot be scanned. Enable them on the Repositories screen first.
• Your plan limits scan time per month and how many scans run at the same time. When the monthly allowance is used up, new scans are refused until it resets or you upgrade. When too many scans are already running, the extra ones are refused and you can start them again when one finishes. Repository, network and web application scans all count towards that limit together. A category counts as one scan against that limit however many scanners it starts, so it is admitted or refused whole. If you start several categories together and only some are refused, the others still start. Only successful scans count towards scan time; a failed or cancelled scan uses none.
• Starting a scan needs the Editor role or above. See Teams and roles.
• When a scan finishes or fails, Vulnara can notify you, and a scan that introduces new critical or high findings raises its own alert. See Notifications and Alerts.
• Deleting a repository or git workspace cancels any scan still running for it.