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

> Learn to configure package overrides in the osv-scanner configuration file create an osv-scanner.toml file to manage vulnerabilities by defining ignore and override actions for specific packages.

- Repository: [Google/osv-scanner](https://github.com/google/osv-scanner)
- Tags: how-to-guide
- Published: 2026-04-25

---

**You configure package overrides by creating an [`osv-scanner.toml`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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:

```toml
[[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:

```tomtoml
[[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:

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

```

### Ignore All Packages in an Ecosystem

 blanket rules apply when match criteria are omitted:

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

```

### Time-Bounded Dev Dependencies

Suppress dev dependencies that expire after a specific date:

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

```

## Summary

- Configuration resides in [`osv-scanner.toml`](https://github.com/google/osv-scanner/blob/main/osv-scanner.toml) using TOML syntax with `[[PackageOverrides]]` entries.
- The `PackageOverrideEntry` struct in [`internal/config/config.go`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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.