Skip to main content
The SCANOSS.JSON file contains project information and BOM (Bill of Materials) rules. It allows you to include, remove or replace components in the BOM before and after scanning.

​
What Can You Do With It?

The settings file lets you:
  • Define Your Scope Control exactly which files get scanned and which don’t, saving time and processing power.
  • Set Scanning Depth Choose how thoroughly you want to analyze your code, from quick scans to deep dives.
  • Configure Detection Rules Fine-tune how components are identified in your codebase.
  • Customise Output Format Get results that match your needs, whether it’s detailed reports or focused summaries.
  • Manage Component Information Control how your software components are identified and represented.

​
How It Helps

  • Efficiency: Skip unnecessary files and focus on what matters
  • Accuracy: Guide the scanner to make better decisions
  • Flexibility: Adapt the scanning process to your specific needs
  • Consistency: Maintain standardized scanning across your projects
The settings file is your single source of truth for scanner configuration, ensuring that your scans are reproducible and aligned with your project’s requirements.

​
Schema Overview

Download a sample settings file here: scanoss-settings-schema.json The settings file consists of two main sections:

​
Project Information

The self section contains basic information about your project: 
{
  "self": {
    "name": "my-project",
    "license": "MIT",
    "description": "Project description"
  }
}

​
Settings

The settings object allows you to configure various aspects of the scanning process. It includes file filtering, network configuration, and snippet matching tuning parameters. Settings Structure: 
{
  "settings": {
    "skip": {
      // File filtering configuration
    },
    "proxy": {
      // Root-level proxy configuration
    },
    "http_config": {
      // Root-level HTTP configuration
    },
    "file_snippet": {
      // Snippet-specific tuning parameters
    },
    "hpfm": {
      // High Precision Folder Matching settings
    }
  }
}

​
Skip configuration

The skip object lets you define rules for excluding files from being scanned or fingerprinted. This can be useful for improving scan performance and avoiding unnecessary processing of certain files.
Properties
Patterns use the same syntax as .gitignore files. For more details, refer to the gitignore pattern documentation. skip.patterns.scanning: A list of file patterns to exclude from scanning.
PropertyDescription
TypeArray of strings
RequiredNo
Example: 
{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": [
          "*.log",
          "!important.log",
          "temp/",
          "debug[0-9]*.txt",
          "src/client/specific-file.js",
          "src/nested/folder/"
        ]
      }
    }
  }
}
skip.patterns.fingerprinting: A list of patterns that determine which files should be skipped during fingerprinting.
PropertyDescription
TypeArray of strings
RequiredNo
Example: 
{
  "settings": {
    "skip": {
      "patterns": {
        "fingerprinting": [
          "*.log",
          "!important.log",
          "temp/",
          "debug[0-9]*.txt",
          "src/client/specific-file.js",
          "src/nested/folder/"
        ]
      }
    }
  }
}
skip.sizes.scanning: Rules for skipping files based on their size during scanning.
PropertyDescription
TypeObject
RequiredNo
Properties:
  • patterns (array of strings) — List of glob patterns to apply the min/max size rule
  • min (integer) — Minimum file size in bytes
  • max (integer, required) — Maximum file size in bytes
Example: 
{
  "settings": {
    "skip": {
      "sizes": {
        "scanning": [
          {
            "patterns": [
              "*.log",
              "!important.log",
              "temp/",
              "debug[0-9]*.txt",
              "src/client/specific-file.js",
              "src/nested/folder/"
            ],
            "min": 100,
            "max": 1000000
          }
        ]
      }
    }
  }
}
skip.sizes.fingerprinting: Rules for skipping files based on their size during fingerprinting.
PropertyDescription
TypeObject
RequiredNo
Properties:
  • patterns (array of strings) — List of glob patterns to apply the min/max size rule
  • min (integer) — Minimum file size in bytes
  • max (integer, required) — Maximum file size in bytes
Example: 
{
  "settings": {
    "skip": {
      "sizes": {
        "fingerprinting": [
          {
            "patterns": [
              "*.log",
              "!important.log",
              "temp/",
              "debug[0-9]*.txt",
              "src/client/specific-file.js",
              "src/nested/folder/"
            ],
            "min": 100,
            "max": 1000000
          }
        ]
      }
    }
  }
}
Pattern Format Rules
  • Patterns are matched relative to the scan root directory
  • A trailing slash indicates a directory (e.g., path/ matches only directories)
  • An asterisk * matches anything except a slash
  • Two asterisks ** match zero or more directories (e.g., path/**/folder matches path/to, path/to/folder, path/to/folder/b)
  • Range notations like [0-9] match any character in the range
  • Question mark ? matches any single character except a slash
Example: 
# Match all .txt files
*.txt

# Match all .log files except important.log
*.log
!important.log

# Match all files in the build directory
build/

# Match all .pdf files in docs directory and its subdirectories
docs/**/*.pdf

