feat: [containeranalysis] 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

packages/google-devtools-containeranalysis/protos/grafeas/v1/common.proto

@@ -45,6 +45,8 @@ enum NoteKind {
   COMPLIANCE = 9;
   // This represents a DSSE attestation Note
   DSSE_ATTESTATION = 10;
+  // This represents a Vulnerability Assessment.
+  VULNERABILITY_ASSESSMENT = 11;
 }
 
 // Metadata for any related URL information.

packages/google-devtools-containeranalysis/protos/grafeas/v1/grafeas.proto

@@ -33,6 +33,7 @@ import "grafeas/v1/dsse_attestation.proto";
 import "grafeas/v1/image.proto";
 import "grafeas/v1/package.proto";
 import "grafeas/v1/upgrade.proto";
+import "grafeas/v1/vex.proto";
 import "grafeas/v1/vulnerability.proto";
 
 option go_package = "google.golang.org/genproto/googleapis/grafeas/v1;grafeas";
@@ -314,6 +315,8 @@ message Note {
     grafeas.v1.ComplianceNote compliance = 18;
     // A note describing a dsse attestation note.
     grafeas.v1.DSSEAttestationNote dsse_attestation = 19;
+    // A note describing a vulnerability assessment.
+    grafeas.v1.VulnerabilityAssessmentNote vulnerability_assessment = 20;
   }
 }
 

packages/google-devtools-containeranalysis/protos/grafeas/v1/vex.proto

@@ -0,0 +1,203 @@
+// Copyright 2023 The Grafeas Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package grafeas.v1;
+
+import "grafeas/v1/common.proto";
+
+option go_package = "google.golang.org/genproto/googleapis/grafeas/v1;grafeas";
+option java_multiple_files = true;
+option java_package = "io.grafeas.v1";
+option objc_class_prefix = "GRA";
+
+// A single VulnerabilityAssessmentNote represents
+// one particular product's vulnerability assessment for one CVE.
+message VulnerabilityAssessmentNote {
+  // The title of the note. E.g. `Vex-Debian-11.4`
+  string title = 1;
+
+  // A one sentence description of this Vex.
+  string short_description = 2;
+
+  // A detailed description of this Vex.
+  string long_description = 3;
+
+  // Identifies the language used by this document,
+  // corresponding to IETF BCP 47 / RFC 5646.
+  string language_code = 4;
+
+  // Publisher contains information about the publisher of
+  // this Note.
+  // (-- api-linter: core::0123::resource-annotation=disabled
+  //     aip.dev/not-precedent: Publisher is not a separate resource. --)
+  message Publisher {
+    // Name of the publisher.
+    // Examples: 'Google', 'Google Cloud Platform'.
+    string name = 1;
+
+    // Provides information about the authority of the issuing party to
+    // release the document, in particular, the party's constituency and
+    // responsibilities or other obligations.
+    string issuing_authority = 2;
+
+    // The context or namespace.
+    // Contains a URL which is under control of the issuing party and can
+    // be used as a globally unique identifier for that issuing party.
+    // Example: https://csaf.io
+    string publisher_namespace = 3;
+  }
+
+  // Publisher details of this Note.
+  Publisher publisher = 5;
+
+  // Product contains information about a product and how to uniquely identify
+  // it.
+  // (-- api-linter: core::0123::resource-annotation=disabled
+  //     aip.dev/not-precedent: Product is not a separate resource. --)
+  message Product {
+    // Name of the product.
+    string name = 1;
+
+    // Token that identifies a product so that it can be referred to from other
+    // parts in the document. There is no predefined format as long as it
+    // uniquely identifies a group in the context of the current document.
+    string id = 2;
+
+    oneof identifier {
+      // Contains a URI which is vendor-specific.
+      // Example: The artifact repository URL of an image.
+      string generic_uri = 3;
+    }
+  }
+
+  // The product affected by this vex.
+  Product product = 6;
+
+  // Assessment provides all information that is related to a single
+  // vulnerability for this product.
+  message Assessment {
+    // Holds the MITRE standard Common Vulnerabilities and Exposures (CVE)
+    // tracking number for the vulnerability.
+    string cve = 1;
+
+    // A one sentence description of this Vex.
+    string short_description = 2;
+
+    // A detailed description of this Vex.
+    string long_description = 3;
+
+    // Holds a list of references associated with this vulnerability item and
+    // assessment. These uris have additional information about the
+    // vulnerability and the assessment itself. E.g. Link to a document which
+    // details how this assessment concluded the state of this vulnerability.
+    repeated grafeas.v1.RelatedUrl related_uris = 4;
+
+    // Provides the state of this Vulnerability assessment.
+    enum State {
+      // No state is specified.
+      STATE_UNSPECIFIED = 0;
+      // This product is known to be affected by this vulnerability.
+      AFFECTED = 1;
+      // This product is known to be not affected by this vulnerability.
+      NOT_AFFECTED = 2;
+      // This product contains a fix for this vulnerability.
+      FIXED = 3;
+      // It is not known yet whether these versions are or are not affected
+      // by the vulnerability. However, it is still under investigation.
+      UNDER_INVESTIGATION = 4;
+    }
+
+    // Provides the state of this Vulnerability assessment.
+    State state = 5;
+
+    // Contains information about the impact of this vulnerability,
+    // this will change with time.
+    repeated string impacts = 6;
+
+    // Justification provides the justification when the state of the
+    // assessment if NOT_AFFECTED.
+    message Justification {
+      // Provides the type of justification.
+      enum JustificationType {
+        // JUSTIFICATION_TYPE_UNSPECIFIED.
+        JUSTIFICATION_TYPE_UNSPECIFIED = 0;
+        // The vulnerable component is not present in the product.
+        COMPONENT_NOT_PRESENT = 1;
+        // The vulnerable code is not present. Typically this case
+        // occurs when source code is configured or built in a way that excludes
+        // the vulnerable code.
+        VULNERABLE_CODE_NOT_PRESENT = 2;
+        // The vulnerable code can not be executed.
+        // Typically this case occurs when the product includes the vulnerable
+        // code but does not call or use the vulnerable code.
+        VULNERABLE_CODE_NOT_IN_EXECUTE_PATH = 3;
+        // The vulnerable code cannot be controlled by an attacker to exploit
+        // the vulnerability.
+        VULNERABLE_CODE_CANNOT_BE_CONTROLLED_BY_ADVERSARY = 4;
+        // The product includes built-in protections or features that prevent
+        // exploitation of the vulnerability. These built-in protections cannot
+        // be subverted by the attacker and cannot be configured or disabled by
+        // the user. These mitigations completely prevent exploitation based on
+        // known attack vectors.
+        INLINE_MITIGATIONS_ALREADY_EXIST = 5;
+      }
+
+      // The justification type for this vulnerability.
+      JustificationType justification_type = 1;
+
+      // Additional details on why this justification was chosen.
+      string details = 2;
+    }
+
+    // Justification provides the justification when the state of the
+    // assessment if NOT_AFFECTED.
+    Justification justification = 7;
+
+    // Specifies details on how to handle (and presumably, fix) a vulnerability.
+    message Remediation {
+      // The type of remediation that can be applied.
+      enum RemediationType {
+        // No remediation type specified.
+        REMEDIATION_TYPE_UNSPECIFIED = 0;
+        // A MITIGATION is available.
+        MITIGATION = 1;
+        // No fix is planned.
+        NO_FIX_PLANNED = 2;
+        // Not available.
+        NONE_AVAILABLE = 3;
+        // A vendor fix is available.
+        VENDOR_FIX = 4;
+        // A workaround is available.
+        WORKAROUND = 5;
+      }
+
+      // The type of remediation that can be applied.
+      RemediationType remediation_type = 1;
+
+      // Contains a comprehensive human-readable discussion of the remediation.
+      string details = 2;
+
+      // Contains the URL where to obtain the remediation.
+      grafeas.v1.RelatedUrl remediation_uri = 3;
+    }
+
+    // Specifies details on how to handle (and presumably, fix) a vulnerability.
+    repeated Remediation remediations = 8;
+  }
+
+  // Represents a vulnerability assessment for the product.
+  Assessment assessment = 7;
+}

