Skip to content

Commit a4e6205

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: Add VULNERABILITY_ASSESSMENT Note type to grafeas v1 API, adds Vex_Assessment derived from the Note to resources' occurrences, VEX notes now be written to add CVE assessments
PiperOrigin-RevId: 515727862
1 parent e2388a3 commit a4e6205

6 files changed

Lines changed: 490 additions & 3 deletions

File tree

‎grafeas/v1/BUILD.bazel‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ proto_library(
3939
"slsa_provenance.proto",
4040
"slsa_provenance_zero_two.proto",
4141
"upgrade.proto",
42+
"vex.proto",
4243
"vulnerability.proto",
4344
],
4445
deps = [

‎grafeas/v1/common.proto‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@ enum NoteKind {
4545
COMPLIANCE = 9;
4646
// This represents a DSSE attestation Note
4747
DSSE_ATTESTATION = 10;
48+
// This represents a Vulnerability Assessment.
49+
VULNERABILITY_ASSESSMENT = 11;
4850
}
4951

5052
// Metadata for any related URL information.

‎grafeas/v1/grafeas.proto‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ import "grafeas/v1/dsse_attestation.proto";
3333
import "grafeas/v1/image.proto";
3434
import "grafeas/v1/package.proto";
3535
import "grafeas/v1/upgrade.proto";
36+
import "grafeas/v1/vex.proto";
3637
import "grafeas/v1/vulnerability.proto";
3738

3839
option go_package = "google.golang.org/genproto/googleapis/grafeas/v1;grafeas";
@@ -314,6 +315,8 @@ message Note {
314315
grafeas.v1.ComplianceNote compliance = 18;
315316
// A note describing a dsse attestation note.
316317
grafeas.v1.DSSEAttestationNote dsse_attestation = 19;
318+
// A note describing a vulnerability assessment.
319+
grafeas.v1.VulnerabilityAssessmentNote vulnerability_assessment = 20;
317320
}
318321
}
319322

‎grafeas/v1/swagger/grafeas.swagger.json‎