# Match files like test1.js, test2.js, etc.
test[0-9].js
Complete Skip Example
Here’s a comprehensive example combining pattern and size-based skipping. 
{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": [
          "# Node.js dependencies",
          "node_modules/",

          "# Build outputs",
          "dist/",
          "build/"
        ],
        "fingerprinting": [
          "# Logs except important ones",
          "*.log",
          "!important.log",

          "# Temporary files",
          "temp/",
          "*.tmp",

          "# Debug files with numbers",
          "debug[0-9]*.txt",

          "# All test files in any directory",
          "**/*test.js"
        ]
      },
      "sizes": {
        "scanning": [
          {
            "patterns": ["*.log", "!important.log"],
            "min": 512,
            "max": 5242880
          }
        ],
        "fingerprinting": [
          {
            "patterns": [
              "temp/",
              "*.tmp",
              "debug[0-9]*.txt",
              "src/client/specific-file.js",
              "src/nested/folder/"
            ],
            "min": 512,
            "max": 5242880
          }
        ]
      }
    }
  }
}

​
Proxy Configuration

Root-level proxy configuration for all SCANOSS API requests. This can be overridden at the snippet level using file_snippet.proxy. settings.proxy
PropertyDescription
TypeObject
RequiredNo
Properties:
  • host (string, required) — Proxy server URL including protocol and port
Example: 
{
  "settings": {
    "proxy": {
      "host": "http://file-snippet-proxy:8080"
    }
  }
}

​
HTTP Configuration

Root-level HTTP configuration for all SCANOSS API requests. This can be overridden at the snippet level using file_snippet.http_config. settings.http_config
PropertyDescription
TypeObject
RequiredNo
Properties:
  • base_uri (string) — Base API endpoint URL
  • ignore_cert_errors (boolean) — Whether to ignore SSL certificate validation errors
Example: 
{
  "settings": {
    "http_config": {
      "base_uri": "https://root-api.scanoss.com",
      "ignore_cert_errors": false
    }
  }
}

​
Snippet Matching Tuning

The file_snippet section provides fine-grained control over snippet matching behavior. These settings help you reduce false positives, improve match accuracy, and customise scanning behavior for your specific codebase.
file_snippet.min_snippet_hits
Minimum number of snippet hits required for a match to be considered valid. Higher values reduce false positives by requiring more evidence before reporting a match. Example: 
{
  "settings": {
    "file_snippet": {
      "min_snippet_hits": 5
    }
  }
}
file_snippet.min_snippet_lines
Minimum number of lines a snippet must span to be considered. Filters out tiny matches that may not be meaningful, such as single-line imports or common boilerplate. Example: 
{
  "settings": {
    "file_snippet": {
      "min_snippet_lines": 3
    }
  }
}
file_snippet.ranking_enabled
Controls whether origin project score quality is taken into account during matching. Example: 
{
  "settings": {
    "file_snippet": {
      "ranking_enabled": true
    }
  }
}
file_snippet.ranking_threshold
Sets the minimum ranking score (0-10) required for matches to be reported. Higher thresholds mean only high-confidence matches are returned. Use -1 to apply the server default threshold. Example: 
{
  "settings": {
    "file_snippet": {
      "ranking_threshold": 7
    }
  }
}
file_snippet.honour_file_exts
Controls whether file extensions are considered during matching. Useful when files have been renamed or use non-standard extensions. Example: 
{
  "settings": {
    "file_snippet": {
      "honour_file_exts": false
    }
  }
}
file_snippet.skip_headers
Skip license headers, comments, and imports at the beginning of files. This helps avoid false matches on standard boilerplate that appears in many files. Example: 
{
  "settings": {
    "file_snippet": {
      "skip_headers": true
    }
  }
}
file_snippet.skip_headers_limit
Maximum number of lines to skip when skip_headers is enabled. Controls how much of the file’s beginning is ignored during matching. Example: 
{
  "settings": {
    "file_snippet": {
      "skip_headers": true,
      "skip_headers_limit": 50
    }
  }
}
file_snippet.dependency_analysis
Enable dependency analysis during scanning. When enabled, the scanner will analyze and report on dependencies declared in manifest files. Example: 
{
  "settings": {
    "file_snippet": {
      "dependency_analysis": true
    }
  }
}
file_snippet.proxy
Snippet-specific proxy configuration that overrides the root-level settings.proxy. Use this when snippet scanning requires a different proxy than other operations. Example: 
{
  "settings": {
    "file_snippet": {
      "proxy": {
        "host": "http://snippet-proxy.example.com:8080"
      }
    }
  }
}
file_snippet.http_config
Snippet-specific HTTP configuration that overrides the root-level settings.http_config. Use this when snippet scanning requires different API endpoints or certificate handling. Example: 
{
  "settings": {
    "file_snippet": {
      "http_config": {
        "base_uri": "https://snippet-api.scanoss.com",
        "ignore_cert_errors": true
      }
    }
  }
}

​
High Precision Folder Matching (HPFM)

