Advanced Use

This guide covers advanced SCANOSS-PY features for power users who need fine-grained control over scanning, performance optimisation, and custom workflows.

Settings File (`scanoss.json`)

The scanoss.json settings file provides declarative configuration for project scanning, Bill of Materials (BOM) management, and file filtering.

Quick Start

Create scanoss.json in your project root:

{
  "self": {
    "name": "my-project",
    "license": "MIT",
    "description": "Project description"
  },
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["node_modules/", "dist/", "build/"],
        "dependencies": ["vendor/**", "third_party/"]
      }
    }
  }
}

Scan with settings:

# Automatically uses scanoss.json if present
scanoss-py scan -o results.json /path/to/project

# Specify a custom settings file
scanoss-py scan --settings custom-settings.json -o results.json /path/to/project

# Skip the settings file
scanoss-py scan --skip-settings-file -o results.json /path/to/project

High Precision Snippet Matching (HPSM)

HPSM is an alternative scanning mode that increases the precision of snippet detection by applying stricter matching criteria. Use it when you need to reduce false positives in snippet results.

Enable HPSM

# Enable HPSM mode
scanoss-py scan --hpsm -o results.json /path/to/project

# With fingerprinting
scanoss-py fingerprint --hpsm -o fingerprints.wfp /path/to/project

Header Filtering

Skip detected licence headers, comments, and import blocks at the beginning of files to prevent them from influencing snippet matching results.

Basic Header Filtering

# Skip headers (automatic detection)
scanoss-py scan --skip-headers -o results.json /path/to/project

# With fingerprinting
scanoss-py fingerprint --skip-headers -o fingerprints.wfp /path/to/project

Limit Header Lines

Control the maximum number of lines to skip from the beginning of each file:

# Skip up to 50 header lines
scanoss-py scan --skip-headers --skip-headers-limit 50 -o results.json /path/to/project

Fingerprint Obfuscation

Obfuscate fingerprints before submission to the SCANOSS API, for privacy or security purposes:

# Obfuscate fingerprints during scanning
scanoss-py scan --obfuscate -o results.json /path/to/project

# Obfuscate during fingerprinting
scanoss-py fingerprint --obfuscate -o fingerprints.wfp /path/to/project

Advanced File Filtering

Skip by Extension

# Skip files with a specific extension
scanoss-py scan --skip-extension .min.js -o results.json /path/to/project

Skip by Folder

# Skip a specific folder
scanoss-py scan --skip-folder node_modules -o results.json /path/to/project

Skip by File Size

# Skip files smaller than 1,024 bytes (1 KB)
scanoss-py scan --skip-size 1024 -o results.json /path/to/project

Include All Files

Override default exclusions:

# Include all file extensions
scanoss-py scan --all-extensions -o results.json /path/to/project

# Include all folders (including .git and node_modules)
scanoss-py scan --all-folders -o results.json /path/to/project

# Include all hidden files
scanoss-py scan --all-hidden -o results.json /path/to/project

Scan Specific Files

# Scan specific files only
scanoss-py scan --files src/main.js -o results.json /path/to/project

Trace Mode

# Enable trace logging
scanoss-py scan --trace -o results.json /path/to/project

Quiet Mode

# Suppress all output except errors
scanoss-py scan --quiet -o results.json /path/to/project

Snippet Tuning

Snippet tuning allows you to configure detection thresholds and matching behaviour to suit your project’s requirements. The parameters below control how many snippet matches are required and how results are ranked before being reported.

When to Use CLI vs `scanoss.json`

Use CLI parameters when:

Testing different configurations
Running one-off scans with specific requirements
Overriding baseline settings for a particular scan
Running automated scans with varying sensitivity levels

Use scanoss.json when:

Establishing baseline scanning behaviour for your project
Ensuring consistent scans across all team members
Defining project-wide detection policies
Version-controlling your scanning configuration

Parameter Reference

`min_snippet_hits`

Sets the minimum number of snippet matches required before reporting a match. CLI:

scanoss-py scan --min-snippet-hits 5 -o results.json /path/to/project

scanoss.json:

{
  "settings": {
    "file_snippet": {
      "min_snippet_hits": 5
    }
  }
}

`min_snippet_lines`

Sets the minimum number of lines a code snippet must span to be considered a match. CLI:

scanoss-py scan --min-snippet-lines 5 -o results.json /path/to/project

scanoss.json:

{
  "settings": {
    "file_snippet": {
      "min_snippet_lines": 5
    }
  }
}

`ranking_enabled`

Controls whether the origin project’s quality score is taken into account during matching. CLI:

# Enable ranking
scanoss-py scan --ranking true -o results.json /path/to/project

# Disable ranking
scanoss-py scan --ranking false -o results.json /path/to/project

scanoss.json:

{
  "settings": {
    "file_snippet": {
      "ranking_enabled": true
    }
  }
}

`ranking_threshold`

Sets the minimum ranking score required for matches to be reported. Accepts an integer from 0 (lowest) to 10 (highest confidence). Use -1 to apply the server default. CLI:

# High confidence matches only
scanoss-py scan --ranking true --ranking-threshold=10 -o results.json /path/to/project

# Use server default
scanoss-py scan --ranking true --ranking-threshold=-1 -o results.json /path/to/project

scanoss.json:

{
  "settings": {
    "file_snippet": {
      "ranking_enabled": true,
      "ranking_threshold": 5
    }
  }
}

`honour_file_exts`

Controls whether file extensions are taken into account during matching. CLI:

# Consider file extensions (default)
scanoss-py scan --honour-file-exts true -o results.json /path/to/project

# Ignore file extensions
scanoss-py scan --honour-file-exts false -o results.json /path/to/project

scanoss.json:

{
  "settings": {
    "file_snippet": {
      "honour_file_exts": false
    }
  }
}

Documentation

Links

Settings File (`scanoss.json`)

Quick Start

High Precision Snippet Matching (HPSM)

Enable HPSM

Header Filtering

Basic Header Filtering

Limit Header Lines

Fingerprint Obfuscation

Advanced File Filtering

Skip by Extension

Skip by Folder

Skip by File Size

Include All Files

Scan Specific Files

Trace Mode

Quiet Mode

Snippet Tuning

When to Use CLI vs `scanoss.json`

Parameter Reference

`min_snippet_hits`

`min_snippet_lines`

`ranking_enabled`

`ranking_threshold`

`honour_file_exts`

​Settings File (scanoss.json)

​Quick Start

​High Precision Snippet Matching (HPSM)

​Enable HPSM

​Header Filtering

​Basic Header Filtering

​Limit Header Lines

​Fingerprint Obfuscation

​Advanced File Filtering

​Skip by Extension

​Skip by Folder

​Skip by File Size

​Include All Files

​Scan Specific Files

​Trace Mode

​Quiet Mode

​Snippet Tuning

​When to Use CLI vs scanoss.json

​Parameter Reference

​min_snippet_hits

​min_snippet_lines

​ranking_enabled

​ranking_threshold

​honour_file_exts

Settings File (`scanoss.json`)

Quick Start

High Precision Snippet Matching (HPSM)

Enable HPSM

Header Filtering

Basic Header Filtering

Limit Header Lines

Fingerprint Obfuscation

Advanced File Filtering

Skip by Extension

Skip by Folder

Skip by File Size

Include All Files

Scan Specific Files

Trace Mode

Quiet Mode

Snippet Tuning

When to Use CLI vs `scanoss.json`

Parameter Reference

`min_snippet_hits`

`min_snippet_lines`

`ranking_enabled`

`ranking_threshold`

`honour_file_exts`