Ignore rules

Purpose

Ignore rules let users (or hard-coded Grype defaults) move matches into a separate "ignored" set without losing the information. Ignored matches are excluded from the default output but visible with --show-suppressed and always present in the JSON output.

Where they come from

Three sources, applied in order:

1. Hard-coded explicit ignores in grype/match/explicit_ignores.go. These are global, baked-in suppressions for known false positives (e.g. linux-kernel-headers matched indirectly via kernel).
2. CLI-augmented rules added by cmd/grype/cli/commands/root.go::runGrype:
   • --only-fixed → ignore not-fixed, wont-fix, and unknown fix states.
   • --only-not-fixed → ignore fixed.
   • --ignore-states <comma-separated> → ignore the listed fix states.
   • --match-upstream-kernel-headers=false (default) → ignore the linux kernel headers tuples.
3. User-provided rules from CLI (--ignore <yaml-file>), env (GRYPE_IGNORE), or YAML config (ignore: ...).

Rule shape

grype/match/ignore.go::IgnoreRule:

type IgnoreRule struct {
    Vulnerability    string             `yaml:"vulnerability"`
    IncludeAliases   bool               `yaml:"include-aliases"`
    Reason           string             `yaml:"reason"`
    Namespace        string             `yaml:"namespace"`
    FixState         string             `yaml:"fix-state"`
    Package          IgnoreRulePackage  `yaml:"package"`
    VexStatus        string             `yaml:"vex-status"`
    VexJustification string             `yaml:"vex-justification"`
    MatchType        Type               `yaml:"match-type"`
}

type IgnoreRulePackage struct {
    Name         string
    Version      string
    Language     string
    Type         string
    Location     string
    UpstreamName string
}

A rule applies when every non-empty field matches. Name, UpstreamName, and Location accept regex syntax when they contain regex meta-characters; otherwise they are exact-match.

Indexed evaluation

Naively applying N rules to M matches is O(N×M). vulnerability_matcher.go::ignoredMatchFilter builds three indexes for fast lookup:

• by exact Package.Location (for location-targeted rules).
• by exact Package.Name (for package-name rules).
• by exact Vulnerability ID (for ID-targeted rules with IncludeAliases).

Rules that don't fit an index fall through to a linear scan, but the indexed paths handle the common cases cheaply.

Related-package ignores

match.IgnoreRelatedPackage is a more specialized filter. It says "ignore vulnerability X for package P if P is related to package R." The matcher pipeline uses this to suppress duplicates produced by upstream-aware matchers (e.g. when both an apk binary package and its source have a hit on the same CVE).

YAML example

ignore:
  # ignore everything from this CVE
  - vulnerability: CVE-2024-99999
    reason: 'False positive; investigated 2024-09-01'

  # ignore not-fixed CVEs in test images
  - fix-state: not-fixed
    package:
      location: /opt/test/**

  # ignore vendor-marked not_affected
  - vex-status: not_affected

Output

Each ignored match in the JSON output carries appliedIgnoreRules — the list of rules that matched it — so users and post-processors can reason about why a match was suppressed.

Key source files

File	Purpose
grype/match/ignore.go	Rule shape + matching.
grype/match/explicit_ignores.go	Hard-coded suppressions.
grype/vulnerability_matcher.go	Pipeline integration + index construction.
cmd/grype/cli/commands/root.go	CLI-flag-driven rule augmentation.
cmd/grype/cli/options/grype.go	CLI options for ignores.

Entry points for modification

• Tighten or relax a built-in — edit grype/match/explicit_ignores.go. These rules apply to every scan; changes need broad testing.
• Add a new rule field — extend IgnoreRule, propagate through the indexed-evaluation logic, and update YAML parsing in grype/match/ignore.go::IgnoreRule.UnmarshalYAML.
• Surface a new ignore source — add the loader in cmd/grype/cli/commands/root.go::runGrype's pre-match phase.