How to Configure Package Overrides in the OSV-Scanner Configuration File

You configure package overrides by creating an osv-scanner.toml file in your project root and defining [[PackageOverrides]] entries that specify match criteria (name, version, ecosystem, group) and desired actions (ignore, vulnerability.ignore, license.override).

The google/osv-scanner tool supports granular suppression and modification rules through TOML-based configuration, allowing you to ignore specific packages, suppress false-positive vulnerabilities, or override license detections without altering your dependency files.

Understanding the PackageOverrides Structure

The configuration system defines package overrides through the PackageOverrideEntry struct located in internal/config/config.go. Each entry in the PackageOverrides array supports optional match criteria and mandatory action fields.

Match criteria filter which packages the override applies to:

• name – The package name (e.g., "axios")
• version – Specific version string (e.g., "0.21.1")
• ecosystem – Package ecosystem (e.g., "npm", "pypi", "go")
• group – Dependency group classifier (e.g., "dev")

Action fields determine what happens when criteria match:

• ignore – Boolean to skip both vulnerability and license scanning
• vulnerability.ignore – Boolean to skip only vulnerability checks
• license.ignore – Boolean to skip license verification
• license.override – Array of strings replacing detected licenses (e.g., ["MIT"])
• effectiveUntil – RFC3339 timestamp for automatic expiration
• reason – Documentation string explaining the override

How Package Matching Works

The matching algorithm implemented in the matches method of PackageOverrideEntry uses strict conjunctive logic. When processing a discovered package, the scanner evaluates every populated field in the override entry against the package metadata. All supplied criteria must match for the override to apply—omitted fields act as wildcards.

As implemented in internal/config/config.go (lines 49-66), the method compares the override entry against the extractor.Package instance. If you specify name, version, and ecosystem, the override triggers only when all three attributes align perfectly with the detected package.

Configuration Actions and Their Effects

Once a PackageOverrideEntry matches, the scanner delegates to three specific helper methods defined on the top-level Config struct to determine behavior:

ShouldIgnorePackage (lines 12-18) returns true when any matching override sets ignore = true, causing the scanner to exclude the package entirely from both vulnerability and license analysis.

ShouldIgnorePackageVulnerabilities (lines 19-24) activates when vulnerability.ignore = true in a matching entry, allowing license scanning to continue while suppressing vulnerability reports.

ShouldOverridePackageLicense (lines 28-33) handles both license.ignore and license.override fields, returning whether to skip license validation or substitute the detected license list with your specified values.

Each helper first filters the PackageOverrides slice through filterPackageVersionEntries, which validates the optional effectiveUntil timestamp via shouldIgnoreTimestamp to ensure expired rules are automatically disregarded.

Practical Configuration Examples

Ignore a Specific Package Completely

To exclude axios version 0.21.1 from all scanning:

[[PackageOverrides]]
name = "axios"
version = "0.21.1"
ecosystem = "npm"
ignore = true
reason = "Internal fork with patched vulnerabilities"
effectiveUntil = 2024-12-31

Suppress Vulnerabilities While Checking Licenses

For packages with known false positives in the CVE database:

[[PackageOverrides]]
name = "example-lib"
version = "2.3.4"
ecosystem = "pypi"
vulnerability.ignore = true
reason = "Known false-positive tracked internally"

Override License Detection

Replace the automatically detected license for a C library:

[[PackageOverrides]]
name = "libssl"
ecosystem = "c"
license.override = ["OpenSSL"]

Ignore All Packages in an Ecosystem

blanket rules apply when match criteria are omitted:

[[PackageOverrides]]
ecosystem = "go"
ignore = true
reason = "Internal Go modules audited separately"

Time-Bounded Dev Dependencies

Suppress dev dependencies that expire after a specific date:

[[PackageOverrides]]
group = "dev"
ignore = true
effectiveUntil = 2025-06-01
reason = "Temporary build dependency"

Summary

• Configuration resides in osv-scanner.toml using TOML syntax with [[PackageOverrides]] entries.
• The PackageOverrideEntry struct in internal/config/config.go defines valid fields including name, version, ecosystem, group, and various ignore/override actions.
• Matching requires all provided criteria to align with the discovered package (conjunctive logic).
• Three helper methods—ShouldIgnorePackage, ShouldIgnorePackageVulnerabilities, and ShouldOverridePackageLicense—process matching entries to determine scanning behavior.
• The effectiveUntil field enables temporary overrides that automatically expire after the specified timestamp.

Frequently Asked Questions

What file format does osv-scanner use for configuration?

OSV-scanner uses TOML (Tom's Obvious, Minimal Language) for its configuration files. The scanner looks for a file named osv-scanner.toml in the directory being scanned, or accepts a custom path via the --config flag. This format supports the nested table syntax required for [[PackageOverrides]] entries.

Can I use wildcards or regular expressions in package names?

No, the current implementation in internal/config/config.go uses exact string matching for the name, version, ecosystem, and group fields within the matches method. To apply broad rules, omit specific fields (which act as wildcards) or create multiple explicit entries for each package requiring overrides.

How does the effectiveUntil timestamp work?

The effectiveUntil field accepts an RFC3339 timestamp (e.g., 2024-12-31T23:59:59Z). When processing overrides, the shouldIgnoreTimestamp helper checks the current time against this value. If the current time exceeds the timestamp, the override entry is filtered out via filterPackageVersionEntries and no longer applies to the scan, effectively reactivating checks for that package.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}