Your first scan

Connecting a repository queues its first scan immediately. This page is what that scan actually does, in the order it does it.

Starting a scan

A scan starts in one of four ways: you connect a repository, you ask for one, a commit lands on the default branch and the repository is set to scan on push, or a scheduled interval comes due. See Scan triggers.

cf scan
cf scan --branch release/2.4
cf scan --wait

The states a scan moves through

A running or queued scan can be stopped with Stop on the Repository coverage run strip. The scanner stops at its next lane or batch, the scan is recorded as cancelled with the name of whoever stopped it, and the audit log gets a scan.cancelled event. Results already on screen stay as they were, because Repository coverage reads completed scans.

The default branch is scanned unless you name another with --branch. Whichever branch it ran on, findings belong to that scan, so reading a branch means naming it.

What the scan reads

Cefense fetches the repository contents at the commit being scanned, through the provider API using the credential you granted. It reads source files, dependency manifests and lockfiles, and infrastructure and configuration files.

It deliberately skips a great deal. Version control internals, installed dependencies and virtualenvs, build and cache output, minified bundles, binaries and media, prose and data files, symlinks, and any single file past a size cap are all left out. Lockfiles are read for the dependency check but never analysed as source.

Build output is skipped, unless it is the package

dist, build, and out are the one exception to the skip list. In an application they are compiler output and are left alone. In a package that publishes only its compiled form, with no source directory beside it, the entry point in its manifest resolves into one of those directories and that is the only code there is, so it is read. The decision is made package by package, which is what makes it come out right in a monorepo that contains both kinds.

A very large repository is truncated

The practical answer is to keep what you want scanned separable: a repository that carries a large corpus of test data, fixtures, or generated assets alongside the code spends the ceiling on the part you did not care about.

Single files have their own limit of 512 KiB. A file over it is not read and the scan records it as a gap. A file under it is read in full however long it is: one that does not fit a single request is read in overlapping parts, and findings in a later part carry their line in the whole file.

What the scan never does

• It does not run your code, your test suite, or your build.
• It does not read your working tree. Only what is committed to the connected repository.
• It does not touch your production environment. There is no agent to install.

How long it takes

A first scan of a large repository takes a few minutes. Later scans of the same repository are faster: analysis of a file that has not changed since it was last analysed does not have to be repeated. cf scan --wait blocks until the scan settles, for up to about ten minutes, and then returns the status and the finding count.

How much work a scan does also depends on which checks are on and how deep the repository is set to scan. Turning on every check costs more time than the four that are on by default, and a repository set to max depth scans several times longer than one at default. All of it is spent from the organization's allowance, and a scan is refused when that is gone. See Checks, Scan depth, and Usage and limits.

When the scan finishes

Findings are stored against that scan and appear in Findings and in cf reproduced, worst first. Each one is reconciled against the previous scan of the same repository, which is what lets the commit history say what a commit introduced and what it resolved. See Branches and commits.