- how a scan works, and the ways to start one
- how to follow its progress, and what to do when a run fails or is cancelled
- how to read its results, including what scan coverage means
- how pull and merge requests are scanned
- where Earnie keeps past runs
How a Scan Works
A source-code scan has four steps:- Read. Earnie collects the files to scan from your repository, folder, or archive.
- Fingerprint. Earnie reduces each file to a fingerprint, a compact signature that identifies its content. By default, Earnie leaves each file’s licence header, comments, and imports out of the fingerprint, so two files that share only a licence block don’t look alike. The Skip licence headers option in Scan Configuration controls this.
- Match. Earnie compares the fingerprints against the SCANOSS knowledgebase, a large index of known open-source code.
- Enrich. The intelligence layers add licence and vulnerability data to each match.
Starting a Scan
A scan starts in one of three ways:
Earnie also scans each pull or merge request on its own, whatever the Automatic scanning setting. See Pull and Merge Request Scans.
Running a Scan on Demand

- On the project’s page, select New scan.
- Choose the source:
- Upload, to scan a folder or an archive. Click the drop area to choose a folder, or drag a folder or a
.zip,.tar.gz, or.tgzarchive onto it. - Repository, to scan a repository from a GitHub or GitLab connection. Earnie scans its default branch unless you choose another. See Scanning Another Branch.
- Import SBOM, to import a software bill of materials instead of scanning code. See Importing an SBOM.
- Upload, to scan a folder or an archive. Click the drop area to choose a folder, or drag a folder or a
- Optionally, give the scan a Display name, so you can find it later in Scan history.
- Unless you’re importing an SBOM, choose the scanners and intelligence layers. See Choosing Scanners.
- Select Start scan. Earnie opens the scan’s progress page.
Scanning Another Branch
On the Repository source, Branch chooses what Earnie scans. It starts on the repository’s default branch, marked (default). Open it to search the repository’s branches, or type the name of a branch, tag, or commit that isn’t listed. A connection that can’t list branches leaves a text field instead: type a name, or leave it empty to scan the default branch. A scan of any other branch doesn’t update the project’s findings or posture. Only a scan of the default branch does, so the page says “A scan of another branch does not update the project’s posture.” when you pick one. The scan still appears in Scan history with its branch.Choosing Scanners
A scanner analyses your source code. Under Scanners, Earnie shows each scanner your organisation has: OSS matching, Cryptography, and AI provenance. All of them are selected. You can turn any off for this scan, but at least one must stay selected. If your organisation has only one scanner, the section doesn’t appear. Under Intelligence layers, Vulnerabilities and License add vulnerability and licence data to what the scanners find. Snippet classification scores each open-source snippet match, and proposes the ones that look wrong for you to review. All three are on. Turning one off makes the scan finish sooner and removes its stage from the progress page. Snippet classification is offered only beside OSS matching, and it needs the scanned files, so a scan that imports an SBOM never runs it. To score a match, Earnie reads the matched open-source file from SCANOSS, up to 2,000 files per scan, and each read counts against your SCANOSS API key’s quota. Turn the layer off to stop those reads. See Open-Source Matches for what a proposal looks like. Earnie offers intelligence layers while OSS matching is selected. With the Enrichment module, Earnie offers them with any scanner, and adds licence and vulnerability details to the components that Cryptography and AI provenance find, such as the library a cryptographic call comes from. The self-hosted installer always turns this module on. From the Earnie CLI, pass--scanners to choose the scanners.
Importing an SBOM
An SBOM (software bill of materials) is a document that lists the components a piece of software contains. If you already have one, you can import it instead of scanning source code. Earnie accepts CycloneDX and SPDX 2.1 to 2.3 documents, in JSON format only. The Import SBOM drop area shows the largest document Earnie accepts. Earnie refuses a larger file before it sends any of it, with a message that names the file’s size and the limit. It also refuses a document that’s already been imported into the project. An imported SBOM lists declared components only, with no code to match. So the run always has partial coverage, and you don’t choose scanners for it. When the SBOM declares a licence for a component, Earnie keeps it and labels it FROM SBOM, so you can tell it apart from a licence SCANOSS detected. If both exist for the same component, the licence SCANOSS detected takes precedence.How Your Source Reaches Earnie
Earnie doesn’t scan every file in your project. Skip rules decide which files to keep, and Earnie sends and stores only the files it keeps. The rules come from your Skip patterns and size limits in Scan Configuration, the repository’s.gitignore, and its scanoss.json. They apply whichever way your source arrives:
Earnie normally leaves out generated folders, such as
node_modules. It may still keep a dependency manifest from inside one, because later stages need it. A dependency manifest is a file such as package.json that lists a project’s dependencies. So the file viewer can show such a folder with only its manifest in it.
Large Folders and Archives
For a folder, Start scan responds at once, however large the folder, because Earnie works out which files to keep afterwards, in a Selecting files stage. If the kept files are still too large to scan, the scan fails withkeep_set_too_large. Leave out generated folders, or scan a smaller tree.
A large upload can take a while. Keep the browser tab open, and in the foreground, until the Receiving files stage finishes:
- If a folder transfer keeps failing, an Upload stalled banner appears. Select Retry upload to continue from where it stopped. This works only in the same tab: reloading the page loses the selected files.
- If an archive upload fails, after Earnie has retried it, the scan is cancelled, and the New scan page shows a network error. Start the upload again.
- If no files arrive for an hour, Earnie fails the scan.
Following Scan Progress

