1// Copyright 2023 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
15syntax = "proto3";
16
17package google.cloud.securitycenter.v1;
18
19import "google/api/field_behavior.proto";
20import "google/api/resource.proto";
21import "google/cloud/securitycenter/v1/access.proto";
22import "google/cloud/securitycenter/v1/cloud_dlp_data_profile.proto";
23import "google/cloud/securitycenter/v1/cloud_dlp_inspection.proto";
24import "google/cloud/securitycenter/v1/compliance.proto";
25import "google/cloud/securitycenter/v1/connection.proto";
26import "google/cloud/securitycenter/v1/contact_details.proto";
27import "google/cloud/securitycenter/v1/container.proto";
28import "google/cloud/securitycenter/v1/database.proto";
29import "google/cloud/securitycenter/v1/exfiltration.proto";
30import "google/cloud/securitycenter/v1/external_system.proto";
31import "google/cloud/securitycenter/v1/file.proto";
32import "google/cloud/securitycenter/v1/iam_binding.proto";
33import "google/cloud/securitycenter/v1/indicator.proto";
34import "google/cloud/securitycenter/v1/kernel_rootkit.proto";
35import "google/cloud/securitycenter/v1/kubernetes.proto";
36import "google/cloud/securitycenter/v1/mitre_attack.proto";
37import "google/cloud/securitycenter/v1/process.proto";
38import "google/cloud/securitycenter/v1/security_marks.proto";
39import "google/cloud/securitycenter/v1/vulnerability.proto";
40import "google/protobuf/struct.proto";
41import "google/protobuf/timestamp.proto";
42
43option csharp_namespace = "Google.Cloud.SecurityCenter.V1";
44option go_package = "cloud.google.com/go/securitycenter/apiv1/securitycenterpb;securitycenterpb";
45option java_multiple_files = true;
46option java_package = "com.google.cloud.securitycenter.v1";
47option php_namespace = "Google\\Cloud\\SecurityCenter\\V1";
48option ruby_package = "Google::Cloud::SecurityCenter::V1";
49
50// Security Command Center finding.
51//
52// A finding is a record of assessment data like security, risk, health, or
53// privacy, that is ingested into Security Command Center for presentation,
54// notification, analysis, policy testing, and enforcement. For example, a
55// cross-site scripting (XSS) vulnerability in an App Engine application is a
56// finding.
57message Finding {
58  option (google.api.resource) = {
59    type: "securitycenter.googleapis.com/Finding"
60    pattern: "organizations/{organization}/sources/{source}/findings/{finding}"
61    pattern: "folders/{folder}/sources/{source}/findings/{finding}"
62    pattern: "projects/{project}/sources/{source}/findings/{finding}"
63  };
64
65  // The state of the finding.
66  enum State {
67    // Unspecified state.
68    STATE_UNSPECIFIED = 0;
69
70    // The finding requires attention and has not been addressed yet.
71    ACTIVE = 1;
72
73    // The finding has been fixed, triaged as a non-issue or otherwise addressed
74    // and is no longer active.
75    INACTIVE = 2;
76  }
77
78  // The severity of the finding.
79  enum Severity {
80    // This value is used for findings when a source doesn't write a severity
81    // value.
82    SEVERITY_UNSPECIFIED = 0;
83
84    // Vulnerability:
85    // A critical vulnerability is easily discoverable by an external actor,
86    // exploitable, and results in the direct ability to execute arbitrary code,
87    // exfiltrate data, and otherwise gain additional access and privileges to
88    // cloud resources and workloads. Examples include publicly accessible
89    // unprotected user data and public SSH access with weak or no
90    // passwords.
91    //
92    // Threat:
93    // Indicates a threat that is able to access, modify, or delete data or
94    // execute unauthorized code within existing resources.
95    CRITICAL = 1;
96
97    // Vulnerability:
98    // A high risk vulnerability can be easily discovered and exploited in
99    // combination with other vulnerabilities in order to gain direct access and
100    // the ability to execute arbitrary code, exfiltrate data, and otherwise
101    // gain additional access and privileges to cloud resources and workloads.
102    // An example is a database with weak or no passwords that is only
103    // accessible internally. This database could easily be compromised by an
104    // actor that had access to the internal network.
105    //
106    // Threat:
107    // Indicates a threat that is able to create new computational resources in
108    // an environment but not able to access data or execute code in existing
109    // resources.
110    HIGH = 2;
111
112    // Vulnerability:
113    // A medium risk vulnerability could be used by an actor to gain access to
114    // resources or privileges that enable them to eventually (through multiple
115    // steps or a complex exploit) gain access and the ability to execute
116    // arbitrary code or exfiltrate data. An example is a service account with
117    // access to more projects than it should have. If an actor gains access to
118    // the service account, they could potentially use that access to manipulate
119    // a project the service account was not intended to.
120    //
121    // Threat:
122    // Indicates a threat that is able to cause operational impact but may not
123    // access data or execute unauthorized code.
124    MEDIUM = 3;
125
126    // Vulnerability:
127    // A low risk vulnerability hampers a security organization's ability to
128    // detect vulnerabilities or active threats in their deployment, or prevents
129    // the root cause investigation of security issues. An example is monitoring
130    // and logs being disabled for resource configurations and access.
131    //
132    // Threat:
133    // Indicates a threat that has obtained minimal access to an environment but
134    // is not able to access data, execute code, or create resources.
135    LOW = 4;
136  }
137
138  // Mute state a finding can be in.
139  enum Mute {
140    // Unspecified.
141    MUTE_UNSPECIFIED = 0;
142
143    // Finding has been muted.
144    MUTED = 1;
145
146    // Finding has been unmuted.
147    UNMUTED = 2;
148
149    // Finding has never been muted/unmuted.
150    UNDEFINED = 4;
151  }
152
153  // Represents what kind of Finding it is.
154  enum FindingClass {
155    // Unspecified finding class.
156    FINDING_CLASS_UNSPECIFIED = 0;
157
158    // Describes unwanted or malicious activity.
159    THREAT = 1;
160
161    // Describes a potential weakness in software that increases risk to
162    // Confidentiality & Integrity & Availability.
163    VULNERABILITY = 2;
164
165    // Describes a potential weakness in cloud resource/asset configuration that
166    // increases risk.
167    MISCONFIGURATION = 3;
168
169    // Describes a security observation that is for informational purposes.
170    OBSERVATION = 4;
171
172    // Describes an error that prevents some SCC functionality.
173    SCC_ERROR = 5;
174  }
175
176  // The [relative resource
177  // name](https://cloud.google.com/apis/design/resource_names#relative_resource_name)
178  // of the finding. Example:
179  // "organizations/{organization_id}/sources/{source_id}/findings/{finding_id}",
180  // "folders/{folder_id}/sources/{source_id}/findings/{finding_id}",
181  // "projects/{project_id}/sources/{source_id}/findings/{finding_id}".
182  string name = 1;
183
184  // The relative resource name of the source the finding belongs to. See:
185  // https://cloud.google.com/apis/design/resource_names#relative_resource_name
186  // This field is immutable after creation time.
187  // For example:
188  // "organizations/{organization_id}/sources/{source_id}"
189  string parent = 2;
190
191  // For findings on Google Cloud resources, the full resource
192  // name of the Google Cloud resource this finding is for. See:
193  // https://cloud.google.com/apis/design/resource_names#full_resource_name
194  // When the finding is for a non-Google Cloud resource, the resourceName can
195  // be a customer or partner defined string. This field is immutable after
196  // creation time.
197  string resource_name = 3;
198
199  // The state of the finding.
200  State state = 4;
201
202  // The additional taxonomy group within findings from a given source.
203  // This field is immutable after creation time.
204  // Example: "XSS_FLASH_INJECTION"
205  string category = 5;
206
207  // The URI that, if available, points to a web page outside of Security
208  // Command Center where additional information about the finding can be found.
209  // This field is guaranteed to be either empty or a well formed URL.
210  string external_uri = 6;
211
212  // Source specific properties. These properties are managed by the source
213  // that writes the finding. The key names in the source_properties map must be
214  // between 1 and 255 characters, and must start with a letter and contain
215  // alphanumeric characters or underscores only.
216  map<string, google.protobuf.Value> source_properties = 7;
217
218  // Output only. User specified security marks. These marks are entirely
219  // managed by the user and come from the SecurityMarks resource that belongs
220  // to the finding.
221  SecurityMarks security_marks = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
222
223  // The time the finding was first detected. If an existing finding is updated,
224  // then this is the time the update occurred.
225  // For example, if the finding represents an open firewall, this property
226  // captures the time the detector believes the firewall became open. The
227  // accuracy is determined by the detector. If the finding is later resolved,
228  // then this time reflects when the finding was resolved. This must not
229  // be set to a value greater than the current timestamp.
230  google.protobuf.Timestamp event_time = 9;
231
232  // The time at which the finding was created in Security Command Center.
233  google.protobuf.Timestamp create_time = 10;
234
235  // The severity of the finding. This field is managed by the source that
236  // writes the finding.
237  Severity severity = 12;
238
239  // The canonical name of the finding. It's either
240  // "organizations/{organization_id}/sources/{source_id}/findings/{finding_id}",
241  // "folders/{folder_id}/sources/{source_id}/findings/{finding_id}" or
242  // "projects/{project_number}/sources/{source_id}/findings/{finding_id}",
243  // depending on the closest CRM ancestor of the resource associated with the
244  // finding.
245  string canonical_name = 14;
246
247  // Indicates the mute state of a finding (either muted, unmuted
248  // or undefined). Unlike other attributes of a finding, a finding provider
249  // shouldn't set the value of mute.
250  Mute mute = 15;
251
252  // The class of the finding.
253  FindingClass finding_class = 17;
254
255  // Represents what's commonly known as an *indicator of compromise* (IoC) in
256  // computer forensics. This is an artifact observed on a network or in an
257  // operating system that, with high confidence, indicates a computer
258  // intrusion. For more information, see [Indicator of
259  // compromise](https://en.wikipedia.org/wiki/Indicator_of_compromise).
260  Indicator indicator = 18;
261
262  // Represents vulnerability-specific fields like CVE and CVSS scores.
263  // CVE stands for Common Vulnerabilities and Exposures
264  // (https://cve.mitre.org/about/)
265  Vulnerability vulnerability = 20;
266
267  // Output only. The most recent time this finding was muted or unmuted.
268  google.protobuf.Timestamp mute_update_time = 21
269      [(google.api.field_behavior) = OUTPUT_ONLY];
270
271  // Output only. Third party SIEM/SOAR fields within SCC, contains external
272  // system information and external system finding fields.
273  map<string, ExternalSystem> external_systems = 22
274      [(google.api.field_behavior) = OUTPUT_ONLY];
275
276  // MITRE ATT&CK tactics and techniques related to this finding.
277  // See: https://attack.mitre.org
278  MitreAttack mitre_attack = 25;
279
280  // Access details associated with the finding, such as more information on the
281  // caller, which method was accessed, and from where.
282  Access access = 26;
283
284  // Contains information about the IP connection associated with the finding.
285  repeated Connection connections = 31;
286
287  // Records additional information about the mute operation, for example, the
288  // [mute configuration](/security-command-center/docs/how-to-mute-findings)
289  // that muted the finding and the user who muted the finding.
290  string mute_initiator = 28;
291
292  // Represents operating system processes associated with the Finding.
293  repeated Process processes = 30;
294
295  // Output only. Map containing the points of contact for the given finding.
296  // The key represents the type of contact, while the value contains a list of
297  // all the contacts that pertain. Please refer to:
298  // https://cloud.google.com/resource-manager/docs/managing-notification-contacts#notification-categories
299  //
300  //     {
301  //       "security": {
302  //         "contacts": [
303  //           {
304  //             "email": "[email protected]"
305  //           },
306  //           {
307  //             "email": "[email protected]"
308  //           }
309  //         ]
310  //       }
311  //     }
312  map<string, ContactDetails> contacts = 33
313      [(google.api.field_behavior) = OUTPUT_ONLY];
314
315  // Contains compliance information for security standards associated to the
316  // finding.
317  repeated Compliance compliances = 34;
318
319  // Output only. The human readable display name of the finding source such as
320  // "Event Threat Detection" or "Security Health Analytics".
321  string parent_display_name = 36 [(google.api.field_behavior) = OUTPUT_ONLY];
322
323  // Contains more details about the finding.
324  string description = 37;
325
326  // Represents exfiltrations associated with the finding.
327  Exfiltration exfiltration = 38;
328
329  // Represents IAM bindings associated with the finding.
330  repeated IamBinding iam_bindings = 39;
331
332  // Steps to address the finding.
333  string next_steps = 40;
334
335  // Unique identifier of the module which generated the finding.
336  // Example:
337  // folders/598186756061/securityHealthAnalyticsSettings/customModules/56799441161885
338  string module_name = 41;
339
340  // Containers associated with the finding. This field provides information for
341  // both Kubernetes and non-Kubernetes containers.
342  repeated Container containers = 42;
343
344  // Kubernetes resources associated with the finding.
345  Kubernetes kubernetes = 43;
346
347  // Database associated with the finding.
348  Database database = 44;
349
350  // File associated with the finding.
351  repeated File files = 46;
352
353  // Cloud Data Loss Prevention (Cloud DLP) inspection results that are
354  // associated with the finding.
355  CloudDlpInspection cloud_dlp_inspection = 48;
356
357  // Cloud DLP data profile that is associated with the finding.
358  CloudDlpDataProfile cloud_dlp_data_profile = 49;
359
360  // Signature of the kernel rootkit.
361  KernelRootkit kernel_rootkit = 50;
362}
363