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. Currently, it provides control over which files should be skipped during scanning through the skip property.

​
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 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
          }
        ]
      }
    }
  }
}

​
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

{
  "self": {
    "name": "example-project",
    "license": "Apache-2.0",
    "description": "Example project configuration"
  },
  "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",
              "src/nested/folder/"
            ],
            "min": 512,
            "max": 5242880
          }
        ]
      }
    }
  },
  "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"
      }
    ]
  }
}