Commands & Arguments - SCANOSS documentation

General Arguments

The following arguments are available on all commands:

Argument	Description
`--debug`, `-d`	Enable debug output
`--trace`, `-t`	Enable trace output, including full API request and response bodies
`--quiet`, `-q`	Suppress all non-error output

scan

Aliases: sc Fingerprints a directory or file and queries the SCANOSS Knowledge Base to identify open-source components, licences, vulnerabilities, and dependencies. Results are written to STDOUT by default.

scanoss-py scan [OPTIONS] <file or directory>

Argument	Description
`--wfp <file>`, `-w <file>`	Scan a pre-generated `.wfp` fingerprint file instead of a directory
`--dep <file>`, `-p <file>`	Scan a dependency file instead of a directory
`--stdin <filename>`, `-s <filename>`	Scan file contents from STDIN, using the given filename for identification
`--files <file> [<file>...]`, `-e`	Scan specific files
`--files-from <path>`, `-ff`	List of files to scan
`--identify <SBOM file>`, `-i <SBOM file>`	Identify components listed in an SBOM file (API key required)
`--ignore <SBOM file>`, `-n <SBOM file>`	Exclude components listed in an SBOM file from results (API key required)
`--output <file>`, `-o <file>`	Write results to a file (default: STDOUT)
`--format <format>`, `-f <format>`	Output format: `plain`, `cyclonedx`, `spdxlite`, `csv`, `raw` (default: `plain`)
`--flags <FLAGS>`, `-F <FLAGS>`	Send custom scanning flags to the API
`--threads <N>`, `-T <N>`	Number of concurrent upload threads (default: `5`, max: `30`)
`--skip-snippets`, `-S`	Skip snippet fingerprint generation
`--post-size <KB>`, `-P <KB>`	Maximum kilobytes per API request (default: `32`)
`--timeout <seconds>`, `-M <seconds>`	API request timeout in seconds (default: `180`)
`--retry <N>`, `-R <N>`	Number of retries on API failure (default: `5`; use `0` to fail immediately)
`--hpsm`, `-H`	Enable High Precision Snippet Matching
`--min-snippet-hits <N>`	Minimum snippet hits required for a match (`0` defers to server configuration)
`--min-snippet-lines <N>`	Minimum snippet lines required for a match (`0` defers to server configuration)
`--ranking <value>`	Enable or disable result ranking: `true`, `false`, or unset (default: unset, defers to server)
`--ranking-threshold <N>`	Ranking threshold from `-1` to `10` (default: `-1`, defers to server configuration)
`--honour-file-exts <value>`	Honour file extensions during matching: `true`, `false`, or unset (default: unset)
`--skip-headers`, `-skh`	Skip copyright notices, import statements, and comments at the start of each file
`--skip-headers-limit <N>`, `-shl <N>`	Maximum number of lines to skip when using `--skip-headers` (default: `0`)
`--wfp-output <file>`	Save computed fingerprints to a file during scanning
`--all-folders`	Include all folders (including those skipped by default)
`--all-extensions`	Include all file extensions (including those skipped by default)
`--all-hidden`	Include hidden files and folders
`--skip-extension <ext>`, `-E <ext>`	Exclude files with this extension (can be repeated)
`--skip-folder <folder>`, `-O <folder>`	Exclude this folder (can be repeated)
`--skip-size <bytes>`, `-Z <bytes>`	Exclude files smaller than the specified size in bytes (default: `0`)
`--skip-md5 <md5>`, `-5 <md5>`	Exclude files whose MD5 matches this hash (can be repeated)
`--strip-hpsm <fragment>`, `-G <fragment>`	Strip a specific HPSM code fragment before scanning (can be repeated)
`--strip-snippet <id>`, `-N <id>`	Strip a specific snippet ID before scanning (can be repeated)
`--obfuscate`	Obfuscate file paths in fingerprints before sending
`--dependencies`, `-D`	Include dependency scanning alongside file scanning
`--dependencies-only`	Run dependency scanning only, skipping file scanning
`--dep-scope <scope>`, `-ds <scope>`	Filter dependencies by scope: `dev` or `prod`
`--dep-scope-inc <scope>`, `-dsi <scope>`	Include only dependencies matching this scope
`--dep-scope-exc <scope>`, `-dse <scope>`	Exclude dependencies matching this scope
`--sc-command <cmd>`	Path or command name for Scancode (default: `scancode`)
`--sc-timeout <seconds>`	Timeout in seconds for Scancode to complete (default: `600`)
`--settings <file>`, `-st <file>`	Settings file path (default: `scanoss.json`). Cannot be combined with `--skip-settings-file`
`--skip-settings-file`, `-stf`	Ignore the default `scanoss.json` settings file. Cannot be combined with `--settings`
`--scan-root <path>`	Root directory for the scan. Settings file is looked up here first, and all paths are validated to stay within this root
`--apiurl <URL>`	SCANOSS API base URL (default: `https://api.osskb.org`)
`--key <token>`, `-k <token>`	SCANOSS API key (not required for the default API URL)
`--proxy <URL>`	Proxy URL. Also reads from the `HTTPS_PROXY` environment variable
`--pac <file/url>`	Proxy Auto-Config file, HTTP URL, or `auto` for system discovery
`--ca-cert <file>`	Custom CA certificate PEM file. Also reads from `REQUESTS_CA_BUNDLE` or `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH`
`--header <key:value>`, `-hdr <key:value>`	Add a custom HTTP request header (can be repeated)
`--ignore-cert-errors`	Disable SSL certificate verification (use only in trusted environments)

