[YAML design] Filtering for vulnerability exposure

[kilo-code-bot]

UPDATE: @noahtalerman: Marking this PR as draft until we know which release we're targeting.

• @noahtalerman: YAML (GitOps) changes for the following user story:
  • Filtering for vulnerability exposure: YAML (GitOps) #47327

[sgress454]

For the purpose of keeping the YAML and API close together, can we flatten these to:

• epss_min
• epss_max
• cvss_min
• cvss_max

Suggested change

	epss_score:
	min: 0
	max: 100
	cvss_score:
	min: 9
	max: 10
	epss_min: 0
	epss_max: 100
	cvss_min: 9
	cvss_max: 10

[sgress454]

Also CVSS should be left out of this revision or else a comment put in that it won't do anything yet.

[lukeheath]

@noahtalerman Reminder this needs to be merged - the code just merged. Also the docs branch needs to be updated to 4.89.0 since we're issuing a mid-cadence release of 4.88.0.

[AndreyKizimenko]

@noahtalerman heads up — this draft's YAML doesn't match the field names/shape that actually shipped in the merged implementation (#47634, in the 4.89.0 RC).

The source of truth is VulnExposureFilterSettings in server/fleet/app.go. The block uses flat fields, not the nested epss_score/cvss_score objects shown here, and several key names differ:

This draft	Merged code (app.go)
software_categories (os, browser, microsoft_office, adobe)	software_filters (os, browsers, office, adobe)
epss_score: {min, max}	epss_min / epss_max
cvss_score: {min, max}	cvss_min / cvss_max
exclude_cves	exclude_vulnerabilities
has_known_exploit	has_known_exploit (matches)

Validation in the merged code (VulnExposureFilterSettings.Validate):

• software_filters — valid values os, browsers, office, adobe; must include at least one (explicit empty list is rejected).
• cvss_min/cvss_max — 0–10, min <= max.
• epss_min/epss_max — 0–100 in YAML (converted to 0–1 on the chart API), min <= max.
• exclude_vulnerabilities — must match CVE-\d{4}-\d{4,} (case-insensitive).

So the docs example should read something like:

org_settings:
  features:
    vulnerability_exposure_historical_reporting:
      software_filters:
        - os
        - browsers
        - office
        - adobe
      has_known_exploit: true
      epss_min: 0
      epss_max: 100
      cvss_min: 9
      cvss_max: 10
      exclude_vulnerabilities:
        - CVE-2025-50897
        - CVE-2025-76306

Could you update the draft to match the shipped field names before it merges? Otherwise the published docs will describe a schema that GitOps will reject. Thanks!

[noahtalerman]

@AndreyKizimenko thanks for the heads up! Looking into this 👀

[noahtalerman]

Closing out this PR because the changes are already live on the website: https://fleetdm.com/docs/configuration/yaml-files#org-settings-and-settings