1// Copyright 2018 The Grafeas Authors. All rights reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//    http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package grafeas.v1beta1.vulnerability;
18
19import "google/protobuf/timestamp.proto";
20import "google/devtools/containeranalysis/v1beta1/common/common.proto";
21import "google/devtools/containeranalysis/v1beta1/cvss/cvss.proto";
22import "google/devtools/containeranalysis/v1beta1/package/package.proto";
23
24option go_package = "cloud.google.com/go/containeranalysis/apiv1beta1/containeranalysispb;containeranalysispb";
25option java_multiple_files = true;
26option java_package = "io.grafeas.v1beta1.vulnerability";
27option objc_class_prefix = "GRA";
28
29// Note provider-assigned severity/impact ranking.
30enum Severity {
31  // Unknown.
32  SEVERITY_UNSPECIFIED = 0;
33  // Minimal severity.
34  MINIMAL = 1;
35  // Low severity.
36  LOW = 2;
37  // Medium severity.
38  MEDIUM = 3;
39  // High severity.
40  HIGH = 4;
41  // Critical severity.
42  CRITICAL = 5;
43}
44
45// Vulnerability provides metadata about a security vulnerability in a Note.
46message Vulnerability {
47  // The CVSS score for this vulnerability.
48  float cvss_score = 1;
49
50  // Note provider assigned impact of the vulnerability.
51  Severity severity = 2;
52
53  // All information about the package to specifically identify this
54  // vulnerability. One entry per (version range and cpe_uri) the package
55  // vulnerability has manifested in.
56  repeated Detail details = 3;
57
58  // Identifies all appearances of this vulnerability in the package for a
59  // specific distro/location. For example: glibc in
60  // cpe:/o:debian:debian_linux:8 for versions 2.1 - 2.2
61  message Detail {
62    // Required. The CPE URI in
63    // [cpe format](https://cpe.mitre.org/specification/) in which the
64    // vulnerability manifests. Examples include distro or storage location for
65    // vulnerable jar.
66    string cpe_uri = 1;
67
68    // Required. The name of the package where the vulnerability was found.
69    string package = 2;
70
71    // The min version of the package in which the vulnerability exists.
72    grafeas.v1beta1.package.Version min_affected_version = 3;
73
74    // The max version of the package in which the vulnerability exists.
75    grafeas.v1beta1.package.Version max_affected_version = 4;
76
77    // The severity (eg: distro assigned severity) for this vulnerability.
78    string severity_name = 5;
79
80    // A vendor-specific description of this note.
81    string description = 6;
82
83    // The fix for this specific package version.
84    VulnerabilityLocation fixed_location = 7;
85
86    // The type of package; whether native or non native(ruby gems, node.js
87    // packages etc).
88    string package_type = 8;
89
90    // Whether this detail is obsolete. Occurrences are expected not to point to
91    // obsolete details.
92    bool is_obsolete = 9;
93
94    // The time this information was last changed at the source. This is an
95    // upstream timestamp from the underlying information source - e.g. Ubuntu
96    // security tracker.
97    google.protobuf.Timestamp source_update_time = 10;
98  }
99
100  // The full description of the CVSSv3.
101  CVSSv3 cvss_v3 = 4;
102
103  // Windows details get their own format because the information format and
104  // model don't match a normal detail. Specifically Windows updates are done as
105  // patches, thus Windows vulnerabilities really are a missing package, rather
106  // than a package being at an incorrect version.
107  repeated WindowsDetail windows_details = 5;
108
109  message WindowsDetail {
110    // Required. The CPE URI in
111    // [cpe format](https://cpe.mitre.org/specification/) in which the
112    // vulnerability manifests. Examples include distro or storage location for
113    // vulnerable jar.
114    string cpe_uri = 1;
115
116    // Required. The name of the vulnerability.
117    string name = 2;
118
119    // The description of the vulnerability.
120    string description = 3;
121
122    // Required. The names of the KBs which have hotfixes to mitigate this
123    // vulnerability. Note that there may be multiple hotfixes (and thus
124    // multiple KBs) that mitigate a given vulnerability. Currently any listed
125    // kb's presence is considered a fix.
126    repeated KnowledgeBase fixing_kbs = 4;
127
128    message KnowledgeBase {
129      // The KB name (generally of the form KB[0-9]+ i.e. KB123456).
130      string name = 1;
131      // A link to the KB in the Windows update catalog -
132      // https://www.catalog.update.microsoft.com/
133      string url = 2;
134    }
135  }
136
137  // The time this information was last changed at the source. This is an
138  // upstream timestamp from the underlying information source - e.g. Ubuntu
139  // security tracker.
140  google.protobuf.Timestamp source_update_time = 6;
141
142  // Next free ID is 7.
143}
144
145// Details of a vulnerability Occurrence.
146message Details {
147  // The type of package; whether native or non native(ruby gems, node.js
148  // packages etc)
149  string type = 1;
150
151  // Output only. The note provider assigned Severity of the vulnerability.
152  Severity severity = 2;
153
154  // Output only. The CVSS score of this vulnerability. CVSS score is on a
155  // scale of 0-10 where 0 indicates low severity and 10 indicates high
156  // severity.
157  float cvss_score = 3;
158
159  // Required. The set of affected locations and their fixes (if available)
160  // within the associated resource.
161  repeated PackageIssue package_issue = 4;
162
163  // Output only. A one sentence description of this vulnerability.
164  string short_description = 5;
165
166  // Output only. A detailed description of this vulnerability.
167  string long_description = 6;
168
169  // Output only. URLs related to this vulnerability.
170  repeated grafeas.v1beta1.RelatedUrl related_urls = 7;
171
172  // The distro assigned severity for this vulnerability when it is
173  // available, and note provider assigned severity when distro has not yet
174  // assigned a severity for this vulnerability.
175  Severity effective_severity = 8;
176}
177
178// This message wraps a location affected by a vulnerability and its
179// associated fix (if one is available).
180message PackageIssue {
181  // Required. The location of the vulnerability.
182  VulnerabilityLocation affected_location = 1;
183
184  // The location of the available fix for vulnerability.
185  VulnerabilityLocation fixed_location = 2;
186
187  // Deprecated, use Details.effective_severity instead
188  // The severity (e.g., distro assigned severity) for this vulnerability.
189  string severity_name = 3;
190}
191
192// The location of the vulnerability.
193message VulnerabilityLocation {
194  // Required. The CPE URI in [cpe format](https://cpe.mitre.org/specification/)
195  // format. Examples include distro or storage location for vulnerable jar.
196  string cpe_uri = 1;
197
198  // Required. The package being described.
199  string package = 2;
200
201  // Required. The version of the package being described.
202  grafeas.v1beta1.package.Version version = 3;
203}
204