--dependencies and --dependencies-only require scancode-toolkit to be installed.

fingerprint

Aliases: fp, wfp Computes Winnowing fingerprints for a directory or file and writes them to a .wfp file or STDOUT. This step does not query the SCANOSS Knowledge Base, use scan for a full lookup.

scanoss-py fingerprint [OPTIONS] <file or directory>

Argument	Description
`--stdin <filename>`, `-s <filename>`	Read file contents from STDIN, using the given filename for identification
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--obfuscate`	Obfuscate file paths in fingerprints
`--hpsm`, `-H`	Enable High Precision Snippet Matching algorithm
`--skip-snippets`, `-S`	Skip snippet fingerprint generation
`--skip-headers`, `-skh`	Skip copyright notices, import statements, and comments at the start of each file
`--skip-headers-limit <N>`, `-shl <N>`	Maximum number of lines to skip when using `--skip-headers` (default: `0`)
`--all-extensions`	Include all file extensions
`--all-folders`	Include all folders
`--all-hidden`	Include hidden files and folders
`--skip-extension <ext>`, `-E <ext>`	Exclude files with this extension (can be repeated)
`--skip-folder <folder>`, `-O <folder>`	Exclude this folder (can be repeated)
`--skip-size <bytes>`, `-Z <bytes>`	Exclude files smaller than the specified size in bytes (default: `0`)
`--skip-md5 <md5>`, `-5 <md5>`	Exclude files whose MD5 matches this hash (can be repeated)
`--strip-hpsm <fragment>`, `-G <fragment>`	Strip a specific HPSM code fragment (can be repeated)
`--strip-snippet <id>`, `-N <id>`	Strip a specific snippet ID (can be repeated)
`--settings <file>`, `-st <file>`	Settings file path (default: `scanoss.json`). Cannot be combined with `--skip-settings-file`
`--skip-settings-file`, `-stf`	Ignore the default `scanoss.json` settings file. Cannot be combined with `--settings`
`--scan-root <path>`	Root directory for fingerprinting. Settings file is looked up here first, and all paths are validated to stay within this root

dependencies

Aliases: dp, dep Scans source code for declared dependencies without performing a Knowledge Base lookup.

scanoss-py dependencies [OPTIONS] <directory>

Requires scancode-toolkit.

Argument	Description
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--container <image:tag>`	Analyse dependencies from a Docker container image instead of a directory
`--sc-command <cmd>`	Path or command name for Scancode (default: `scancode`)
`--sc-timeout <seconds>`	Timeout in seconds for Scancode to complete (default: `600`)
`--syft-command <cmd>`	Path or command name for Syft (default: `syft`)
`--syft-timeout <seconds>`	Timeout in seconds for Syft to complete (default: `600`)
`--settings <file>`, `-st <file>`	Settings file path (default: `scanoss.json`). Cannot be combined with `--skip-settings-file`
`--skip-settings-file`, `-stf`	Ignore the default `scanoss.json` settings file. Cannot be combined with `--settings`
`--scan-root <path>`	Root directory for the scan. Settings file is looked up here first, and all paths are validated to stay within this root

