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

> Learn how to configure vulnerability ignore rules in osv-scanner.toml. Suppress specific vulnerabilities with clear reasons and optional expiry dates for precise scan results.

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

---

**You can suppress specific vulnerabilities in OSV Scanner by creating an [`osv-scanner.toml`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/internal/config/config.go):

```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:**

```toml
[[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`](https://github.com/google/osv-scanner/blob/main/internal/config/config.go) (lines 24–30), the `IgnoreEntry` struct defines the data model:

```go
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`:

```go
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:

```go
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`](https://github.com/google/osv-scanner/blob/main/osv-scanner.toml) next to your [`package-lock.json`](https://github.com/google/osv-scanner/blob/main/package-lock.json), `go.mod`, or other lockfile:

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

```

Run the scanner normally:

```bash
osv-scanner scan .

```

### Temporary Ignores with Expiry Dates

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

```toml
[[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`](https://github.com/google/osv-scanner/blob/main/osv-scanner.toml) files, use the `--config` flag defined in [`cmd/osv-scanner/scan/source/command.go`](https://github.com/google/osv-scanner/blob/main/cmd/osv-scanner/scan/source/command.go):

```bash
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`](https://github.com/google/osv-scanner/blob/main/osv-scanner.toml)** in the same directory as your lockfile; the filename is defined by `OSVScannerConfigName` in [`internal/config/config.go`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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.