packages/google-devtools-containeranalysis/protos/grafeas/v1/vulnerability.proto

@@ -22,6 +22,7 @@ import "grafeas/v1/common.proto";
 import "grafeas/v1/cvss.proto";
 import "grafeas/v1/package.proto";
 import "grafeas/v1/severity.proto";
+import "grafeas/v1/vex.proto";
 
 option go_package = "google.golang.org/genproto/googleapis/grafeas/v1;grafeas";
 option java_multiple_files = true;
@@ -253,5 +254,44 @@ message VulnerabilityOccurrence {
   // The cvss v2 score for the vulnerability.
   CVSS cvss_v2 = 12;
 
-  // Next free ID is 13.
+  // VexAssessment provides all publisher provided Vex information that is
+  // related to this vulnerability.
+  message VexAssessment {
+    // Holds the MITRE standard Common Vulnerabilities and Exposures (CVE)
+    // tracking number for the vulnerability.
+    string cve = 1;
+
+    // Holds a list of references associated with this vulnerability item and
+    // assessment.
+    repeated grafeas.v1.RelatedUrl related_uris = 2;
+
+    // The VulnerabilityAssessment note from which this VexAssessment was
+    // generated.
+    // This will be of the form: `projects/[PROJECT_ID]/notes/[NOTE_ID]`.
+    // (-- api-linter: core::0122::name-suffix=disabled
+    //     aip.dev/not-precedent: The suffix is kept for consistency. --)
+    string note_name = 3;
+
+    // Provides the state of this Vulnerability assessment.
+    grafeas.v1.VulnerabilityAssessmentNote.Assessment.State state = 4;
+
+    // Contains information about the impact of this vulnerability,
+    // this will change with time.
+    repeated string impacts = 5;
+
+    // Specifies details on how to handle (and presumably, fix) a vulnerability.
+    repeated grafeas.v1.VulnerabilityAssessmentNote.Assessment.Remediation
+        remediations = 6;
+
+    // Justification provides the justification when the state of the
+    // assessment if NOT_AFFECTED.
+    grafeas.v1.VulnerabilityAssessmentNote.Assessment.Justification
+        justification = 7;
+
+    // Next ID: 8
+  }
+
+  VexAssessment vex_assessment = 13;
+
+  // Next free ID is 14.
 }