file_count

Aliases: fc Walks the source tree and produces a summary of file types found.

scanoss-py file_count [OPTIONS] <directory>

Argument	Description
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--all-hidden`	Include hidden files and directories

convert

Aliases: cv, cnv, cvrt Converts a SCANOSS results file between supported output formats without re-scanning.

scanoss-py convert -i <input file> --format <format> -o <output file>

Argument	Description
`--input <file>`, `-i <file>`	Input results file
`--input-format <format>`	Input file format (default: `plain`)
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--format <format>`, `-f <format>`	Output format: `cyclonedx`, `spdxlite`, `csv`, `glc-codequality` (default: `spdxlite`)

folder-scan

Aliases: fs Scans a directory using folder-level hashing to identify components. Produces broader component matches than file-level scanning and is well-suited for detecting vendored or copied directories.

scanoss-py folder-scan [OPTIONS] <directory>

Argument	Description
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--format <format>`, `-f <format>`	Output format: `json`, `cyclonedx`, `raw` (default: `json`)
`--timeout <seconds>`, `-M <seconds>`	API request timeout in seconds (default: `600`)
`--rank-threshold <N>`	Only return results at or below this rank (lower rank = higher quality match; e.g. `3` returns ranks 1, 2, and 3)
`--depth <N>`	Directory traversal depth limit (default: `2`)
`--recursive-threshold <score>`	Score threshold for recursive scanning (default: `0.0`)
`--min-accepted-score <score>`	Minimum accepted match score (default: `0.0`)
`--settings <file>`, `-st <file>`	Settings file path (default: `scanoss.json`). Cannot be combined with `--skip-settings-file`
`--skip-settings-file`, `-stf`	Ignore the default `scanoss.json` settings file. Cannot be combined with `--settings`
`--scan-root <path>`	Root directory for the scan. Settings file is looked up here first, and all paths are validated to stay within this root
`--key <token>`, `-k <token>`	SCANOSS API key (not required for the default OSSKB URL)
`--proxy <URL>`	Proxy URL
`--pac <file/url>`	Proxy Auto-Config file, HTTP URL, or `auto`
`--ca-cert <file>`	Custom CA certificate PEM file
`--header <key:value>`, `-hdr <key:value>`	Add a custom HTTP request header (can be repeated)
`--ignore-cert-errors`	Disable SSL certificate verification (use only in trusted environments)

folder-hash

Aliases: fh Generates cryptographic hashes for all files in a directory tree and writes them to a JSON file or STDOUT. Use this to pre-compute folder hashes before running folder-scan.

scanoss-py folder-hash [OPTIONS] <directory>

Argument	Description
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--format <format>`, `-f <format>`	Output format: `json` (default: `json`)
`--depth <N>`	Directory traversal depth limit (default: `2`)
`--settings <file>`, `-st <file>`	Settings file path (default: `scanoss.json`). Cannot be combined with `--skip-settings-file`
`--skip-settings-file`, `-stf`	Ignore the default `scanoss.json` settings file. Cannot be combined with `--settings`
`--scan-root <path>`	Root directory for hashing. Settings file is looked up here first, and all paths are validated to stay within this root

container-scan

Aliases: cs Pulls a Docker container image and scans its layers for open-source dependencies. Requires Docker to be installed and running.

scanoss-py container-scan -i <image:tag> [OPTIONS]

