Run a scan

A scan checks a repository's commits with one scanner 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

1. Vulnara checks that the repository is enabled and that the git token, if you chose one, is valid and not expired.
2. It clones the repository and lists the commits to scan: every commit on every branch, or only the commits on the branches you chose.
3. Each commit is checked out and the scanner runs over the files. The .git directory and any ignore paths are kept out of the scan.
4. The scanner's output is turned into findings with a severity. See Scanners.
5. When every commit has been accounted for, the scan finishes and the repository's security score is recalculated.

Commits already scanned are reused

When you scan a repository again, commits that were already scanned with the same scanner are not scanned a second time. Vulnara reuses their results and counts them as done, so a re-scan only does the work for new commits. A scan in which every commit was reused still finishes successfully.

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.
• Scanners: every available scanner is selected by default. Vulnara starts one scan per scanner you keep.
• 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 scanners, and choose whether to create issues.
4. Choose Start scan. Vulnara opens Repository Scans and the scan appears in the tasks bar.

From the CLI, each scan names one scanner:

vulnara start_repository_scan --repositoryId <repository-id> --dockerScanToolId <scanner-id> --branch main

With GraphQL, use startRepositoryScan. List the scanner ids with dockerScanTools.

mutation StartScan($input: StartRepositoryScanInput!) {
  startRepositoryScan(input: $input) {
    id
    status
  }
}

See 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, repository, organisation) and sort by newest or by progress. Finished tasks are collapsed into their own section.

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. If you start several scans together and only some are refused, the others still start. Failed scans count towards scan time.
• 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.