How to Configure Vulnerability Ignore Rules in osv-scanner.toml

You can suppress specific vulnerabilities in OSV Scanner by creating an osv-scanner.toml file next to your lockfile and adding [[IgnoredVulns]] entries that specify the vulnerability ID, optional expiry date, and reason.

The google/osv-scanner tool supports fine-grained ignore rules that allow security teams to filter out false positives or accepted risks without modifying lockfiles. These rules are defined using TOML syntax and processed by the configuration package located in internal/config/config.go. Below is a complete guide to the file structure, underlying logic, and practical examples.

Configuration File Location and Naming

The scanner searches for a hardcoded filename defined by the OSVScannerConfigName constant in internal/config/config.go:

var OSVScannerConfigName = "osv-scanner.toml"

Place this file in the same directory as the lockfile you are scanning. The scanner does not cascade configuration to subdirectories, so each project directory requires its own file unless you use the global override flag.

TOML Syntax for Ignore Entries

The configuration uses an array-of-tables structure named [[IgnoredVulns]]. Each entry supports three fields:

• id (string, required): The OSV vulnerability identifier (e.g., GO-2022-0968 or GHSA-xxx).
• ignoreUntil (date, optional): An expiry timestamp in ISO 8601 format (e.g., 2024-12-31). Omit this field for permanent ignores.
• reason (string, optional): A human-readable explanation displayed in scan output.

Basic example:

[[IgnoredVulns]]
id = "GO-2022-0968"
reason = "No SSH servers are deployed in this Go service"

[[IgnoredVulns]]
id = "GO-2022-1059"
ignoreUntil = 2024-06-01
reason = "Temporary acceptance until upstream library updates"

How Ignore Logic Works in the Source Code

The IgnoreEntry Struct

In internal/config/config.go (lines 24–30), the IgnoreEntry struct defines the data model:

type IgnoreEntry struct {
    ID          string    `toml:"id"`
    IgnoreUntil time.Time `toml:"ignoreUntil"`
    Reason      string    `toml:"reason"`
    Used        bool      `toml:"-"` // internal tracking field
}

The Used field is excluded from TOML serialization and tracks whether the entry matched any vulnerability during the scan.

Matching and Expiry Evaluation

The Config.ShouldIgnore method (lines 90–98) performs the lookup using slices.IndexFunc:

func (c *Config) ShouldIgnore(vulnID string) (bool, *IgnoreEntry) {
    index := slices.IndexFunc(c.IgnoredVulns, func(e *IgnoreEntry) bool { return e.ID == vulnID })
    if index == -1 {
        return false, &IgnoreEntry{}
    }
    ignoredLine := c.IgnoredVulns[index]
    return shouldIgnoreTimestamp(ignoredLine.IgnoreUntil), ignoredLine
}

The helper function shouldIgnoreTimestamp (lines 35–43) handles expiry logic:

func shouldIgnoreTimestamp(ignoreUntil time.Time) bool {
    if ignoreUntil.IsZero() {
        return true                // No expiry → ignore forever
    }
    return ignoreUntil.After(time.Now())
}

If ignoreUntil is a zero value (omitted in TOML), the vulnerability is suppressed indefinitely. Otherwise, the ignore is active only while the timestamp remains in the future.

Tracking Unused Rules

After scanning, the tool warns about stale configuration entries. The UnusedIgnoredVulns method (lines 78–88) collects entries where Used == false, helping teams remove outdated suppressions.

Practical Configuration Examples

Basic Single Vulnerability Ignore

Create osv-scanner.toml next to your package-lock.json, go.mod, or other lockfile:

[[IgnoredVulns]]
id = "GHSA-1234-5678-90ab"
reason = "Development dependency only; not shipped in production"

Run the scanner normally:

osv-scanner scan .

Temporary Ignores with Expiry Dates

Use ignoreUntil to create time-bound exceptions that automatically expire:

[[IgnoredVulns]]
id = "GO-2023-0012"
ignoreUntil = 2024-03-31
reason = "Mitigation in place until Q1 patch cycle completes"

After March 31, 2024, the scanner will resume reporting this vulnerability.

Global Configuration with the --config Flag

To apply a single ignore list across multiple projects, bypassing per-directory osv-scanner.toml files, use the --config flag defined in cmd/osv-scanner/scan/source/command.go:

osv-scanner scan --config ~/security/global-ignores.toml /path/to/monorepo

This is useful for centralized security policies in large organizations.

Summary

• Place osv-scanner.toml in the same directory as your lockfile; the filename is defined by OSVScannerConfigName in internal/config/config.go.
• Structure ignores using the [[IgnoredVulns]] array with required id and optional ignoreUntil and reason fields.
• Expiry logic treats zero-value dates as permanent ignores and evaluates dates via shouldIgnoreTimestamp in the source.
• Override locally using the --config flag to specify a global configuration file.
• Clean up rules by reviewing warnings emitted by UnusedIgnoredVulns after each scan.

Frequently Asked Questions

Can I ignore vulnerabilities across my entire repository with one file?

No, the scanner looks for osv-scanner.toml in the same directory as each individual lockfile and does not cascade to subdirectories. To apply a single set of rules everywhere, use the --config /path/to/global.toml flag when running osv-scanner scan, which overrides local configuration files.

What date format should I use for ignoreUntil?

Use ISO 8601 format (e.g., 2024-12-31 or 2024-12-31T23:59:59Z). The shouldIgnoreTimestamp function in internal/config/config.go parses this using Go’s time.Time parsing, treating zero values (omitted field) as "ignore forever."

Does the scanner warn me about unused ignore rules?

Yes. The UnusedIgnoredVulns method identifies any IgnoreEntry that did not match a vulnerability found in the current scan. The CLI prints these as warnings, recommending you remove stale entries to keep your configuration accurate.

Are vulnerability aliases also suppressed when I ignore an ID?

Yes. When you provide an ignore ID, the scanner also filters out any aliases of that vulnerability as defined in the OSV database, ensuring comprehensive suppression of duplicate findings.

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