Argument	Description
`--image <image:tag>`, `-i <image:tag>`	Docker image name and tag to scan (required)
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--format <format>`, `-f <format>`	Output format: `plain`, `cyclonedx`, `spdxlite`, `csv`, `raw` (default: `plain`)
`--timeout <seconds>`, `-M <seconds>`	API request timeout in seconds (default: `180`)
`--retry <N>`, `-R <N>`	Number of retries on API failure (default: `5`; use `0` to fail immediately)
`--apiurl <URL>`	SCANOSS API base URL (optional - default https://api.osskb.org)
`--key <token>`, `-k <token>`	SCANOSS API key (not required for the default OSSKB URL)
`--proxy <URL>`	Proxy URL
`--pac <file/url>`	Proxy Auto-Config file, HTTP URL, or `auto` for system discovery
`--ca-cert <file>`	Custom CA certificate PEM file
`--header <key:value>`, `-hdr <key:value>`	Add a custom HTTP request header (can be repeated)
`--ignore-cert-errors`	Disable SSL certificate verification (use only in trusted environments)
`--syft-command <cmd>`	Path or command name for Syft (default: `syft`)
`--syft-timeout <seconds>`	Timeout in seconds for Syft to complete (default: `600`)

crypto

Aliases: cr Retrieves cryptographic information for components identified by PURL. Requires a SCANOSS API key.

scanoss-py crypto <subcommand> [OPTIONS]

Subcommands

algorithms

Aliases: alg Returns the cryptographic algorithms used by the specified component versions.

scanoss-py crypto algorithms --purl <purl> [OPTIONS]

Argument	Description
`--with-range`	Include all versions within the specified version range that contain cryptographic algorithms

hints

Returns encryption hints for the specified component versions.

scanoss-py crypto hints --purl <purl> [OPTIONS]

Argument	Description
`--with-range`	Include all versions within the specified version range that contain encryption hints

versions-in-range

Aliases: vr Given a list of PURLs with version ranges, returns the subset of versions that do or do not contain cryptographic algorithms.

scanoss-py crypto versions-in-range --purl <purl_with_range> [OPTIONS]

Common Arguments

The following arguments apply to all crypto subcommands:

Argument	Description
`--purl <PURL>`, `-p <PURL>`	Package URL (PURL) to query. Can be specified multiple times
`--input <file>`, `-i <file>`	Input file containing a list of PURLs
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--timeout <seconds>`, `-M <seconds>`	API request timeout in seconds (default: `600`)
`--key <token>`, `-k <token>`	SCANOSS API key
`--proxy <URL>`	Proxy URL
`--pac <file/url>`	Proxy Auto-Config file, HTTP URL, or `auto` for system discovery
`--ca-cert <file>`	Custom CA certificate PEM file
`--header <key:value>`, `-hdr <key:value>`	Add a custom HTTP request header (can be repeated)
`--ignore-cert-errors`	Disable SSL certificate verification (use only in trusted environments)

component

Aliases: comp Queries the SCANOSS Knowledge Base for metadata about specific components identified by PURL. Requires a SCANOSS API key.

scanoss-py component <subcommand> [OPTIONS]

Subcommands

vulns

Returns known vulnerabilities for the specified component versions.

scanoss-py component vulns --purl <purl> [OPTIONS]

licenses

Returns the licences associated with the specified component versions.

scanoss-py component licenses --purl <purl> [OPTIONS]

semgrep

Returns Semgrep static analysis results for the specified component versions.

scanoss-py component semgrep --purl <purl> [OPTIONS]

versions

Returns the available versions for the specified component.

scanoss-py component versions --purl <purl> [OPTIONS]

Argument	Description
`--limit <N>`, `-l <N>`	Maximum number of versions to return

search

Searches the SCANOSS Knowledge Base for components matching a query.

scanoss-py component search [OPTIONS]

Argument	Description
`--search <query>`, `-s`	Generic search string
`--vendor <name>`, `-v`	Filter by vendor name
`--comp <name>`, `-c`	Filter by component name
`--package <name>`, `-p`	Filter by package name
`--limit <N>`, `-l <N>`	Maximum number of results to return
`--offset <N>`, `-f <N>`	Result offset for pagination

provenance

