SCANOSS-PY

A comprehensive Python library and CLI tool for Software Composition Analysis. CLI tool for Software Composition Analysis. Scan your code for open source components, dependencies and license compliance.

SCANOSS-PY provides a simple, easy-to-consume library for interacting with SCANOSS APIs and engines.

Prerequisites

Before you begin, make sure you have:

• Python 3.9 or higher

Installation

Standard Installation

Install SCANOSS-PY from PyPI:

# Install from PyPI
pip3 install scanoss

# Upgrade existing installation
pip3 install --upgrade scanoss

Fast Winnowing

Provides 15x performance improvement in fingerprinting.

# Install with fast winnowing support
pip3 install scanoss[fast_winnowing]

# Or install separately
pip3 install scanoss_winnowing

Dependency Scanning

To enable dependency detection from package manifests and lockfiles, install scancode-toolkit:

pip install scancode-toolkit

scancode-toolkit is only required if you want to use the -D or --dependencies flag for scanning declared dependencies. Standard file and snippet scanning does not require this dependency.

Installation on Externally Managed Environments

Modern Linux distributions (Ubuntu 23.04+, Fedora 38+, Debian 11+).

# Install pipx
sudo apt install pipx
pipx ensurepath

# Install scanoss-py
pipx install scanoss

# Upgrade existing installation
pipx upgrade scanoss

# Install scanoss-py with fast winnowing support
pipx install scanoss[fast_winnowing]

# Instal scancode-toolkit to scan for scanning declared dependencies
pipx install scancode-toolkit

Docker Installation

# Pull the latest Docker image
docker pull ghcr.io/scanoss/scanoss-py:latest

# Run the Python CLI
docker run -it ghcr.io/scanoss/scanoss-py

# Scan current folder
docker run -it -v "$(pwd)":"/scanoss" ghcr.io/scanoss/scanoss-py scan .

# Scan with output file
docker run -it -v "$(pwd)":"/scanoss" ghcr.io/scanoss/scanoss-py scan -o results.json .

# Scan with dependencies
docker run -it -v "$(pwd)":"/scanoss" ghcr.io/scanoss/scanoss-py scan -D -o results.json .

# Redirect output to file
docker run -i -v "$(pwd)":"/scanoss" ghcr.io/scanoss/scanoss-py scan . > output.json

# Use scancode for license and dependency detection
docker run -it -v "$(pwd)":"/scanoss" --entrypoint scancode ghcr.io/scanoss/scanoss-py --json-pp /scanoss/results.json -l -p .

Configuration

API Access Setup

While SCANOSS works without an API key, the free tier has usage limitations. To avoid hitting these limits, configure your API key before scanning.

Set API Key via Environment Variables:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export SCANOSS_API_KEY=your_api_key_here' >> ~/.bashrc
source ~/.bashrc

scanoss-py automatically detects the SCANOSS_API_KEY environment variable when set.

You can also pass the API key directly with --key $SCANOSS_API_KEY when running the tool.

Getting Started

Basic Scanning

# Scan a directory
scanoss-py scan -o results.json /path/to/folder

# Scan with dependency detection
scanoss-py scan -D -o results.json /path/to/folder

# Scan with specific settings
scanoss-py scan -D --settings scanoss.json -o results.json /path/to/folder

Scanning with Snippet Tuning

SCANOSS-PY exposes snippet tuning parameters via CLI flags that let you control match sensitivity directly from the command line.

Reduce False Positives:

# Require higher confidence matches
scanoss-py scan \
  --min-snippet-hits 5 \
  --min-snippet-lines 3 \
  --ranking-threshold=5 \
  -o results.json /path/to/folder

How Snippet Tuning Works

When you use these settings, scanoss-py:

1. Reads your scanoss.json (if present)
2. Reads CLI arguments (used as fallback only)
3. Merges both sources — scanoss.json takes precedence over CLI
4. Encodes the merged settings
5. Sends to the SCANOSS API
6. Server applies tuning during the scan

For more details on configuring these parameters in scanoss.json, see the SCANOSS Settings documentation.

Viewing results

# View raw results
cat results.json

# Inspect undeclared components
scanoss-py inspect undeclared -i results.json

# Check for copyleft licenses
scanoss-py inspect copyleft -i results.json

# Generate component summary
scanoss-py inspect component-summary -i results.json --output components.json