HPFM (High Precision Folder Matching) settings control matching behavior for entire folder structures rather than individual files. This is useful for detecting when large portions of a codebase match known components.
hpfm.ranking_enabled
Enable ranking specifically for HPFM (folder-level) operations. When enabled, folder matches are ranked by confidence to help you focus on the most significant structural matches. Example: 
{
  "settings": {
    "hpfm": {
      "ranking_enabled": true
    }
  }
}
hpfm.ranking_threshold
Specifies the minimum ranking score (0–10) HPFM (High Precision Folder Matching) uses to include folder-level matches in results. A value of -1 defers to the server’s default threshold. Example: 
{
  "settings": {
    "hpfm": {
      "ranking_threshold": 8
    }
  }
}

​
BOM

The bom section defines rules for modifying the BOM before and after scanning. It contains three main operations:

​
Include Rules

Rules for adding context when scanning. These rules will be sent to the SCANOSS API meaning they have more chance of being considered part of the resulting scan. 
{
  "bom": {
    "include": [
      {
        "path": "/path/to/file",
        "purl": "pkg:npm/vue@2.6.12",
        "comment": "Optional comment"
      }
    ]
  }
}

​
Remove Rules

Rules for removing files from results after scanning. These rules will be applied to the results file after scanning. The post processing happens on the client side. 
{
  "bom": {
    "remove": [
      {
        "path": "/path/to/file",
        "purl": "pkg:npm/vue@2.6.12",
        "comment": "Optional comment"
      }
    ]
  }
}

​
Replace Rules

Rules for replacing components after scanning. These rules will be applied to the results file after scanning. The post processing happens on the client side. 
{
  "bom": {
    "replace": [
      {
        "path": "/path/to/file",
        "purl": "pkg:npm/vue@2.6.12",
        "replace_with": "pkg:npm/vue@2.6.14",
        "license": "MIT",
        "comment": "Optional comment"
      }
    ]
  }
}

​
Important Notes

Matching Rules
  • Full Match: Requires both PATH and PURL to match. It means the rule will be applied ONLY to the specific file with the matching PURL and PATH.
  • Partial Match: Matches based on either: - File path only (PURL is optional). It means the rule will be applied to all files with the matching path. - PURL only (PATH is optional). It means the rule will be applied to all files with the matching PURL.
File Paths
  • All paths should be specified relative to the scanned directory
  • Use forward slashes (/) as path separators
Given the following example directory structure: 
project/
├── src/
│   └── component.js
└── lib/
    └── utils.py
If the scanned directory is /project/src, then:
  • component.js is a valid path
  • lib/utils.py is an invalid path and will not match any files
If the scanned directory is /project, then:
  • src/component.js is a valid path
  • lib/utils.py is a valid path
Package URLs (PURLs) PURLs must follow the Package URL specification:
  • Format: pkg:<type>/<namespace>/<name>@<version>
  • Examples: - pkg:npm/vue@2.6.12 - pkg:golang/github.com/golang/go@1.17.3
  • Must be valid and include all required components
  • Version is strongly recommended but optional

​
Full Example

Here’s a complete configuration showing all available settings including the snippet tuning parameters: 
{
  "self": {
    "name": "example-project",
    "license": "Apache-2.0",
    "description": "Example project with advanced snippet tuning"
  },
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["node_modules/", "dist/", "build/"],
        "fingerprinting": [
          "*.log",
          "!important.log",
          "temp/",
          "*.tmp",
          "debug[0-9]*.txt",
          "**/*test.js"
        ]
      },
      "sizes": {
        "scanning": [
          {
            "patterns": ["*.log", "!important.log"],
            "min": 512,
            "max": 5242880
          }
        ],
        "fingerprinting": [
          {
            "patterns": [
              "temp/",
              "debug[0-9]*.txt",
              "src/client/specific-file.js"
            ],
            "min": 512,
            "max": 5242880
          }
        ]
      }
    },
    "proxy": {
      "host": "http://corporate-proxy.example.com:8080"
    },
    "http_config": {
      "base_uri": "https://api.scanoss.com",
      "ignore_cert_errors": false
    },
    "file_snippet": {
      "min_snippet_hits": 5,
      "min_snippet_lines": 3,
      "ranking_enabled": true,
      "ranking_threshold": 7,
      "honour_file_exts": true,
      "skip_headers": true,
      "skip_headers_limit": 50,
      "dependency_analysis": true
    },
    "hpfm": {
      "ranking_enabled": true,
      "ranking_threshold": 8
    }
  },
  "bom": {
    "include": [
      {
        "path": "src/lib/component.js",
        "purl": "pkg:npm/lodash@4.17.21",
        "comment": "Include lodash dependency"
      }
    ],
    "remove": [
      {
        "purl": "pkg:npm/deprecated-pkg@1.0.0",
        "comment": "Remove deprecated package"
      }
    ],
    "replace": [
      {
        "path": "src/utils/helper.js",
        "purl": "pkg:npm/old-lib@1.0.0",
        "replace_with": "pkg:npm/new-lib@2.0.0",
        "license": "MIT",
        "comment": "Upgrade to newer version"
      }
    ]
  }
}