Aliases: prov Returns contributor provenance information for the specified component versions.

scanoss-py component provenance --purl <purl> [OPTIONS]

Argument	Description
`--origin`	Retrieve provenance using contributor origin data

status

Aliases: sts, st Returns the development lifecycle status for one or more components. Provides information including component status, repository status, first and last indexed dates, and version-specific details.

scanoss-py component status --purl <purl> [OPTIONS]

Common Arguments

The following arguments apply to all component subcommands:

Argument	Description
`--purl <PURL>`, `-p <PURL>`	Package URL (PURL) to query. Can be specified multiple times
`--input <file>`, `-i <file>`	Input file containing a list of PURLs
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--timeout <seconds>`, `-M <seconds>`	API request timeout in seconds (default: `600`)
`--apiurl <URL>`	SCANOSS API base URL (default: `https://api.osskb.org`)
`--key <token>`, `-k <token>`	SCANOSS API key
`--proxy <URL>`	Proxy URL
`--pac <file/url>`	Proxy Auto-Config file, HTTP URL, or `auto` for system discovery
`--ca-cert <file>`	Custom CA certificate PEM file
`--header <key:value>`, `-hdr <key:value>`	Add a custom HTTP request header (can be repeated)
`--ignore-cert-errors`	Disable SSL certificate verification (use only in trusted environments)

results

Reads a SCANOSS results file and filters or formats its contents.

scanoss-py results <file> [OPTIONS]