An imported SBOM runs fewer stages: Importing SBOM, then Finalizing, then the intelligence layers. If the document contains a component Earnie can’t read, such as one with neither a name nor a package identifier, Earnie skips it and shows a warning under Importing SBOM.
Cryptography Steps
The cryptography scan shows its own steps under Detecting cryptography, as it reaches them:- Cryptography: scanning source
- Cryptography: scanning dependencies
- Cryptography: building call graph
requirements.txt and a JavaScript front end with a package.json. When the scan doesn’t check the dependencies of every manifest it finds, the step shows a warning that names the language and the manifest it didn’t check, such as “the Python dependencies in requirements.txt were not checked for cryptography”. A JavaScript manifest counts only with its package-lock.json beside it, because the scan needs the lockfile to know which versions are installed. While such a warning is shown, Earnie doesn’t mark earlier cryptography findings in those dependencies as resolved, because the scan never read them.
When a Stage Fails
What a failure does depends on the stage:- A core stage or a scanner fails. The whole run fails. The stage that failed shows its cause. Stages that were running beside it are marked failed with
cancelled: sibling phase failed, because the run was already over, not because of anything they found. - An intelligence layer fails. The run still completes, with your scan results. A warning appears under that layer, such as Vulnerability enrichment did not complete. Re-run the scan once the service is back to fill in that layer’s data.
When a Run Fails or Is Cancelled
A run that ends without results opens on its own page, which explains what happened:
The Run details card shows the stage the run stopped at and how far it got, the source, when it started and ended, the reason code, and the Scan id. Quote the scan ID when you ask an administrator to check the logs.
Reading the Results

- Run totals: the Findings, the Components in this scan, the Dependencies, and the Files scanned.
- The policy gate card: the gate, and a button to review the findings behind it: Review N blocking for a Block, Review N that need approval for Needs approval, or Review N warned for a Warn. It opens a list of those findings, 25 at a time, linking to each finding in the Review Workspace. Admins and Operators can also select Request approval on a row.
- The Configuration card: the scanners that ran, under Domains, and the intelligence layers, under Enrichments.
- The Audit trail card: the run’s history. See The Audit Trail of a Run.
Coverage: Full vs Partial
Every run has a coverage level, which decides whether it can remove findings:- Full coverage. The run looked at the whole project, so it can mark a finding it no longer sees as absent. Its badge reads Updates findings. It doesn’t mean Earnie read every file: Files scanned counts the files left after the built-in exclusions.
- Partial coverage. The run saw only part of the project, for example an imported SBOM or a pull request scan. It adds and updates what it saw, but never marks anything absent, because it can’t tell what isn’t there. So an imported SBOM can never remove a finding that an earlier full scan found. Hover over or focus a run’s badge to see why it’s partial.
You can re-scan as often as you like. Decisions you’ve already recorded
survive a re-scan, and a new run never asks you to triage the same finding
twice. The exception is a file that now matches a different component or
version. It appears as a new finding to review. Earnie hides the earlier
decision but doesn’t delete it.
Crypto Changes Between Scans
When a run measured cryptography across the whole project, its page shows a Crypto changes card. It compares the run with the nearest earlier completed run that also measured cryptography in full, and counts the cryptography findings that are new, resolved, re-detected, and still open. Earnie skips any run in between that skipped cryptography or covered only part of the project. If no earlier run qualifies, the card doesn’t appear, rather than comparing against nothing.Pull and Merge Request Scans
Earnie scans each pull request (a merge request on GitLab), so you see its findings before the change merges:- Opening a pull request starts a scan, and so does each push of new commits to it.
- If an earlier scan of the same pull request is still running when new commits arrive, the new scan replaces it.
- If the pull request is merged or closed while its scan is running, Earnie cancels the scan. The
Earniecheck finishes as cancelled, titled Pull request closed before the scan finished, with no summary comment. Scan history shows the run as Cancelled.
scanoss.json changed, or the SCANOSS knowledgebase was updated.
What Earnie posts on the pull request is covered in Merge gate.
Scan History

74 of 80 files. Duration says how long a finished run took. A failed run says why under its status. The status control counts every run, and the page’s address keeps the search, the status, and the page, so a link opens the same rows.
Self-checks, the quick checks coding agents run on changed files, are not scans and don’t appear here.
The Audit Trail of a Run
Every completed, failed, or cancelled run has an Audit trail card. It lists the run’s own history, oldest entry first, read from the organisation audit log. The trail answers the question a reviewer asks months later: which code, which policies, which actor, and which outcome produced this gate? It records:- Submitted. Who asked for the run: a person, an API key under its own name, or the GitHub or GitLab connection. It also records the commit and branch, the scanners that ran, the coverage, and the number of policies in force.
- Gate evaluated. The gate the run was given. If a Policy Approval later changes the gate without a new scan, a Gate updated entry follows.
- Published. What Earnie posted on the pull or merge request, including any retry someone requested and any publication Earnie had to give up on.
earnie scan audit <id>.