Self-hosted: v2 to v3

This page is for customers who run SCANOSS in their own infrastructure on v2 and want to offer the v3 API to their users. v3 covers both scanning and decoration (licences, vulnerabilities, cryptography, dependencies, geoprovenance, copyright, and components). There is no installer for v3 yet. This page lists the manual steps. Your v2 deployment keeps working for now, so you can build v3 next to it, test it, and move clients over when you’re ready. For the bigger picture, see Migrating to v3.

What changes

	v2 (today)	v3
API service	`scanoss-go-api`, with endpoints such as `/scan/direct`	`scanoss-services-api`, one service with every endpoint under `/v3`
Scan engine	Engine 5.x	Engine 6.x (`-crc64` releases)
LDB library	LDB 4.x	LDB 5.x (`-crc64` releases)
Knowledge base	The current KB line	The crc64 KB line, delivered over the same SFTP access
Decoration data	Read from the KB by the engine	A separate serving database, delivered as DuckDB files
File contents	Served from your KB	Not served from the self-hosted KB. The crc64 KB has no `sources` table.
Clients	`scanoss-py`, SCANOSS integrations	`scanoss-cli`

Engine 6 and LDB 5 can’t share a host with engine 5 and LDB 4. The two lines are not interchangeable in either direction: a crc64-line engine needs a crc64-line LDB, and an older engine can’t read crc64-line tables. The engine refuses to start on a mismatch. Build v3 on a separate host and keep v2 where it is. See SCANOSS LDB.

Prerequisites

A separate Linux x86-64 host for v3. The scanoss-services-api binary needs glibc 2.36 or later, so use Debian 12 or later, or another distribution with glibc 2.36+.
libgcrypt and zlib, for example apt install libgcrypt20 zlib1g on Debian.
At least 7.5 TB of SSD for the crc64 KB. The full KB is about 7.2 TB today and grows by about 400 GB a month, so plan room for the updates you’ll import.
64 GB of RAM and 16 to 20 CPU threads as a starting point. That is what SCANOSS runs on its own crc64 scan nodes. The services themselves use little memory: most of the RAM works as the operating system’s page cache for the KB, and more cache means faster scans.
Your SFTP credentials, the same ones you use for v2 KB downloads.
Outbound HTTPS to api.osv.dev, if you turn on the OSV vulnerability source in the API service’s config.
An API key for scanoss-cli is not needed when you point it at your own deployment. A custom API URL may run without a key.

Set up v3

Download the crc64 knowledge base

The crc64 KB is in your SFTP account under kb/crc64/, next to the v2 KB you download today:

Folder	What it holds
`kb/crc64/full/<YY.MM>/`	The full crc64 KB for a release.
`kb/crc64/update/<version>/`	Incremental updates.
`kb/duckdb/<YY.MM>/`	The decoration data, as DuckDB files.

The kb-download.sh script from the on-premise repository downloads all three. Its default is still the v2 KB, so always pass one of the crc64 modes with -m. See the script’s documentation for every option.

# Full crc64 KB. -o is where the 'oss' folder goes. Keep it apart from your v2 KB.
./kb-download.sh -m crc64_full -o /var/lib/ldb/oss

# A crc64 update (latest by default, or pick one with -V <version>)
./kb-download.sh -m crc64_update

# Decoration data
./kb-download.sh -m duckdb

Never point -o at a folder that holds a v2 KB: the tables have the same names. The crc64 KB and the DuckDB files are not part of every subscription. Without access, the script stops and asks you to contact SCANOSS support.The script asks for your SFTP host, port, user, and password unless you pass them. If you download with your own SFTP client instead, only take a full release folder that contains the COMPLETE file. A folder without it is still being published.Check every file after the download. Each entry has a checksum manifest: from release 26.10, a SHA-256 file under sha256sum/, and before that an MD5 file under md5sum/. Each DuckDB file comes with a .sha256 file next to it.

Install LDB 5 and engine 6

Install the crc64 line of LDB first, then the engine. Their releases carry a -crc64 suffix, for example v5.0.0-crc64 for LDB and v6.0.0-crc64 for the engine. Debian packages are on the LDB releases and engine releases pages.Put the oss folder of the full KB where the engine reads it, /var/lib/ldb/oss, as in v2. Then check that both binaries report the crc64 line:

ldb -v
scanoss -v

Install and configure the API service

scanoss-services-api is one Linux x86-64 binary. It links the system libldb.so from LDB 5. Download the release from your SCANOSS SFTP account, with the same credentials you use for the KB.Copy the binary onto your PATH, and check it:

sudo install -m 0755 scanoss-services-api /usr/local/bin/
scanoss-services-api -version

Then write a config file. This is a minimal one for a node that does both scanning and decoration:

server:
  host: "0.0.0.0"
  port: 9001                     # the default port

# Scanning. The /v3 scan endpoints exist only when engine_path is set.
scan:
  engine_path: /usr/bin/scanoss  # the engine 6 binary; it reads the KB in /var/lib/ldb
  timeout: 120s                  # per synchronous request
  batch:                         # chunked uploads from scanoss-cli
    max_total_size: 268435456    # largest fingerprint file one scan may upload (256 MiB)
    session_ttl: 1h              # how long a scan and its result are kept after last use
    workers: 2                   # scans that run at the same time