Lines changed: 240 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -796,6 +796,50 @@
796796
"default": "KIND_UNSPECIFIED",
797797
"description": "The type of an alias.\n\n - KIND_UNSPECIFIED: Unknown.\n - FIXED: Git tag.\n - MOVABLE: Git branch.\n - OTHER: Used to specify non-standard aliases. For example, if a Git repo has a\nref named \"refs/foo/bar\"."
798798
},
799+
"AssessmentJustification": {
800+
"type": "object",
801+
"properties": {
802+
"justificationType": {
803+
"$ref": "#/definitions/JustificationJustificationType",
804+
"description": "The justification type for this vulnerability."
805+
},
806+
"details": {
807+
"type": "string",
808+
"description": "Additional details on why this justification was chosen."
809+
}
810+
},
811+
"description": "Justification provides the justification when the state of the\nassessment if NOT_AFFECTED."
812+
},
813+
"AssessmentRemediation": {
814+
"type": "object",
815+
"properties": {
816+
"remediationType": {
817+
"$ref": "#/definitions/RemediationRemediationType",
818+
"description": "The type of remediation that can be applied."
819+
},
820+
"details": {
821+
"type": "string",
822+
"description": "Contains a comprehensive human-readable discussion of the remediation."
823+
},
824+
"remediationUri": {
825+
"$ref": "#/definitions/v1RelatedUrl",
826+
"description": "Contains the URL where to obtain the remediation."
827+
}
828+
},
829+
"description": "Specifies details on how to handle (and presumably, fix) a vulnerability."
830+
},
831+
"AssessmentState": {
832+
"type": "string",
833+
"enum": [
834+
"STATE_UNSPECIFIED",
835+
"AFFECTED",
836+
"NOT_AFFECTED",
837+
"FIXED",
838+
"UNDER_INVESTIGATION"
839+
],
840+
"default": "STATE_UNSPECIFIED",
841+
"description": "Provides the state of this Vulnerability assessment.\n\n - STATE_UNSPECIFIED: No state is specified.\n - AFFECTED: This product is known to be affected by this vulnerability.\n - NOT_AFFECTED: This product is known to be not affected by this vulnerability.\n - FIXED: This product contains a fix for this vulnerability.\n - UNDER_INVESTIGATION: It is not known yet whether these versions are or are not affected\nby the vulnerability. However, it is still under investigation."
842+
},
799843
"AttestationNoteHint": {
800844
"type": "object",
801845
"properties": {
@@ -886,6 +930,32 @@
886930
"default": "CONTINUOUS_ANALYSIS_UNSPECIFIED",
887931
"description": "Whether the resource is continuously analyzed.\n\n - CONTINUOUS_ANALYSIS_UNSPECIFIED: Unknown.\n - ACTIVE: The resource is continuously analyzed.\n - INACTIVE: The resource is ignored for continuous analysis."
888932
},
933+
"JustificationJustificationType": {
934+
"type": "string",
935+
"enum": [
936+
"JUSTIFICATION_TYPE_UNSPECIFIED",
937+
"COMPONENT_NOT_PRESENT",
938+
"VULNERABLE_CODE_NOT_PRESENT",
939+
"VULNERABLE_CODE_NOT_IN_EXECUTE_PATH",
940+
"VULNERABLE_CODE_CANNOT_BE_CONTROLLED_BY_ADVERSARY",
941+
"INLINE_MITIGATIONS_ALREADY_EXIST"
942+
],
943+
"default": "JUSTIFICATION_TYPE_UNSPECIFIED",
944+
"description": "Provides the type of justification.\n\n - JUSTIFICATION_TYPE_UNSPECIFIED: JUSTIFICATION_TYPE_UNSPECIFIED.\n - COMPONENT_NOT_PRESENT: The vulnerable component is not present in the product.\n - VULNERABLE_CODE_NOT_PRESENT: The vulnerable code is not present. Typically this case\noccurs when source code is configured or built in a way that excludes\nthe vulnerable code.\n - VULNERABLE_CODE_NOT_IN_EXECUTE_PATH: The vulnerable code can not be executed.\nTypically this case occurs when the product includes the vulnerable\ncode but does not call or use the vulnerable code.\n - VULNERABLE_CODE_CANNOT_BE_CONTROLLED_BY_ADVERSARY: The vulnerable code cannot be controlled by an attacker to exploit\nthe vulnerability.\n - INLINE_MITIGATIONS_ALREADY_EXIST: The product includes built-in protections or features that prevent\nexploitation of the vulnerability. These built-in protections cannot\nbe subverted by the attacker and cannot be configured or disabled by\nthe user. These mitigations completely prevent exploitation based on\nknown attack vectors."
945+
},
946+
"RemediationRemediationType": {
947+
"type": "string",
948+
"enum": [
949+
"REMEDIATION_TYPE_UNSPECIFIED",
950+
"MITIGATION",
951+
"NO_FIX_PLANNED",
952+
"NONE_AVAILABLE",
953+
"VENDOR_FIX",
954+
"WORKAROUND"
955+
],
956+
"default": "REMEDIATION_TYPE_UNSPECIFIED",
957+
"description": "The type of remediation that can be applied.\n\n - REMEDIATION_TYPE_UNSPECIFIED: No remediation type specified.\n - MITIGATION: A MITIGATION is available.\n - NO_FIX_PLANNED: No fix is planned.\n - NONE_AVAILABLE: Not available.\n - VENDOR_FIX: A vendor fix is available.\n - WORKAROUND: A workaround is available."
958+
},
889959
"SlsaProvenanceMaterial": {
890960
"type": "object",
891961
"properties": {
@@ -986,6 +1056,89 @@
9861056
"default": "VERSION_KIND_UNSPECIFIED",
9871057
"description": "Whether this is an ordinary package version or a sentinel MIN/MAX version.\n\n - VERSION_KIND_UNSPECIFIED: Unknown.\n - NORMAL: A standard package version.\n - MINIMUM: A special version representing negative infinity.\n - MAXIMUM: A special version representing positive infinity."
9881058
},
1059+
"VulnerabilityAssessmentNoteAssessment": {
1060+
"type": "object",
1061+
"properties": {
1062+
"cve": {
1063+
"type": "string",
1064+
"description": "Holds the MITRE standard Common Vulnerabilities and Exposures (CVE)\ntracking number for the vulnerability."
1065+
},
1066+
"shortDescription": {
1067+
"type": "string",
1068+
"description": "A one sentence description of this Vex."
1069+
},
1070+
"longDescription": {
1071+
"type": "string",
1072+
"description": "A detailed description of this Vex."
1073+
},
1074+
"relatedUris": {
1075+
"type": "array",
1076+
"items": {
1077+
"$ref": "#/definitions/v1RelatedUrl"
1078+
},
1079+
"description": "Holds a list of references associated with this vulnerability item and\nassessment. These uris have additional information about the\nvulnerability and the assessment itself. E.g. Link to a document which\ndetails how this assessment concluded the state of this vulnerability."
1080+
},
1081+
"state": {
1082+
"$ref": "#/definitions/AssessmentState",
1083+
"description": "Provides the state of this Vulnerability assessment."
1084+
},
1085+
"impacts": {
1086+
"type": "array",
1087+
"items": {
1088+
"type": "string"
1089+
},
1090+
"description": "Contains information about the impact of this vulnerability,\nthis will change with time."
1091+
},
1092+
"justification": {
1093+
"$ref": "#/definitions/AssessmentJustification",
1094+
"description": "Justification provides the justification when the state of the\nassessment if NOT_AFFECTED."
1095+
},
1096+
"remediations": {
1097+
"type": "array",
1098+
"items": {
1099+
"$ref": "#/definitions/AssessmentRemediation"
1100+
},
1101+
"description": "Specifies details on how to handle (and presumably, fix) a vulnerability."
1102+
}
1103+
},
1104+
"description": "Assessment provides all information that is related to a single\nvulnerability for this product."
1105+
},
1106+
"VulnerabilityAssessmentNoteProduct": {
1107+
"type": "object",
1108+
"properties": {
1109+
"name": {
1110+
"type": "string",
1111+
"description": "Name of the product."
1112+
},
1113+
"id": {
1114+
"type": "string",
1115+
"description": "Token that identifies a product so that it can be referred to from other\nparts in the document. There is no predefined format as long as it\nuniquely identifies a group in the context of the current document."
1116+
},
1117+
"genericUri": {
1118+
"type": "string",
1119+
"description": "Contains a URI which is vendor-specific.\nExample: The artifact repository URL of an image."
1120+
}
1121+
},
1122+
"title": "Product contains information about a product and how to uniquely identify\nit.\n(-- api-linter: core::0123::resource-annotation=disabled\n aip.dev/not-precedent: Product is not a separate resource. --)"
1123+
},
1124+
"VulnerabilityAssessmentNotePublisher": {
1125+
"type": "object",
1126+
"properties": {
1127+
"name": {
1128+
"type": "string",
1129+
"description": "Name of the publisher.\nExamples: 'Google', 'Google Cloud Platform'."
1130+
},
1131+
"issuingAuthority": {
1132+
"type": "string",
1133+
"description": "Provides information about the authority of the issuing party to\nrelease the document, in particular, the party's constituency and\nresponsibilities or other obligations."
1134+
},
1135+
"publisherNamespace": {
1136+
"type": "string",
1137+
"title": "The context or namespace.\nContains a URL which is under control of the issuing party and can\nbe used as a globally unique identifier for that issuing party.\nExample: https://csaf.io"
1138+
}
1139+
},
1140+
"title": "Publisher contains information about the publisher of\nthis Note.\n(-- api-linter: core::0123::resource-annotation=disabled\n aip.dev/not-precedent: Publisher is not a separate resource. --)"
1141+
},
9891142
"VulnerabilityNoteDetail": {
9901143
"type": "object",
9911144
"properties": {
@@ -1123,6 +1276,49 @@
11231276
},
11241277
"description": "A detail for a distro and package this vulnerability occurrence was found in\nand its associated fix (if one is available)."
11251278
},
1279+
"VulnerabilityOccurrenceVexAssessment": {
1280+
"type": "object",
1281+
"properties": {
1282+
"cve": {
1283+
"type": "string",
1284+
"description": "Holds the MITRE standard Common Vulnerabilities and Exposures (CVE)\ntracking number for the vulnerability."
1285+
},
1286+
"relatedUris": {
1287+
"type": "array",
1288+
"items": {
1289+
"$ref": "#/definitions/v1RelatedUrl"
1290+
},
1291+
"description": "Holds a list of references associated with this vulnerability item and\nassessment."
1292+
},
1293+
"noteName": {
1294+
"type": "string",
1295+
"title": "The VulnerabilityAssessment note from which this VexAssessment was\ngenerated.\nThis will be of the form: `projects/[PROJECT_ID]/notes/[NOTE_ID]`.\n(-- api-linter: core::0122::name-suffix=disabled\n aip.dev/not-precedent: The suffix is kept for consistency. --)"
1296+
},
1297+
"state": {
1298+
"$ref": "#/definitions/AssessmentState",
1299+
"description": "Provides the state of this Vulnerability assessment."
1300+
},
1301+
"impacts": {
1302+
"type": "array",
1303+
"items": {
1304+
"type": "string"
1305+
},
1306+
"description": "Contains information about the impact of this vulnerability,\nthis will change with time."
1307+
},
1308+
"remediations": {
1309+
"type": "array",
1310+
"items": {
1311+
"$ref": "#/definitions/AssessmentRemediation"
1312+
},
1313+
"description": "Specifies details on how to handle (and presumably, fix) a vulnerability."
1314+
},
1315+
"justification": {
1316+
"$ref": "#/definitions/AssessmentJustification",
1317+
"description": "Justification provides the justification when the state of the\nassessment if NOT_AFFECTED."
1318+
}
1319+
},
1320+
"description": "VexAssessment provides all publisher provided Vex information that is\nrelated to this vulnerability."
1321+
},
11261322
"WindowsDetailKnowledgeBase": {
11271323
"type": "object",
11281324
"properties": {
@@ -2453,6 +2649,10 @@
24532649
"dsseAttestation": {
24542650
"$ref": "#/definitions/v1DSSEAttestationNote",
24552651
"description": "A note describing a dsse attestation note."
2652+
},
2653+
"vulnerabilityAssessment": {
2654+
"$ref": "#/definitions/v1VulnerabilityAssessmentNote",
2655+
"description": "A note describing a vulnerability assessment."
24562656
}
24572657
},
24582658
"description": "A type of analysis that can be done for a resource."
@@ -2470,10 +2670,11 @@
24702670
"ATTESTATION",
24712671
"UPGRADE",
24722672
"COMPLIANCE",
2473-
"DSSE_ATTESTATION"
2673+
"DSSE_ATTESTATION",
2674+
"VULNERABILITY_ASSESSMENT"
24742675
],
24752676
"default": "NOTE_KIND_UNSPECIFIED",
2476-
"description": "Kind represents the kinds of notes supported.\n\n - NOTE_KIND_UNSPECIFIED: Default value. This value is unused.\n - VULNERABILITY: The note and occurrence represent a package vulnerability.\n - BUILD: The note and occurrence assert build provenance.\n - IMAGE: This represents an image basis relationship.\n - PACKAGE: This represents a package installed via a package manager.\n - DEPLOYMENT: The note and occurrence track deployment events.\n - DISCOVERY: The note and occurrence track the initial discovery status of a resource.\n - ATTESTATION: This represents a logical \"role\" that can attest to artifacts.\n - UPGRADE: This represents an available package upgrade.\n - COMPLIANCE: This represents a Compliance Note\n - DSSE_ATTESTATION: This represents a DSSE attestation Note"
2677+
"description": "Kind represents the kinds of notes supported.\n\n - NOTE_KIND_UNSPECIFIED: Default value. This value is unused.\n - VULNERABILITY: The note and occurrence represent a package vulnerability.\n - BUILD: The note and occurrence assert build provenance.\n - IMAGE: This represents an image basis relationship.\n - PACKAGE: This represents a package installed via a package manager.\n - DEPLOYMENT: The note and occurrence track deployment events.\n - DISCOVERY: The note and occurrence track the initial discovery status of a resource.\n - ATTESTATION: This represents a logical \"role\" that can attest to artifacts.\n - UPGRADE: This represents an available package upgrade.\n - COMPLIANCE: This represents a Compliance Note\n - DSSE_ATTESTATION: This represents a DSSE attestation Note\n - VULNERABILITY_ASSESSMENT: This represents a Vulnerability Assessment."
24772678
},
24782679
"v1Occurrence": {
24792680
"type": "object",
@@ -3090,6 +3291,40 @@
30903291
},
30913292
"description": "Version contains structured information about the version of a package."
30923293
},
3294+
"v1VulnerabilityAssessmentNote": {
3295+
"type": "object",
3296+
"properties": {
3297+
"title": {
3298+
"type": "string",
3299+
"title": "The title of the note. E.g. `Vex-Debian-11.4`"
3300+
},
3301+
"shortDescription": {
3302+
"type": "string",
3303+
"description": "A one sentence description of this Vex."
3304+
},
3305+
"longDescription": {
3306+
"type": "string",
3307+
"description": "A detailed description of this Vex."
3308+
},
3309+
"languageCode": {
3310+
"type": "string",
3311+
"description": "Identifies the language used by this document,\ncorresponding to IETF BCP 47 / RFC 5646."
3312+
},
3313+
"publisher": {
3314+
"$ref": "#/definitions/VulnerabilityAssessmentNotePublisher",
3315+
"description": "Publisher details of this Note."
3316+
},
3317+
"product": {
3318+
"$ref": "#/definitions/VulnerabilityAssessmentNoteProduct",
3319+
"description": "The product affected by this vex."
3320+
},
3321+
"assessment": {
3322+
"$ref": "#/definitions/VulnerabilityAssessmentNoteAssessment",
3323+
"description": "Represents a vulnerability assessment for the product."
3324+
}
3325+
},
3326+
"description": "A single VulnerabilityAssessmentNote represents\none particular product's vulnerability assessment for one CVE."
3327+
},
30933328
"v1VulnerabilityNote": {
30943329
"type": "object",
30953330
"properties": {
@@ -3200,6 +3435,9 @@
32003435
"cvssV2": {
32013436
"$ref": "#/definitions/v1CVSS",
32023437
"description": "The cvss v2 score for the vulnerability."
3438+
},
3439+
"vexAssessment": {
3440+
"$ref": "#/definitions/VulnerabilityOccurrenceVexAssessment"
32033441
}
32043442
},
32053443
"description": "An occurrence of a severity vulnerability on a resource."

0 commit comments

Comments
 (0)