Skip to content

Commit 751f6c8

Browse files
alilleybrinkeralilleybrinker
committed
feat: Added "applicability" structure for more Software IDs.
This adds support for Package URLs and OmniBOR Artifact IDs to be embedded in CVE records by introducing a new "applicability" structure for both CNAs and ADPs. This "applicability" structure is intended to replace usage of the existing "cpeApplicability" structure added recently for CPE support. It extends the prior schema of "cpeApplicability" in a backwards-compatible way, defining new "purl_match" and "omnibor_match" structures alongside the existing "match" now renamed "cpe_match". The prior "cpeApplicability" structure remains entirely supported, though CNAs and any future ADPs enriching with software ID information should be encouraged to use the more expressive new "applicability" structure instead, and use of both at the same time should be treated as an error to avoid ambiguity. This also opens the possibility of introducing more software identification schemes in the future by adding new "<schema>_match" variants within the "applicability" structure. Signed-off-by: Andrew Lilley Brinker <[email protected]>
1 parent ddd04fb commit 751f6c8

File tree

1 file changed

+142
-8
lines changed

1 file changed

+142
-8
lines changed

‎schema/CVE_Record_Format.json‎

Lines changed: 142 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,7 @@
212212
},
213213
"cpes": {
214214
"type": "array",
215-
"description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here. NOTE: Consider using the newer cpeApplicability block for defining CPE data using the CPE Applicability Language which includes more options for defining CPE Names.",
215+
"description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here. NOTE: Consider using the newer applicability block for defining CPE data using the CPE Applicability Language which includes more options for defining CPE Names.",
216216
"uniqueItems": true,
217217
"items": {
218218
"title": "CPE Name",
@@ -500,6 +500,118 @@
500500
"required": ["orgId"],
501501
"additionalProperties": false
502502
},
503+
"applicability": {
504+
"type": "array",
505+
"items": {
506+
"$ref": "#/definitions/applicabilityElement"
507+
}
508+
},
509+
"applicabilityElement": {
510+
"description": "Affected products defined using one or more software identifiers and applicability parameters. An operator property allows AND or OR logic between identifiers or combinations thereof. The negate and vulnerable Boolean properties allow applicability combinations to be inverted and/or defined as vulnerable or not. Multiple version fields are provided for capturing ranges of products when defining a Match String Range. NOTE: When defining an applicability block, it is recommended that it align with (as much as possible) the product data provided within the affected block.",
511+
"properties": {
512+
"operator": {
513+
"type": "string",
514+
"enum": ["AND", "OR"]
515+
},
516+
"negate": {
517+
"type": "boolean"
518+
},
519+
"nodes": {
520+
"type": "array",
521+
"items": {
522+
"$ref": "#/definitions/node"
523+
}
524+
}
525+
}
526+
},
527+
"node": {
528+
"description": "Defines a configuration node in an applicability statement.",
529+
"properties": {
530+
"operator": {
531+
"type": "string",
532+
"enum": ["AND", "OR"]
533+
},
534+
"negate": {
535+
"type": "boolean"
536+
},
537+
"cpeMatch": {
538+
"type": "array",
539+
"items": {
540+
"$ref": "#/definitions/cpe_match"
541+
}
542+
},
543+
"purlMatch": {
544+
"type": "array",
545+
"items": {
546+
"$ref": "#/definitions/purl_match"
547+
}
548+
},
549+
"omniborMatch": {
550+
"type": "array",
551+
"items": {
552+
"$ref": "#/definitions/omnibor_match"
553+
}
554+
}
555+
},
556+
"allOf": [
557+
{ "required": ["operator"] },
558+
{
559+
"anyOf": [
560+
{ "required": ["cpeMatch"] },
561+
{ "required": ["purlMatch"] },
562+
{ "required": ["omniborMatch"] }
563+
]
564+
}
565+
]
566+
},
567+
"omnibor_match": {
568+
"description": "OmniBOR match string",
569+
"type": "object",
570+
"properties": {
571+
"vulnerable": {
572+
"type": "boolean"
573+
},
574+
"artifact_id": {
575+
"type": "string"
576+
},
577+
"target": {
578+
"type": "string",
579+
"enum": ["artifact", "build_input"]
580+
}
581+
},
582+
"required": ["vulnerable", "artifact_id"],
583+
"additionalProperties": false
584+
},
585+
"purl_match": {
586+
"description": "purl match string or range",
587+
"type": "object",
588+
"properties": {
589+
"vulnerable": {
590+
"type": "boolean"
591+
},
592+
"criteria": {
593+
"description": "Placeholder until we find a formal purl schema",
594+
"$ref": "#/definitions/uriType"
595+
},
596+
"matchCriteriaId": {
597+
"$ref": "#/definitions/uuidType"
598+
},
599+
"versionStartExcluding": {
600+
"$ref": "#/definitions/version"
601+
},
602+
"versionStartIncluding": {
603+
"$ref": "#/definitions/version"
604+
},
605+
"versionEndExcluding": {
606+
"$ref": "#/definitions/version"
607+
},
608+
"versionEndIncluding": {
609+
"$ref": "#/definitions/version"
610+
}
611+
},
612+
"required": ["vulnerable", "criteria"],
613+
"additionalProperties": false
614+
},
503615
"cpeApplicabilityElement": {
504616
"description": "Affected products defined using an implementation of the CPE Applicability Language, mostly copied/forked from the NIST NVD CVE API v2.0 schema (optional). An operator property allows AND or OR logic between CPEs or combinations of CPEs. The negate and vulnerable Boolean properties allow CPEs to be inverted and/or defined as vulnerable or not. Multiple version fields are provided for capturing ranges of products when defining a CPE Match String Range. NOTE: When defining a cpeApplicability block, it is recommended that it align with (as much as possible) the product data provided within the affected block.",
505617
"properties": {
@@ -654,11 +766,20 @@
654766
"$ref": "#/definitions/taxonomyMappings"
655767
}
656768
},
657-
"required": [
658-
"providerMetadata",
659-
"descriptions",
660-
"affected",
661-
"references"
769+
"allOf": [
770+
{
771+
"required": [
772+
"providerMetadata",
773+
"descriptions",
774+
"affected",
775+
"references"
776+
]
777+
},
778+
{
779+
"not": {
780+
"required": ["applicability", "cpeApplicability"]
781+
}
782+
}
662783
],
663784
"patternProperties": {
664785
"^x_[^.]*$": {}
@@ -720,6 +841,12 @@
720841
"affected": {
721842
"$ref": "#/definitions/affected"
722843
},
844+
"applicability": {
845+
"type": "array",
846+
"items": {
847+
"$ref": "#/definitions/applicabilityElement"
848+
}
849+
},
723850
"cpeApplicability": {
724851
"type": "array",
725852
"items": {
@@ -766,8 +893,15 @@
766893
"$ref": "#/definitions/taxonomyMappings"
767894
}
768895
},
769-
"required": [
770-
"providerMetadata"
896+
"allOf": [
897+
{
898+
"required": ["providerMetadata"]
899+
},
900+
{
901+
"not": {
902+
"required": ["applicability", "cpeApplicability"]
903+
}
904+
}
771905
],
772906
"minProperties": 2,
773907
"patternProperties": {

0 commit comments

Comments
 (0)