Skip to content

Add EPSS and other scoring systems that leverage measurements rather than scores. - #1117

Merged
stevespringett merged 10 commits into
2.0-devfrom
2.0-dev-epss
Oct 15, 2026
Merged

stevespringett merged 10 commits into
2.0-devfrom
2.0-dev-epss

Conversation

@stevespringett

Copy link
Copy Markdown
Member

Closes #481

Signed-off-by: Steve Springett <steve@springett.us>
…lity) without restricting ourselves specifically to EPSS, or future scoring systems or versions of EPSS.

Signed-off-by: Steve Springett <steve@springett.us>
@stevespringett stevespringett added this to the 2.0 milestone Sep 18, 2026
@stevespringett stevespringett self-assigned this Sep 18, 2026
@stevespringett
stevespringett requested a review from a team as a code owner September 18, 2026 21:03
@stevespringett stevespringett linked an issue Sep 18, 2026 that may be closed by this pull request
@stevespringett stevespringett added request for comment RFC notice sent A public RFC notice was distributed to the CycloneDX mailing list for consideration labels Sep 18, 2026

@Mehrn0ush Mehrn0ush left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. Named measures plus methodVersion and timestamp answers the concerns in #481 without hard-coding EPSS's current fields, and forbidding score for EPSS keeps probabilities from being mixed with severity scores.

Suggestions I left as inline comments:

  1. confidence is in meta:enum but not in the enum, which probably explains the red test 2.0 job.
  2. For EPSS, also require measures with a probability, and consider requiring timestamp.
  3. Define timestamp as when the method produced the score (the EPSS score date), not when it was retrieved.
  4. Bound probability, percentile, and confidence to 0–1.
  5. Say that measure names are unique within a rating.

Comment thread schema/2.0/modules/cyclonedx-vulnerability-2.0.schema.json
},
"then": {
"not": { "required": [ "score" ] }
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The EPSS conditional forbids score but requires nothing! An EPSS rating can omit both measurements and timing. This stops EPSS from using score, but { "method": "EPSS" } with no measures is still valid, and so is an EPSS rating with no timestamp. Given the concerns in #481, could the then branch also require measures containing a probability, and possibly a timestamp?

"then": {
  "not": { "required": ["score"] },
  "required": ["measures", "timestamp"],
  "properties": {
    "measures": { "contains": { "properties": { "name": { "const": "probability" } }, "required": ["name"] } }
  }
} 

If requiring timestamp is too strict, a "should" in the description would still help.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lets refine this after the merge.

"format": "date-time",
"title": "Timestamp",
"description": "The date and time the rating was produced or observed. Relevant to methods whose scores are recalculated on a schedule."
},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Produced or observed" covers two different times. For EPSS, FIRST publishes a score for a given date, and a scanner may retrieve it days later. Consumers need the first to judge freshness.
The date and time the method produced this rating. For methods published on a schedule, this is the date of the published score, not the time it was retrieved.

Comment thread schema/2.0/modules/cyclonedx-vulnerability-2.0.schema.json
"type": "number",
"title": "Value",
"description": "The numeric value of the measure."
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

meta:enum says probability and percentile are decimals from 0 to 1, but value is an unbounded number, so probability: 42 validates. A conditional on ratingMeasure could enforce it:

"allOf": [{
  "if": { "properties": { "name": { "enum": ["probability", "percentile", "confidence"] } }, "required": ["name"] },
  "then": { "properties": { "value": { "minimum": 0, "maximum": 1 } } }
}]

@jkowalleck

Copy link
Copy Markdown
Member

RFC notice sent on 18 September 2026.
RFC period ends on 16 October 2026.

@jkowalleck

jkowalleck commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

@stevespringett sometests are failing: https://github.com/CycloneDX/specification/actions/runs/36573034473/job/109421784604?pr=1117#step:5:25

 
> SchemaFile:  /home/runner/work/specification/specification/schema/2.0/cyclonedx-2.0.schema.json
> compile schema, log warnings ...
!!! SCHEMA ERROR: Error: strict mode: required property "score" is not defined at "https://cyclonedx.org/schema/2.0/model/cyclonedx-vulnerability-2.0.schema.json#/allOf/0/then/not" (strictRequired) 

Comment thread schema/2.0/modules/cyclonedx-vulnerability-2.0.schema.json Outdated
Signed-off-by: Steve Springett <steve@springett.us>
…lity) without restricting ourselves specifically to EPSS, or future scoring systems or versions of EPSS.

Signed-off-by: Steve Springett <steve@springett.us>
}
},
{
"title": "Custom Method",

@jkowalleck jkowalleck Oct 15, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would love to see examples for the new "other" in the test suite

stevespringett and others added 5 commits October 15, 2026 16:40
@stevespringett
stevespringett merged commit e8869cf into 2.0-dev Oct 15, 2026
43 of 54 checks passed
@stevespringett
stevespringett deleted the 2.0-dev-epss branch October 15, 2026 21:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

proposed core enhancement request for comment RFC notice sent A public RFC notice was distributed to the CycloneDX mailing list for consideration

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE]: EPSS Score on Vulnerability model

3 participants