VULNIX-WHITELIST(5)

📦
version 1.12.5 · 2 versions
, in nixpkgs unstable

💅 VULNIX-WHITELIST(5) — the whitelist file format, explained 🎀

okay so. this is a page from the vulnix manual, section 5 — iykyk, that's "file formats" energy. sit down bestie, we're learning how whitelists work ✨

🌸 NAME 🌸

vulnix-whitelist — literally the whitelist file format. that's it. that's the name 🫶

🦋 DESCRIPTION 🦋

Whitelists are the vibe check that excludes matching program versions from the list of vulnerabilities that vulnix(1) reports. each whitelist file is just a list of rules, and each rule defines its matching criteria. key detail: if a derivation is not matched by any whitelist rule, it gets reported. no rule, no mercy 💀

so here's the vocabulary you need:

  • program — the part of a derivation name before the first dash followed by a digit.
  • version — the part of a derivation name starting at the first digit after a dash.
  • cve — one or more reported CVE identifiers.

and like, additionally, whitelist rules can contain an expiry date (until), plus both a free-text comment and a URL to an issue tracker, purely for informational purposes. cute little metadata moment 💖

📝 TOML format 📝

every rule starts with a TOML section header. the following forms are allowed:

  • ["PROGRAM-VERSION"] — matches derivations with the specified program name and version.
  • ["PROGRAM"] — matches derivations with the specified program name and an arbitrary version for which no more specific rule is present.
  • ["*"] — matches arbitrary derivations that are not covered by a more specific rule. ⚠️ note that the cve field must be specified in this case.

each rule is optionally followed by these fields:

  • cve = ["CVEID", ...] — this rule is only valid if the reported CVE advisories are a subset of those specified here. in case additional CVEs are found, this rule becomes invalid. no cap, it just stops applying.
  • until = "YYYY-MM-DD" — matching derivations are reported only from the specified date on.
  • comment = "TEXT" — contains notes to fellow users, e.g. to explain why a whitelist rule has been written. a list of strings is also allowed.
  • issue_url = "URL" — a link to a ticket in some issue tracker where the development of fixes gets tracked. a list of URLs is also allowed.

🥀 YAML format (deprecated) 🥀

whitelists may also be specified in the legacy YAML format. a whitelist file consists of a list of dicts with the keys:

  • name — derivation name
  • version
  • cve — list of CVE identifiers
  • comment — free text
  • status — ignored; for compatibility reasons
🚨 heads up: the issue_url field is not valid in YAML whitelists. also, one more time for the people in the back — this format is deprecated.

👑 NOTES 👑

for any given derivation, all relevant rules are applied in order of decreasing specificity. most specific first, always 💅

multiple whitelists can be used by passing more than one -w option to vulnix. multiple whitelists are merged in order. for merging, the following rules apply:

  • rules containing a version and those without are considered different. only rules with the same headers are merged.
  • CVE lists are concatenated and duplicates are removed.
  • comments and issue URLs are converted to lists and concatenated.

✨ EXAMPLES ✨

whitelist in TOML format with three rules: the first one matches a specific version of PCRE until a given date. the second one matches all versions of GNU patch as long as the set of published CVEs is a subset of the listed CVEs. the third matches any derivation which is affected by no more than the listed CVEs.

["pcre-8.41"]
until = "2018-03-01"
comment = "should be fixed in a month"
issue_url = "https://tracker.example.com/12345"

["patch"]
cve = ["CVE-2018-6952", "CVE-2018-6951"]
comment = "won't fix these two, but alert me if there is a new CVE"

["*"]
cve = [
  "CVE-2017-6827",
  "CVE-2017-6834",
  "CVE-2017-6828",
  "CVE-2017-6833",
]

🧚 SEE ALSO 🧚

and that's the whole page bestie 🫶 this was Version 1.12.5, dated January 1980 (yes, the date is silly, we love her for it) — go forth and whitelist responsibly 💜✨

📦 where this page comes from