Scanning your project

Scanning

scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY"
scanoss-cli scan ./src/main.go --api-key "$SCANOSS_API_KEY"
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --output results.json

scan fingerprints the target, uploads the WFP in blocks to POST /v3/wfp/scan, and polls GET /v3/wfp/scan/<scan-id> until the scan completes. It prints the scan id as soon as the upload finishes, so you can resume an interrupted scan with results.

Tuning throughput

scanoss-cli scan ./my-project \
  --api-key "$SCANOSS_API_KEY" \
  --threads 20 \
  --chunk-size 2097152          # 2 MiB upload blocks (default 1 MiB)

Keeping the generated WFP

scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --save-wfp project.wfp

The CLI writes the copy as the scan generates it, in completion order, and that order varies between runs. Use the standalone wfp command when you need byte-reproducible output to diff or hash.

Scanning a pre-generated WFP

scanoss-cli scan wfp project.wfp --api-key "$SCANOSS_API_KEY"

Resuming a scan

scanoss-cli results <scan-id> --api-key "$SCANOSS_API_KEY" --output results.json

results works after a Ctrl+C because the uploaded WFP is resumable. A resumed scan applies the same rules as a direct one, so results accepts --settings, -i/-n, --ranking-threshold, --include (vulns, licenses, crypto, geo), -f, --format and --poll-interval, plus the API flags.

Flags reference

The API flags work on every command that reaches the API: scan, scan wfp, results, enrich, dependencies, and the decoration commands.

Flag	Default	Notes
`--api-url`	`https://api.scanoss.com`	Default endpoint requires `--api-key`
`--api-key`	—
`--proxy`	—	Overrides `HTTP_PROXY`/`HTTPS_PROXY`. See Configuration
`--ca-cert`	—	PEM file added to the system trust pool
`--ignore-cert-errors`	`false`	Disables TLS verification (insecure)
`-o, --output`	stdout

scan and scan wfp share the scan flags.

Flag	Default	Notes
`-f, --format`	`raw`	`raw` / `spdx` / `cyclonedx`
`--include`	—	Extra output layers. See Output layers. `scan wfp` accepts all except `deps`
`--settings`	auto-detected `scanoss.json`
`--chunk-size`	`1048576` (1 MiB)	WFP upload block size, bytes
`--poll-interval`	`2s`	Scan status poll cadence
`-i, --identify <file>`, `-n, --ignore <file>`	—	A component list, CycloneDX, SPDX, or raw result file. See BOM rules
`--ranking-threshold`	`-1` (off)	`-1`..`10`; `-1` and `0` both mean off

The fingerprinting flags work only on scan <path> and the standalone wfp command. scan wfp receives a WFP that is already assembled, so it doesn’t accept them, and passing --skip-headers or --skip-headers-limit to it is an error.

Flag	Default	Notes
`-t, --threads`	`10`	Fingerprint workers
`--save-wfp`	—	Keep the generated WFP alongside the scan (`scan` only)
`--min-size` / `--max-size`	`0` / `0`	Bytes. `0` max means unlimited
`--gitignore`	`true`
`--all-extensions`, `--all-folders`, `--all-hidden`	`false`	See Skipping files
`--skip-headers`	`true`	Drops each file’s leading licence header, comments and imports from its fingerprint
`--skip-headers-limit`	`0` (no limit)

--skip-headers changes the fingerprint. A WFP taken with it off won’t match one taken with it on, so keep the setting consistent across runs you intend to compare.

Fingerprinting only

wfp generates fingerprints without contacting the API, so it needs no key:

scanoss-cli wfp ./my-project > project.wfp
scanoss-cli wfp ./src/main.go -o main.wfp
scanoss-cli wfp ./my-project --threads 20 --min-size 100

It accepts the fingerprinting flags above plus -o, --output and --settings. Unlike scan --save-wfp, its output is byte-reproducible, so use it when you need to diff or hash a WFP.

Skipping files

Before scanning, the CLI filters out build directories, vendored dependencies, generated and binary files, model weights (.safetensors, .gguf, .onnx, .pt, .bin), and oversized files. There is no minimum file size by default. Set one with --min-size:

# Skip files below 100 bytes
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --min-size 100

# Keep files between 100 bytes and 1 MiB
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --min-size 100 --max-size 1048576

# Fingerprint everything the built-in lists would drop, and ignore .gitignore
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" \
  --all-extensions --all-folders --gitignore=false

--all-extensions turns off the built-in file rules, which match extensions, name endings, and exact names. --all-folders turns off the directory rules. They are separate switches because someone who wants every folder scanned rarely wants every binary fingerprinted too. --all-hidden includes dotted entries, .git among them. To set skip rules for the whole project, use scanoss.json:

