Improving Scan Accuracy - SCANOSS documentation

SCANOSS matches your code against its knowledgebase using content fingerprints, not file names or explicit declarations. A snippet is the portion of one of your files that fingerprint-matches a piece of known open-source code, it’s the basic unit SCANOSS reports a match against. For most code, this matching produces confident, correct results on its own. But for code that’s short, generic, or vendored from a project with several similar forks or variants, a fingerprint alone can sometimes be ambiguous, more than one component could plausibly be the match. This page covers two independent ways to help SCANOSS get it right: telling it what components you already expect to find (scan context), and adjusting how strict its matching should be overall (snippet tuning). Both are configured in the same scanoss.json file, which SCANOSS tools pick up automatically from the directory being scanned, no extra flags needed.

Where to Place `scanoss.json`

Both techniques in this guide are configured in a single scanoss.json file, saved in the root of the directory you’re scanning, alongside your project’s top-level source folders:

my-project/
├── src/
├── scanoss.json
└── # your project's other top-level files

Providing Scan Context

Most of this documentation covers declaring components after a scan: reviewing what SCANOSS found, then confirming it in your scanoss.json. Scan context works the other way around: you tell SCANOSS what you expect to find, before or during the scan itself, so the scan itself comes back more accurate. When your scanoss.json includes a bom.include rule for a component, that component’s PURL is sent to the SCANOSS API as additional context during the scan, not just applied afterward. It acts as a hint: “this file or folder is expected to be this component.” That extra signal increases the likelihood the correct match is returned. This is the same bom.include rule used to declare components for compliance purposes (see Declaring Components), it does double duty: it satisfies your compliance record, and it improves the scan that produces it.

Providing Context for a Component

Add a bom.include rule to scanoss.json for any component you already know is part of your project. Identify the component with a PURL (Package URL), the standard identifier SCANOSS uses for software components, e.g. pkg:github/scanoss/engine:

{
  "bom": {
    "include": [
      {
        "purl": "pkg:github/scanoss/engine",
        "comment": "Core SCANOSS engine, used for software composition analysis"
      }
    ]
  }
}

Scoping Context to a Path

If you know exactly where a component lives, for example a vendored library, you can scope the hint to that path. This gives the scanner a stronger signal, since it only needs to consider that one component for files under that path:

{
  "bom": {
    "include": [
      {
        "path": "src/vendor/",
        "purl": "pkg:npm/lodash@4.17.21",
        "comment": "All files under src/vendor/ are the vendored lodash library"
      }
    ]
  }
}

When to Provide Context

Providing context up front works best when you already have a good idea of what’s in your project, for example:

You’re vendoring a specific library and know exactly where it lives
A previous scan flagged a component as pending, and you’ve confirmed it’s correct
You’re setting up a new project and already know your major dependencies

If you’re starting from scratch and don’t yet know what’s in your codebase, run an initial scan first and build up your bom.include rules from its results. See Desktop Integration for that end-to-end workflow.

Tuning Snippet Matching

Snippet tuning takes a different approach: instead of telling SCANOSS about specific components, it adjusts how sensitive matching is across the whole scan. These parameters live under settings.file_snippet in scanoss.json. You don’t need to set all of them, start with the default scan and only add a parameter once you have a specific problem to fix:

min_snippet_hits, min_snippet_lines, ranking_enabled, and ranking_threshold control how much evidence a match needs before it’s reported
honour_file_exts, skip_headers, and skip_headers_limit control what parts of a file are considered during matching

`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 a match is reported.

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

`min_snippet_lines`

Minimum number of lines a snippet must span to be considered a valid match. Filters out short matches that are unlikely to be meaningful, such as single-line imports or common boilerplate.

{
  "settings": {
    "file_snippet": {
      "min_snippet_lines": 3
    }
  }
}

`ranking_enabled`

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

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

`ranking_threshold`

Sets the minimum ranking score (0–10) required for a match to be reported. Higher values return only higher-confidence matches. Set to -1 to use the server’s default threshold.

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

`honour_file_exts`

Controls whether file extensions are taken into account during matching. Set to false when files have been renamed or use non-standard extensions.

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

`skip_headers`

Skips licence headers, comments, and imports at the beginning of files. Helps avoid false matches on standard boilerplate that appears across many files.

{
  "settings": {
    "file_snippet": {
      "skip_headers": true
    }
  }
}

`skip_headers_limit`

Maximum number of lines to skip when skip_headers is enabled. Controls how much of the beginning of each file is excluded from matching.

{
  "settings": {
    "file_snippet": {
      "skip_headers": true,
      "skip_headers_limit": 50
    }
  }
}

Which Should You Use?

Both techniques reduce false positives, but they work differently, and you can combine them:

Scan context (bom.include) is targeted: it applies to specific components or paths you already know about. Reach for it when you can name the exact component you expect.
Snippet tuning (file_snippet settings) is global: it changes how strict matching is across your entire scan. Reach for it when you’re seeing too many low-confidence matches, or too few matches on code you know is a real hit, regardless of which component is involved.

For the full scanoss.json reference, including exclude, remove, and replace rules, see Declaring Components.

Complete Example

Both techniques live in the same scanoss.json file, so you can combine them. This example shows the two techniques’ fields together, it’s not a recommended default: pick only the parameters that address a problem you’re actually seeing. Following the same structure as the full scanoss.json reference: project information (self) at the top, scan settings and tuning parameters (settings) in the middle, and BOM rules like scan context (bom.include) at the bottom:

{
  "self": {
    "name": "my-project",
    "license": "MIT",
    "description": "Example project with scan context and snippet tuning enabled"
  },
  "settings": {
    "file_snippet": {
      "min_snippet_hits": 5,
      "min_snippet_lines": 3,
      "ranking_enabled": true,
      "ranking_threshold": 7,
      "honour_file_exts": false,
      "skip_headers": true,
      "skip_headers_limit": 50
    }
  },
  "bom": {
    "include": [
      {
        "purl": "pkg:github/scanoss/engine",
        "comment": "Core SCANOSS engine, used for software composition analysis"
      },
      {
        "path": "src/vendor/",
        "purl": "pkg:npm/lodash@4.17.21",
        "comment": "All files under src/vendor/ are the vendored lodash library"
      }
    ]
  }
}

What’s Next

If you’d rather go step by step instead of the End-to-End Workflow, continue with Desktop Integration to set up local scanning and declaration in more depth.

​Where to Place scanoss.json

​Providing Scan Context

​Providing Context for a Component

​Scoping Context to a Path

​When to Provide Context

​Tuning Snippet Matching

​min_snippet_hits

​min_snippet_lines

​ranking_enabled

​ranking_threshold

​honour_file_exts

​skip_headers

​skip_headers_limit

​Which Should You Use?

​Complete Example

​What’s Next