Argument	Description
`--match-type <type>`, `-mt <type>`	Filter results by match type
`--status <status>`, `-s <status>`	Filter results by status
`--has-pending`	Return only files that have pending declarations
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--format <format>`, `-f <format>`	Output format: `json`, `plain` (default: `json`)

inspect

Aliases: ins Policy-checking commands that analyse a SCANOSS results file for compliance issues such as copyleft licences, undeclared components, and more.

scanoss-py inspect <subcommand> [OPTIONS]

Subcommands

copyleft

Identifies files or components with copyleft licences in a results file.

scanoss-py inspect copyleft --input <file> [OPTIONS]

Argument	Description
`--include <licences>`	Additional licence identifiers to flag as copyleft (comma-separated)
`--exclude <licences>`	Licence identifiers to exclude from copyleft checks (comma-separated)
`--explicit <licences>`	Exact list of licences to use, replacing the built-in set (comma-separated)
`--license-sources <sources>`, `-ls`	Filter which licence detection sources to consider
`--status <file>`, `-s <file>`	Write a pass/fail status summary to this file

undeclared

Identifies components present in scan results that are not declared in the SBOM settings.

scanoss-py inspect undeclared --input <file> [OPTIONS]

Argument	Description
`--sbom-format <fmt>`	SBOM format to use for comparison: `legacy` or `settings` (default: `settings`)
`--status <file>`, `-s <file>`	Write a pass/fail status summary to this file

license-summary

Generates a licence summary from a results file.

scanoss-py inspect license-summary --input <file> [OPTIONS]

Argument	Description
`--include <licences>`	Additional licence identifiers to include (comma-separated)
`--exclude <licences>`	Licence identifiers to exclude (comma-separated)
`--explicit <licences>`	Exact list of licences to use, replacing the built-in set (comma-separated)

component-summary

Generates a component summary from a results file.

scanoss-py inspect component-summary --input <file> [OPTIONS]

dependency-track project-violations

Retrieves policy violations for a project from a Dependency-Track server.

scanoss-py inspect dependency-track project-violations [OPTIONS]

Argument	Description
`--url <URL>`	Dependency-Track server URL (required)
`--apikey <key>`, `-k <key>`	Dependency-Track API key (required)
`--project-id <uuid>`, `-pid <uuid>`	Project UUID
`--project-name <name>`, `-pn <name>`	Project name
`--project-version <ver>`, `-pv <ver>`	Project version
`--upload-token <token>`, `-ut <token>`	Upload token returned by a previous BOM upload
`--timeout <seconds>`, `-M <seconds>`	API request timeout in seconds (default: `300`)
`--status <file>`	Write a pass/fail status summary to this file

gitlab matches

Generates a GitLab-compatible match summary from a results file.

scanoss-py inspect gitlab matches --input <file> --line-range-prefix <url> [OPTIONS]

Argument	Description
`--line-range-prefix <url>`, `-lpr <url>`	GitLab repository URL prefix (required)

Common Arguments

The following arguments apply to all inspect subcommands:

Argument	Description
`--input <file>`, `-i <file>`	SCANOSS results file to analyse (required)
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)
`--format <format>`, `-f <format>`	Output format: `json`, `md`, `jira_md` (default: `json`)

export

Exports SCANOSS results to external platforms.

scanoss-py export <subcommand> [OPTIONS]

Subcommands

dt

Exports a CycloneDX SBOM to a Dependency-Track server.

scanoss-py export dt --input <file> --url <url> --apikey <key> [OPTIONS]

Argument	Description
`--input <file>`, `-i <file>`	CycloneDX SBOM file to upload (required)
`--url <URL>`	Dependency-Track server URL (required)
`--apikey <key>`, `-k <key>`	Dependency-Track API key (required)
`--project-id <uuid>`, `-pid <uuid>`	Project UUID
`--project-name <name>`, `-pn <name>`	Project name
`--project-version <ver>`, `-pv <ver>`	Project version
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)

delta

Aliases: dl Copies files identified in a diff report into a delta folder for further processing.

scanoss-py delta <subcommand> [OPTIONS]

Subcommands

copy

Copies changed files into a target delta folder based on a diff input file.

scanoss-py delta copy --input <file> [OPTIONS]

Argument	Description
`--input <file>`, `-i <file>`	Diff file listing changed files (required)
`--folder <path>`, `-fd <path>`	Destination delta folder
`--root <path>`, `-rd <path>`	Root directory for resolving relative file paths
`--output <file>`, `-o <file>`	Output file name (default: STDOUT)

utilities

Aliases: ut, utils A collection of network and certificate diagnostics utilities.

scanoss-py utilities <subcommand>

Subcommand	Description
`fast`	Verify that SCANOSS fast winnowing is active (requires the scanoss-winnowing package)
`certloc`, `cl`	Display the location of the Python CA certificate bundle
`cert-download`, `cdl`, `cert-dl`	Download the full SSL certificate chain from a remote server
`pac-proxy`, `pac`	Test a PAC (Proxy Auto-Config) file to determine the proxy for a given URL

The cert-download subcommand accepts the following arguments:

Argument	Description
`--hostname <host>`, `-n <host>`	Remote server hostname (required)
`--port <N>`, `-p <N>`	Remote server port (default: `443`)
`--output <file>`, `-o <file>`	Output PEM file name (default: STDOUT)

The pac-proxy subcommand accepts the following arguments:

Argument	Description
`--pac <value>`	PAC file path, HTTP URL, or `auto` for system discovery (default: `auto`)
`--url <URL>`	URL to test proxy resolution against (default: `https://api.osskb.org`)

​General Arguments

​scan

​fingerprint

​dependencies

​file_count

​convert

​folder-scan

​folder-hash

​container-scan

​crypto

​Subcommands

​algorithms

​hints

​versions-in-range

​Common Arguments

​component

​Subcommands

​vulns

​licenses

​semgrep

​versions

​search

​provenance

​status

​Common Arguments

​results

​inspect

​Subcommands

​copyleft

​undeclared

​license-summary

​component-summary

​dependency-track project-violations

​gitlab matches

​Common Arguments

​export

​Subcommands

​dt

​delta

​Subcommands

​copy

​utilities

General Arguments

scan

fingerprint

dependencies

file_count

convert

folder-scan

folder-hash

container-scan

crypto

Subcommands

algorithms

hints

versions-in-range

Common Arguments

component

Subcommands

vulns

licenses

semgrep

versions

search

provenance

status

Common Arguments

results

inspect

Subcommands

copyleft

undeclared

license-summary

component-summary

dependency-track project-violations

gitlab matches

Common Arguments

export

Subcommands

dt

delta

Subcommands

copy

utilities