> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Use

> Advanced features and configurations for power users, including settings files, HPSM, multi-threading, and obfuscation.

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 <a href="/en/latest/getting-started/declaring-components" target="_blank">scanoss.json</a>
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:

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

**Scan with settings:**

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# Skip files with a specific extension
scanoss-py scan --skip-extension .min.js -o results.json /path/to/project
```

### Skip by Folder

```bash theme={null}
# Skip a specific folder
scanoss-py scan --skip-folder node_modules -o results.json /path/to/project
```

### Skip by File Size

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# Scan specific files only
scanoss-py scan --files src/main.js -o results.json /path/to/project
```

### Trace Mode

```bash theme={null}
# Enable trace logging
scanoss-py scan --trace -o results.json /path/to/project
```

### Quiet Mode

```bash theme={null}
# 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:**

```bash theme={null}
scanoss-py scan --min-snippet-hits 5 -o results.json /path/to/project
```

**`scanoss.json`:**

```json theme={null}
{
  "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:**

```bash theme={null}
scanoss-py scan --min-snippet-lines 5 -o results.json /path/to/project
```

**`scanoss.json`:**

```json theme={null}
{
  "settings": {
    "file_snippet": {
      "min_snippet_lines": 5
    }
  }
}
```

### `ranking_enabled`

Controls whether the origin project's quality score is taken into account during
matching.

**CLI:**

```bash theme={null}
# 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`:**

```json theme={null}
{
  "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:**

```bash theme={null}
# 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`:**

```json theme={null}
{
  "settings": {
    "file_snippet": {
      "ranking_threshold": 5
    }
  }
}
```

### `honour_file_exts`

Controls whether file extensions are taken into account during matching.

**CLI:**

```bash theme={null}
# 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`:**

```json theme={null}
{
  "settings": {
    "file_snippet": {
      "honour_file_exts": false
    }
  }
}
```