# Decoration. Point this at the DuckDB serving file from kb/duckdb/<YY.MM>/.
serving_db:
  driver: duckdb                 # sqlite | postgres | duckdb | none
  path: /var/lib/scanoss/serving/current.duckdb

# Vulnerability sources. At least one must be enabled.
vulnerabilities:
  osv:
    enabled: true                # needs outbound HTTPS to api.osv.dev
    api_base_url:  "https://api.osv.dev/v1"
    info_base_url: "https://osv.dev/vulnerability"
    api_workers:   5
  scanoss:
    enabled: true
    max_workers: 5

A few things to know about the config:

Scan-only or decoration-only nodes. Leave out serving_db for a node that only scans. Leave out scan.engine_path for a node that only decorates.
Candidates per match. scan.batch.pipeline.max_components sets how many candidate components a full-file match reports when the client doesn’t ask. A client can override it for one scan with scanoss-cli scan --max-components N or --max-components all.
DuckDB files. Point serving_db.path at a symlink to the file, not at the file. To switch to a new month’s file, change the symlink and send the process SIGHUP. The service checks the new file, switches to it, and keeps the old one if the new one fails its checks.
File contents. The crc64 KB has no sources table, so /v3/file-contents isn’t served from your KB. Evidence links in licence and copyright results point at the public SCANOSS URLs by default.

Start the service with the config file:

scanoss-services-api --config /etc/scanoss/config.yaml

To run it under systemd, a minimal unit looks like this:

[Unit]
Description=SCANOSS Services API (v3)
After=network-online.target

[Service]
ExecStart=/usr/local/bin/scanoss-services-api --config /etc/scanoss/config.yaml
ExecReload=/bin/kill -HUP $MAINPID
Restart=always

[Install]
WantedBy=multi-user.target

Put it behind your proxy or load balancer

Authentication. scanoss-services-api has no authentication of its own. Don’t expose it directly. Put it behind your own reverse proxy and network controls. The service can also require client certificates (mutual TLS) with server.tls.client_ca_file.
TLS. The service listens on plain HTTP by default. Terminate TLS at your proxy, or turn on server.tls in the config.
More than one node. A scanoss-cli scan uploads in several blocks and then polls for the result. The service keeps each scan in its own memory and local disk, so every request for one scan must reach the same node. Route by the scan ID: the X-Scan-Id header on uploads to /v3/wfp/scan, and the ID in the path of GET /v3/wfp/scan/{id}. With one node, you don’t need this.
Upload size. Allow request bodies of at least the upload block size. scanoss-cli sends 1 MiB blocks by default.

Validate

Check that the service is up and that its dependencies are ready:

curl -sS http://<host>:9001/v3/health          # {"status":"ok"}
curl -sS http://<host>:9001/v3/health/ready    # 200 and "status": "ok" when ready

/v3/health/ready answers 503 with "status": "not_ready" when a critical dependency, such as the serving database, is unavailable. The service also serves its API reference at /v3/docs/.Then scan something you know, and decorate it:

scanoss-cli scan ./known-project \
  --api-url http://<host>:9001 \
  --include licenses,vulns \
  --output v3-results.json

jq -r '.components[] | select(.scope == "detected") | .purl' v3-results.json

Compare the components with a v2 scan of the same code. Expect some differences. See Behaviour changes that alter results.

Point clients at v3

Set the API URL on each client that moves to v3:

# One machine
scanoss-cli config set api-url https://scanoss.example.com

# CI jobs
export SCANOSS_API_URL=https://scanoss.example.com

Use the base URL only. scanoss-cli adds the /v3 paths. See From scanoss-py to scanoss-cli for the rest of the client changes.

Keep v2 running

Leave your v2 deployment in place. Clients that stay on scanoss-py, and the SCANOSS integrations, need it: they can’t talk to v3. If something goes wrong on v3, point the moved clients back at v2. Nothing on the v2 host changes, so that is your rollback.

Keep v3 up to date

KB updates. SCANOSS publishes crc64 KB updates on the same cadence as v2, under kb/crc64/update/<version>/ in your SFTP account. Download them with kb-download.sh -m crc64_update and import them as described in the KB update guide, using the crc64 folder instead of the v2 one. Check each download against its checksum manifest.
Decoration data. Each release has new DuckDB files under kb/duckdb/<YY.MM>/. Download the new file, check it against its .sha256 file, point the serving_db.path symlink at it, and reload the service (systemctl reload with the unit above, or kill -HUP).
Engine and LDB. Upgrade them together and stay on the crc64 line. Check ldb -v and scanoss -v after every upgrade.
The API service. Keep the previous binary until the new one passes /v3/health/ready, so you can switch back.

Get started

Migrating to v3

Recipes

CLI reference

API reference

Self-hosting & knowledge base

What changes

Prerequisites

Set up v3

Keep v3 up to date

​What changes

​Prerequisites

​Set up v3

​Keep v3 up to date

What changes

Prerequisites

Set up v3

Keep v3 up to date