Skip to main content
This guide is for customers who use the SCANOSS v2 API today: scanoss-py against /scan/direct, the SCANOSS integrations built on it, or a self-hosted SCANOSS deployment. It explains what changes in v3, who needs to act, and where to go next. We recommend v3 for new work and for any pipeline you are about to change. v2 keeps working for now. There is no date by which you must move.

​
What v3 is

v3 is the current SCANOSS API. Every endpoint lives under /v3, on one service: scanning, decoration (licences, vulnerabilities, cryptography, dependencies, geoprovenance, copyright, components), and file contents. A scan is a chunked upload of fingerprints followed by polling for the result, so large projects don’t need one long request. The client for v3 is scanoss-cli, a Go command-line tool that replaces scanoss-py for scanning in your own pipelines. v2 and v3 are not interchangeable. scanoss-cli only speaks v3, so it can’t talk to a v2 server or to OSSKB.org. scanoss-py speaks v2, so it can’t talk to a v3 server.

​
Why move to v3

​
Results that understand your project

v2 identifies each file on its own. v3 looks at the whole project first: it counts which components the files share, ranks them across the project, and only then picks the best match for each file. Short or generic files that a v2 scan attributes to whichever repository copied them get the right component, because the rest of the project points to it. In our tests on CPython 3.14, scanning files one at a time put the correct component first in 80% of the cases. With project context, it came first in every file that matched: 3,340 out of 3,340. The scan also runs in passes. Every file is matched as a whole first, and snippet matching runs only on the files that found no full-file match. This keeps the snippet pass focused on the code that needs it.

​
A confidence grade on every match

Each match in a v3 result says how sure SCANOSS is: HIGH, MEDIUM, or LOW, along with its match percentage. The grade takes into account how much of your project shares the component, whether the file sits at the same path as in the component, the size of a snippet, and whether the match looks like a vendored copy or a fork. You can review LOW matches first and trust HIGH ones. We validated the grades on about 300 open-source projects. More than 99% of the correct matches were graded HIGH, and fewer than 1 in 10,000 correct matches were graded LOW. You also choose how many candidate components each match reports, from one up to all of them, with --max-components.

​
Large scans that finish

v2 sends fingerprints in many small synchronous requests, and a long scan can hit a timeout. v3 uploads the fingerprints in blocks, queues the scan on the server, and lets the client poll for the result. If the connection drops while you wait, scanoss-cli results <scan-id> fetches the result of the same scan instead of starting again.

​
One API for scanning and decoration

Scanning and every decoration service live under /v3 on one service, with one API key. Most lookups take a batch of components in one request (licences, vulnerabilities, cryptography, dependencies, and more) and report a status for each item, so one bad PURL doesn’t fail the rest. Newer capabilities, such as cryptography reachability, exist only in v3. See the API overview.

​
A simpler client

scanoss-cli is a single binary with no Python runtime to install or keep up to date. It builds CycloneDX 1.7 and SPDX 2.3 SBOMs locally from the scan result, applies your scanoss.json BOM rules, and can enrich an existing SBOM. See scanoss-cli.

​
A smaller knowledge base for self-hosted deployments

The crc64 knowledge base that v3 uses takes about 7.5 TB, against 25 to 27 TB for the v2 KB. Our own v3 scan nodes run on 64 GB of RAM, half of what we recommend for a v2 deployment. A self-hosted v3 deployment also serves the full set of decoration APIs from your own infrastructure. See Hardware requirements.

​
Who is affected

​
What keeps working on v2

v2 keeps working for now. In particular:
  • scanoss-py and every tool built on it keep scanning against api.scanoss.com and OSSKB.org.
  • Self-hosted v2 deployments (the scanoss-go-api service, engine 5.x, LDB 4.x) keep working with the knowledge base you have today.
  • Your scanoss.json files keep working with scanoss-py. scanoss-cli reads the same file, with the differences listed in Settings file.
Because nothing is switched off, you can move one pipeline at a time and compare the results before you rely on them.

​
Integrations

These integrations run scanoss-py or call the v2 API, and they will stay on v2. SCANOSS won’t move them to v3:
  • the SCANOSS code-scan GitHub Action (scanoss/gha-code-scan)
  • the GitLab, Azure DevOps, and Jenkins integrations
  • the SCANOSS pre-commit hooks
  • SBOM Workbench
  • Code Compare (scanoss.cc)
  • the scanoss.js SDK
If you use one of them, you have three options:
  1. Keep it. It keeps working on v2.
  2. Move to Earnie. Earnie replaces the GitHub Action, the pre-commit hook, Code Compare, and policy checks with one platform. See Migrating from SCANOSS Tools.
  3. Build the same step with scanoss-cli and a Recipe. Each Recipe is a plain shell script that runs in any CI system or Git hook:

​
Before you start

Check these before you move anything:
  • You have an API key. scanoss-cli uses https://api.scanoss.com by default, and that endpoint requires a key. scanoss-py fell back to the free OSSKB.org service when you gave it no key. scanoss-cli doesn’t. See API keys and authentication.
  • You know which scripts read the scan output. scanoss-cli writes a different JSON format. Anything that parses scanoss-py results (jq filters, report generators, uploads) needs rewriting. See Output formats.
  • You know which scanoss-py commands you rely on. Some have no scanoss-cli equivalent, for example inspect and container-scan. See What has no equivalent.
  • You have a baseline. Save a recent scanoss-py result for each project you move, so you can compare it with the first scanoss-cli result. Some defaults changed, and they can change what matches.
  • Self-hosted only: you can run a second deployment. v3 can’t share a host with your v2 engine and LDB. Plan a separate host or container for v3. See Self-hosted: v2 to v3.

​
Next steps

From scanoss-py to scanoss-cli

Commands, flags, environment variables, output, and CI pipelines.

Self-hosted: v2 to v3

The crc64 knowledge base, engine 6, LDB 5, and the v3 API service.