{
  "settings": {
    "skip": {
      "patterns": { "scanning": ["dist/**", "**/*.min.js", "docs/"] },
      "sizes": { "scanning": [{ "patterns": ["*.bin"], "min": 0, "max": 1048576 }] }
    }
  }
}

You can use the flags and scanoss.json together. --min-size and --max-size apply to every file, while a skip.sizes rule applies only to the files its patterns match.

BOM rules

Configure a Bill of Materials in scanoss.json. The CLI finds the file in the target automatically, or you can pass its path with --settings:

{
  "bom": {
    "include": [{ "purl": "pkg:github/scanoss/engine" }],
    "remove": [{ "purl": "pkg:github/scanoss/scanoss" }],
    "replace": [{ "purl": "pkg:github/wrong/lib", "replace_with": "pkg:github/right/lib@2.1.0" }]
  }
}

scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --settings my-config.json

The CLI applies every rule on the client side, after results come back, in this order:

bom.ignore (alias bom.exclude) drops the components it names from each file’s matches.
bom.identify (alias bom.include) marks the components it names as "identified": true and moves them to the front of their file’s matches.
--ranking-threshold drops matches whose component ranks worse than the threshold.
bom.remove neutralizes whole files.
bom.replace re-points the survivors at their replace_with component.

Details that change results:

Scoping. An entry may be scoped by purl, by path, or both. Where several entries cover the same file, the most specific one wins:
{ "bom": { "identify": [{ "purl": "pkg:npm/vue@2.6.14", "path": "vendor/vue/" }] } }
Canonical PURLs only. bom.ignore and bom.identify match a component’s canonical PURL, not its aliases. bom.remove and bom.replace do match aliases.
bom.identify wins. It protects its PURLs from every filter in this list: bom.ignore, bom.remove, and the ranking threshold.
Ranking threshold. Rank is how well a component explains a match; lower is stronger, and real ranks run from 1 to 9. Matches with no rank, or the engine’s 999 “no ranking information” sentinel, are never filtered.
Where identified shows up. The CLI writes the flag on each matched file’s evidence, and on the component as a summary, because a path-scoped rule claims a component only in the files it covers. CycloneDX output carries the component-level flag as a scanoss:identified property. Only raw output has the per-file detail.

-i, --identify <file> and -n, --ignore <file> on the command line add unscoped entries to the same rules, and you can combine them with --settings. Each takes a file, which can be a SCANOSS component list ({"components":[{"purl":"..."}]}), CycloneDX, SPDX, or this CLI’s own raw output. The CLI detects the type from the content.

Snippet settings in scanoss.json

scanoss.json can also carry fingerprinting and filtering settings:

{
  "settings": {
    "file_snippet": {
      "skip_headers": true,
      "skip_headers_limit": 50,
      "ranking_threshold": 5
    }
  }
}

These keys override the --skip-headers, --skip-headers-limit and --ranking-threshold flags. That is the reverse of every other setting in this CLI. SCANOSS-PY behaves the same way, so both clients read one settings file identically. If a flag seems to have no effect, check for the key in scanoss.json and remove it to let the flag win.

ranking_threshold accepts values from -1 to 10, where -1 and 0 both mean off. The CLI clamps out-of-range values and prints a warning. Other file_snippet keys, such as min_snippet_hits, ranking_enabled, and honour_file_exts, tune the matching engine. This CLI ignores them because it doesn’t forward scan settings to the server.

Output layers

By default a scan reports only the components it detected. --include adds extra layers, which cover both detected and declared components:

Layer	What it adds
`deps`	Declared dependencies parsed from the project’s manifests and resolved. Needs a source tree, so `scan wfp` rejects it with an error.
`vulns`	Known vulnerabilities.
`licenses`	Declared/concluded licences per component.
`crypto`	Cryptographic algorithms.
`geo`	Contributor geographic provenance.

scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --include deps,vulns,licenses

If the chosen --format can’t represent a layer, the CLI doesn’t gather that layer and prints a message up front. raw renders every layer, cyclonedx drops crypto and geo, and spdx drops vulns, crypto, and geo.

Get started

Recipes

CLI reference

API reference

Self-hosting & knowledge base

Scanning

Tuning throughput

Keeping the generated WFP

Scanning a pre-generated WFP

Resuming a scan

Flags reference

Fingerprinting only

Skipping files

BOM rules

Snippet settings in scanoss.json

Output layers

​Scanning

​Tuning throughput

​Keeping the generated WFP

​Scanning a pre-generated WFP

​Resuming a scan

​Flags reference

​Fingerprinting only

​Skipping files

​BOM rules

​Snippet settings in scanoss.json

​Output layers

Scanning

Tuning throughput

Keeping the generated WFP

Scanning a pre-generated WFP

Resuming a scan

Flags reference

Fingerprinting only

Skipping files

BOM rules

Snippet settings in scanoss.json

Output layers