Skip to main content

​
Goal

Scan code that lives on a machine that cannot reach the internet, or that policy does not allow to send anything out. You split the work in two:
  1. On the restricted machine, generate fingerprints. This step needs no network access and no API key.
  2. On a connected machine, scan the fingerprint file. The source code never leaves the restricted side.

​
When to use it

  • Your build systems run in an isolated network.
  • Your code is under an export, defence, or customer restriction that does not allow a direct connection to an external service.
  • A third party audits your code by scanning your fingerprints, without receiving your source code.
If the restricted network can reach your own SCANOSS deployment instead, you do not need this split. Point scanoss-cli at that deployment with a custom API URL. See Use a custom API URL.

​
What a fingerprint file contains

A WFP file contains, for each file:
  • a hash of the whole file, its size, and its path relative to the scanned directory
  • hashes of overlapping fragments of the file, used to find snippet matches
It does not contain the source code. It does contain your file paths, so if paths are sensitive, review the file before it leaves the restricted side.

​
Prerequisites

  • scanoss-cli on both machines, at the same version (see Quickstart)
  • SCANOSS_API_KEY on the connected machine only
  • An approved way to move one file from the restricted machine to the connected one

​
Step 1: Fingerprint on the restricted machine

Leave out --settings scanoss.json if the project has no scanoss.json. When it is present, its skip rules decide which files scanoss-cli fingerprints. wfp accepts the same file selection flags as scan: --threads, --min-size, --max-size, --gitignore, --all-extensions, --all-folders, --all-hidden, --skip-headers, and --skip-headers-limit. Its output is byte-for-byte reproducible. The same tree and flags give the same file, so you can hash it, diff it, and store it as evidence.
--skip-headers changes the fingerprints. Fingerprints made with it on do not match fingerprints made with it off, so use the same setting every time you fingerprint the same project.

​
Step 2: Move the file

Transfer project.wfp and project.wfp.sha256 with your approved process. On the connected machine, check that the file arrived unchanged:

​
Step 3: Scan the fingerprints on the connected machine

scan wfp uploads the file as it is, waits for the result, and writes the same raw inventory as a normal scan. It accepts the scan flags: --format, --include, --settings, --identify, --ignore, --ranking-threshold, --chunk-size, and --poll-interval. Copy the project’s scanoss.json to the connected machine if you use one. scanoss-cli applies its BOM rules (approved and ignored components) on this side, after the results come back. They match on the file paths stored in the fingerprints. scanoss-cli prints the scan ID when the upload finishes. If the connection drops while you wait, resume with:

​
Step 4: Use the result

The result is a normal scanoss-cli raw inventory, so every other recipe applies to it:
See Approve components with scanoss.json, the licence and vulnerability gate, and Generate an SBOM for each release.

​
What you give up

To include declared dependencies, move the manifest files (for example package.json, package-lock.json, or go.mod) to the connected machine too, if your policy allows it, and run scanoss-cli dependencies <dir> --extract-local --output deps.json on that copy.

​
How it fails the pipeline

As with every scanoss-cli command, scan wfp exits 0 after a successful scan whatever it finds. The gates in step 4 turn findings into a failure.