Skip to main content
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/"]
      }
    }
  }
}
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-threshold=10 -o results.json /path/to/project

# Use server default
scanoss-py scan --ranking-threshold=-1 -o results.json /path/to/project
scanoss.json: 
{
  "settings": {
    "file_snippet": {
      "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
    }
  }
}