SCANOSS Rule Matching Guide

Common Properties

SCANOSS rules have two properties in common that determine matching behavior:

Property	Type	Description
path	string	File path pattern for matching
purl	string	Package URL for component matching

Path Matching

The path property uses two matching modes controlled by a single character - the trailing slash (/):

Mode	Example	Description
Exact Match	src/lib	Must match the complete path exactly Will ONLY match “src/lib”, nothing more or less
StartsWith Match	src/lib/	Matches any path that begins with “src/lib/” Can have any number of subdirectories or files after it

Note: The trailing slash (/) acts as a simple switch between the two modes:

• Without slash (src/lib):
  • Requires exact match of the entire path
  • Example: “src/lib/file.txt” would NOT match
  • Example: Only “src/lib” would match
• With slash (src/lib/):
  • Matches any path that starts with the pattern
  • Example: “src/lib/file.txt” would match
  • Example: “src/lib/subfolder/file.txt” would match
  • Example: “src/lib/deep/nested/file.txt” would match

Examples

Rule Path	Match Mode	Input Path	Matches?	Explanation
src/lib	Exact	src/lib	✅ YES	Exact match - paths are identical
src/lib	Exact	src/lib/file.txt	❌ NO	Exact match required, but input has extra content
src/lib/	StartsWith	src/lib/file.txt	✅ YES	Input starts with “src/lib/“
src/lib/	StartsWith	src/lib/subfolder/file.txt	✅ YES	Input starts with “src/lib/“
src/lib/	StartsWith	src/libs/file.txt	❌ NO	Input does not start with “src/lib/“
src/lib/	StartsWith	src/lib	❌ NO	Input is shorter than the required prefix

Warning: Common pitfalls to avoid:

• Not having a trailing slash when you want to match subdirectories
• Having a trailing slash when you only want to match one specific path
• Forgetting that exact matches (no slash) will reject anything longer than the pattern

Purl Matching

The PURL property uses two matching modes based on the version specification:

Mode	Description
Basic	Matches the base PURL without version constraints
Version-specific	Must match both the PURL and specified version

Note: The presence of a version (@version) in the PURL automatically enables version-specific matching behavior:

• pkg:github/scanoss/wfp matches any version of the component
• pkg:github/scanoss/wfp@1.4.2 requires exact version match

This provides a simple way to toggle between basic and version-specific matching without additional configuration.

Warning: Components can have multiple Package URLs (PURLs) associated with them. The version shown in the component details corresponds to the first PURL.

Examples

Rule PURL	Scan Result PURLs	Version	Matches?
pkg:github/scanoss/wfp	pkg:github/scanoss/wfp pkg:npm/@scanoss/wfp	1.4.2	✅ YES
pkg:github/scanoss/wfp@1.4.2	pkg:github/scanoss/wfp pkg:github/scanoss/engine	1.4.2	✅ YES
pkg:github/scanoss/wfp	pkg:npm/@scanoss/wfp pkg:github/scanoss/engine	1.4.2	❌ NO

Combined Path and Purl Matching

Note: Combined matching requires BOTH conditions to be satisfied:

• Path must match according to path matching rules
• PURL must match according to PURL matching rules
• Version must match if specified in PURL

If either condition fails, the entire rule fails to match.

Examples

Path Rule	PURL Rule	File Path	Scan Result PURLs	Version	Matches?	Explanation
src/lib/	pkg:github/scanoss/wfp	src/lib/file1.c	pkg:github/scanoss/wfp, pkg:npm/@scanoss/wfp	-	✅ YES	✓ Path starts with src/lib/ ✓ PURL found in list
src/lib/	pkg:github/scanoss/wfp@1.4.2	src/lib/file2.c	pkg:github/scanoss/wfp	1.4.2	✅ YES	✓ Path starts with src/lib/ ✓ PURL + version match
src/lib/	pkg:github/scanoss/wfp@1.4.2	src/lib/file3.c	pkg:github/scanoss/wfp	1.4.1	❌ NO	✓ Path starts with src/lib/ ✗ Version mismatch (1.4.1 ≠ 1.4.2)
src/lib/exact	pkg:github/scanoss/wfp	src/lib/different	pkg:github/scanoss/wfp	-	❌ NO	✗ Path doesn’t match exactly ✓ PURL matches
test/	pkg:github/scanoss/wfp	src/lib/file1.c	pkg:github/scanoss/wfp	-	❌ NO	✗ Path doesn’t start with test/ ✓ PURL matches
src/lib/	pkg:github/scanoss/wfp	src/lib/file1.c	pkg:npm/@scanoss/wfp, pkg:github/scanoss/engine	-	❌ NO	✓ Path starts with src/lib/ ✗ Required PURL not found
src/lib	pkg:github/scanoss/wfp@1.4.2	src/lib	pkg:github/scanoss/wfp	1.4.2	✅ YES	✓ Path matches exactly ✓ PURL + version match
src/lib/	pkg:github/scanoss/wfp	src/lib/subdir/file.c	pkg:github/scanoss/wfp	-	✅ YES	✓ Path starts with src/lib/ ✓ PURL matches (any depth)
src/lib/	pkg:github/scanoss/wfp@2.0.0	src/lib/file.c	pkg:github/scanoss/wfp@1.0.0	2.0.0	❌ NO	✓ Path starts with src/lib/ ✗ PURL version mismatch

Warning:

• Path matches but PURL doesn’t:
  • The file is in the right location but wrong component
  • Results in NO MATCH
• PURL matches but path doesn’t:
  • Right component but wrong location
  • Results in NO MATCH
• Both match but version wrong:
  • Right component and location but wrong version
  • Results in NO MATCH

Rule Priority

SCANOSS sorts all rules based on a priority system before applying them. This ensures a deterministic order of evaluation, with more specific rules being checked before general ones:

Priority Level	Rule Properties	Score	Description
Highest	PURL + Path	4	Rules with both PURL and path are checked first
Medium	PURL only	2	Rules with only PURL are checked second
Low	Path only	1	Rules with only path are checked last
None	No properties	0	Rules with neither property are ignored

When Rules Have Equal Priority

If two rules have the same priority score, additional criteria are used:

1. For rules with paths:

   • The rule with the longer path takes precedence
   • Example: src/lib/utils/ takes precedence over src/lib/

2. If no other criteria distinguish the rules:

   • The rules are considered equal
   • The first matching rule will be applied

Warning: Be careful when defining multiple rules that could match the same files:

• More specific rules (longer paths) take precedence over general rules
• Rules with both PURL and path always take precedence
• Rules with neither property will never be applied