vulnerability.proto 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337
  1. // Copyright 2021 Google LLC
  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. syntax = "proto3";
  15. package google.cloud.osconfig.v1alpha;
  16. import "google/api/field_behavior.proto";
  17. import "google/api/resource.proto";
  18. import "google/protobuf/timestamp.proto";
  19. option csharp_namespace = "Google.Cloud.OsConfig.V1Alpha";
  20. option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/v1alpha;osconfig";
  21. option java_multiple_files = true;
  22. option java_outer_classname = "VulnerabilityProto";
  23. option java_package = "com.google.cloud.osconfig.v1alpha";
  24. option php_namespace = "Google\\Cloud\\OsConfig\\V1alpha";
  25. option ruby_package = "Google::Cloud::OsConfig::V1alpha";
  26. // This API resource represents the vulnerability report for a specified
  27. // Compute Engine virtual machine (VM) instance at a given point in time.
  28. //
  29. // For more information, see [Vulnerability
  30. // reports](https://cloud.google.com/compute/docs/instances/os-inventory-management#vulnerability-reports).
  31. message VulnerabilityReport {
  32. option (google.api.resource) = {
  33. type: "osconfig.googleapis.com/VulnerabilityReport"
  34. pattern: "projects/{project}/locations/{location}/instances/{instance}/vulnerabilityReport"
  35. };
  36. // A vulnerability affecting the VM instance.
  37. message Vulnerability {
  38. // Contains metadata information for the vulnerability. This information is
  39. // collected from the upstream feed of the operating system.
  40. message Details {
  41. // A reference for this vulnerability.
  42. message Reference {
  43. // The url of the reference.
  44. string url = 1;
  45. }
  46. // The CVE of the vulnerability. CVE cannot be
  47. // empty and the combination of <cve, classification> should be unique
  48. // across vulnerabilities for a VM.
  49. string cve = 1;
  50. // The CVSS V2 score of this vulnerability. CVSS V2 score is on a scale of
  51. // 0 - 10 where 0 indicates low severity and 10 indicates high severity.
  52. float cvss_v2_score = 2;
  53. // The full description of the CVSSv3 for this vulnerability from NVD.
  54. CVSSv3 cvss_v3 = 3;
  55. // Assigned severity/impact ranking from the distro.
  56. string severity = 4;
  57. // The note or description describing the vulnerability from the distro.
  58. string description = 5;
  59. // Corresponds to the references attached to the `VulnerabilityDetails`.
  60. repeated Reference references = 6;
  61. }
  62. // Contains metadata as per the upstream feed of the operating system and
  63. // NVD.
  64. Details details = 1;
  65. // Corresponds to the `INSTALLED_PACKAGE` inventory item on the VM.
  66. // This field displays the inventory items affected by this vulnerability.
  67. // If the vulnerability report was not updated after the VM inventory
  68. // update, these values might not display in VM inventory. For some distros,
  69. // this field may be empty.
  70. repeated string installed_inventory_item_ids = 2;
  71. // Corresponds to the `AVAILABLE_PACKAGE` inventory item on the VM.
  72. // If the vulnerability report was not updated after the VM inventory
  73. // update, these values might not display in VM inventory. If there is no
  74. // available fix, the field is empty. The `inventory_item` value specifies
  75. // the latest `SoftwarePackage` available to the VM that fixes the
  76. // vulnerability.
  77. repeated string available_inventory_item_ids = 3;
  78. // The timestamp for when the vulnerability was first detected.
  79. google.protobuf.Timestamp create_time = 4;
  80. // The timestamp for when the vulnerability was last modified.
  81. google.protobuf.Timestamp update_time = 5;
  82. }
  83. // Output only. The `vulnerabilityReport` API resource name.
  84. //
  85. // Format:
  86. // `projects/{project_number}/locations/{location}/instances/{instance_id}/vulnerabilityReport`
  87. string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  88. // Output only. List of vulnerabilities affecting the VM.
  89. repeated Vulnerability vulnerabilities = 2
  90. [(google.api.field_behavior) = OUTPUT_ONLY];
  91. // Output only. The timestamp for when the last vulnerability report was
  92. // generated for the VM.
  93. google.protobuf.Timestamp update_time = 3
  94. [(google.api.field_behavior) = OUTPUT_ONLY];
  95. }
  96. // A request message for getting the vulnerability report for the specified VM.
  97. message GetVulnerabilityReportRequest {
  98. // Required. API resource name for vulnerability resource.
  99. //
  100. // Format:
  101. // `projects/{project}/locations/{location}/instances/{instance}/vulnerabilityReport`
  102. //
  103. // For `{project}`, either `project-number` or `project-id` can be provided.
  104. // For `{instance}`, either Compute Engine `instance-id` or `instance-name`
  105. // can be provided.
  106. string name = 1 [
  107. (google.api.field_behavior) = REQUIRED,
  108. (google.api.resource_reference) = {
  109. type: "osconfig.googleapis.com/VulnerabilityReport"
  110. }
  111. ];
  112. }
  113. // A request message for listing vulnerability reports for all VM instances in
  114. // the specified location.
  115. message ListVulnerabilityReportsRequest {
  116. // Required. The parent resource name.
  117. //
  118. // Format: `projects/{project}/locations/{location}/instances/{instance}`
  119. //
  120. // For `{project}`, either `project-number` or `project-id` can be provided.
  121. // For `{instance}`, only `-` character is supported to list vulnerability
  122. // reports across VMs.
  123. string parent = 1 [
  124. (google.api.field_behavior) = REQUIRED,
  125. (google.api.resource_reference) = {
  126. type: "compute.googleapis.com/Instance"
  127. }
  128. ];
  129. // The maximum number of results to return.
  130. int32 page_size = 2;
  131. // A pagination token returned from a previous call to
  132. // `ListVulnerabilityReports` that indicates where this listing
  133. // should continue from.
  134. string page_token = 3;
  135. // If provided, this field specifies the criteria that must be met by a
  136. // `vulnerabilityReport` API resource to be included in the response.
  137. string filter = 4;
  138. }
  139. // A response message for listing vulnerability reports for all VM instances in
  140. // the specified location.
  141. message ListVulnerabilityReportsResponse {
  142. // List of vulnerabilityReport objects.
  143. repeated VulnerabilityReport vulnerability_reports = 1;
  144. // The pagination token to retrieve the next page of vulnerabilityReports
  145. // object.
  146. string next_page_token = 2;
  147. }
  148. // Common Vulnerability Scoring System version 3.
  149. // For details, see https://www.first.org/cvss/specification-document
  150. message CVSSv3 {
  151. // This metric reflects the context by which vulnerability exploitation is
  152. // possible.
  153. enum AttackVector {
  154. // Invalid value.
  155. ATTACK_VECTOR_UNSPECIFIED = 0;
  156. // The vulnerable component is bound to the network stack and the set of
  157. // possible attackers extends beyond the other options listed below, up to
  158. // and including the entire Internet.
  159. ATTACK_VECTOR_NETWORK = 1;
  160. // The vulnerable component is bound to the network stack, but the attack is
  161. // limited at the protocol level to a logically adjacent topology.
  162. ATTACK_VECTOR_ADJACENT = 2;
  163. // The vulnerable component is not bound to the network stack and the
  164. // attacker's path is via read/write/execute capabilities.
  165. ATTACK_VECTOR_LOCAL = 3;
  166. // The attack requires the attacker to physically touch or manipulate the
  167. // vulnerable component.
  168. ATTACK_VECTOR_PHYSICAL = 4;
  169. }
  170. // This metric describes the conditions beyond the attacker's control that
  171. // must exist in order to exploit the vulnerability.
  172. enum AttackComplexity {
  173. // Invalid value.
  174. ATTACK_COMPLEXITY_UNSPECIFIED = 0;
  175. // Specialized access conditions or extenuating circumstances do not exist.
  176. // An attacker can expect repeatable success when attacking the vulnerable
  177. // component.
  178. ATTACK_COMPLEXITY_LOW = 1;
  179. // A successful attack depends on conditions beyond the attacker's control.
  180. // That is, a successful attack cannot be accomplished at will, but requires
  181. // the attacker to invest in some measurable amount of effort in preparation
  182. // or execution against the vulnerable component before a successful attack
  183. // can be expected.
  184. ATTACK_COMPLEXITY_HIGH = 2;
  185. }
  186. // This metric describes the level of privileges an attacker must possess
  187. // before successfully exploiting the vulnerability.
  188. enum PrivilegesRequired {
  189. // Invalid value.
  190. PRIVILEGES_REQUIRED_UNSPECIFIED = 0;
  191. // The attacker is unauthorized prior to attack, and therefore does not
  192. // require any access to settings or files of the vulnerable system to
  193. // carry out an attack.
  194. PRIVILEGES_REQUIRED_NONE = 1;
  195. // The attacker requires privileges that provide basic user capabilities
  196. // that could normally affect only settings and files owned by a user.
  197. // Alternatively, an attacker with Low privileges has the ability to access
  198. // only non-sensitive resources.
  199. PRIVILEGES_REQUIRED_LOW = 2;
  200. // The attacker requires privileges that provide significant (e.g.,
  201. // administrative) control over the vulnerable component allowing access to
  202. // component-wide settings and files.
  203. PRIVILEGES_REQUIRED_HIGH = 3;
  204. }
  205. // This metric captures the requirement for a human user, other than the
  206. // attacker, to participate in the successful compromise of the vulnerable
  207. // component.
  208. enum UserInteraction {
  209. // Invalid value.
  210. USER_INTERACTION_UNSPECIFIED = 0;
  211. // The vulnerable system can be exploited without interaction from any user.
  212. USER_INTERACTION_NONE = 1;
  213. // Successful exploitation of this vulnerability requires a user to take
  214. // some action before the vulnerability can be exploited.
  215. USER_INTERACTION_REQUIRED = 2;
  216. }
  217. // The Scope metric captures whether a vulnerability in one vulnerable
  218. // component impacts resources in components beyond its security scope.
  219. enum Scope {
  220. // Invalid value.
  221. SCOPE_UNSPECIFIED = 0;
  222. // An exploited vulnerability can only affect resources managed by the same
  223. // security authority.
  224. SCOPE_UNCHANGED = 1;
  225. // An exploited vulnerability can affect resources beyond the security scope
  226. // managed by the security authority of the vulnerable component.
  227. SCOPE_CHANGED = 2;
  228. }
  229. // The Impact metrics capture the effects of a successfully exploited
  230. // vulnerability on the component that suffers the worst outcome that is most
  231. // directly and predictably associated with the attack.
  232. enum Impact {
  233. // Invalid value.
  234. IMPACT_UNSPECIFIED = 0;
  235. // High impact.
  236. IMPACT_HIGH = 1;
  237. // Low impact.
  238. IMPACT_LOW = 2;
  239. // No impact.
  240. IMPACT_NONE = 3;
  241. }
  242. // The base score is a function of the base metric scores.
  243. // https://www.first.org/cvss/specification-document#Base-Metrics
  244. float base_score = 1;
  245. // The Exploitability sub-score equation is derived from the Base
  246. // Exploitability metrics.
  247. // https://www.first.org/cvss/specification-document#2-1-Exploitability-Metrics
  248. float exploitability_score = 2;
  249. // The Impact sub-score equation is derived from the Base Impact metrics.
  250. float impact_score = 3;
  251. // This metric reflects the context by which vulnerability exploitation is
  252. // possible.
  253. AttackVector attack_vector = 5;
  254. // This metric describes the conditions beyond the attacker's control that
  255. // must exist in order to exploit the vulnerability.
  256. AttackComplexity attack_complexity = 6;
  257. // This metric describes the level of privileges an attacker must possess
  258. // before successfully exploiting the vulnerability.
  259. PrivilegesRequired privileges_required = 7;
  260. // This metric captures the requirement for a human user, other than the
  261. // attacker, to participate in the successful compromise of the vulnerable
  262. // component.
  263. UserInteraction user_interaction = 8;
  264. // The Scope metric captures whether a vulnerability in one vulnerable
  265. // component impacts resources in components beyond its security scope.
  266. Scope scope = 9;
  267. // This metric measures the impact to the confidentiality of the information
  268. // resources managed by a software component due to a successfully exploited
  269. // vulnerability.
  270. Impact confidentiality_impact = 10;
  271. // This metric measures the impact to integrity of a successfully exploited
  272. // vulnerability.
  273. Impact integrity_impact = 11;
  274. // This metric measures the impact to the availability of the impacted
  275. // component resulting from a successfully exploited vulnerability.
  276. Impact availability_impact = 12;
  277. }