Skip to main content
A scan is one analysis of your code at a point in time. It finds the open-source components and copied code in your project, with their licences and known vulnerabilities. If your organisation has them, it also finds the cryptography your code uses and the AI models, SDKs, and datasets it relies on. The results become the findings you review, and Earnie checks them against your policies to give the run a gate: Pass, Warn, Needs approval, or Block. If you’ve completed workspace setup, your first scan is already running. This page explains: Admins and Operators can start and cancel scans. Viewers can follow scans and read their results.

How a Scan Works

A source-code scan has four steps:
  1. Read. Earnie collects the files to scan from your repository, folder, or archive.
  2. 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.
  3. Match. Earnie compares the fingerprints against the SCANOSS knowledgebase, a large index of known open-source code.
  4. Enrich. The intelligence layers add licence and vulnerability data to each match.
The cryptography and AI provenance scanners, if your organisation has them, run alongside these steps.

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

The New scan page on the Upload tab, with the Display name field, the folder drop area, the Scanners section, and the Scan summary with Start scan
  1. On the project’s page, select New scan.
  2. 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 .tgz archive 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.
  3. Optionally, give the scan a Display name, so you can find it later in Scan history.
  4. Unless you’re importing an SBOM, choose the scanners and intelligence layers. See Choosing Scanners.
  5. Select Start scan. Earnie opens the scan’s progress page.
If you scan a repository commit that Earnie has already scanned with the same settings, Earnie shows that scan instead of running a new one.

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 with keep_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

A scan in progress: the Stages list with each stage's state, how long it has run and its file counts, and Cancel scan with the overall percentage in the header The progress page lists each stage of the run with its state in a word and an icon: pending, running, done, skipped, or failed. A stage also shows how long it has run or took, and how many items it has done. A pending stage is waiting for its turn, not stalled. The percentage in the header stays under 100 until every stage has finished. To stop a scan at any stage, select Cancel scan. Earnie stops the transfer and every job for that run. A source-code scan runs these stages: 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
A large repository can spend a long time in one step, and the steps show that the scan is still working. A skipped step gives the reason, for example that the project has no dependency manifest the scan can read. Cryptography: scanning dependencies also tells you when it left some of your dependencies unchecked. A project can declare dependencies for more than one language, for example a Python web app with a 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.
A failed run doesn’t change any of your findings.

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

A completed run blocked by policy: the policy gate card with Review 4 blocking, the run totals, and the Stages list When a run completes, its page shows:
  • 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.
To scan the project again, select Re-scan.

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.
The Dashboard and Review Workspace use your most recent full-coverage run. If a project has only partial runs, such as imported SBOMs, they use the latest of those, and the Dashboard says so. Treat that posture as a minimum: it lists what the SBOM declared, and nothing about code it didn’t mention.
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 Earnie check finishes as cancelled, titled Pull request closed before the scan finished, with no summary comment. Scan history shows the run as Cancelled.
A pull request scan stands alone. It never changes the project’s current findings or posture. Those change only when the code reaches the default branch, through the scan of the merged commit. You can still resolve or reopen a finding the pull request introduced before it merges. See “Deciding a Pull Request’s Own Findings” in Triaging findings. A pull request scan has partial coverage, and Scan history labels it PR scan, or MR scan on GitLab. Its Findings tile leads with the findings the change introduces, new in this pull request, or nothing new in this pull request. The line under it, N across the codebase with this change, is the total the project would carry once the change merges. To save time, Earnie reuses the default branch’s results for files the change didn’t touch, and keeps the cryptography results when nothing the cryptography scan reads has changed. It runs a full scan instead when it can’t be sure, for example when there’s no earlier default-branch scan, the change touches more than 2,000 paths, the scan configuration or scanoss.json changed, or the SCANOSS knowledgebase was updated. What Earnie posts on the pull request is covered in Merge gate.

Scan History

Scan history Scan history lists the project’s scans. You can filter it by status and by source. Each row shows the run’s coverage and its Gate: Pass, Warn, Needs approval, Block, Error, No policy applied, or No verdict recorded. When a run read fewer files than it was given, its coverage shows a count, such as 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:
  1. 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.
  2. 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.
  3. 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 records each actor as it was at the time. An API key that’s renamed later still appears under the name it had when it ran. Automation can read the same trail with earnie scan audit <id>.

What’s Next

With a full-coverage scan complete, open the Dashboard. It shows whether you can ship, which findings need a person to decide, and which are high risk.