feat: Release the access field in the v1 finding proto, which represe…

…nts an access event tied to the finding docs: added more clarification around what event_time means on a v1 finding (#457)

feat: Release the access field in the v1 finding proto, which represents an access event tied to the finding
docs: added more clarification around what event_time means on a v1 finding
PiperOrigin-RevId: 425659764
Source-Link: googleapis/googleapis@fa6793b
Source-Link: googleapis/googleapis-gen@2541906
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMjU0MTkwNjExZDExZTdmMGQyNzEyMjJjZjY0NDg3ZGU5ZmZiZDVkOSJ9
Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

packages/google-cloud-securitycenter/protos/google/cloud/securitycenter/v1/access.proto

@@ -0,0 +1,56 @@
+// Copyright 2021 Google LLC
+//
+// 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 google.cloud.securitycenter.v1;
+
+import "google/api/annotations.proto";
+
+option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter";
+option java_multiple_files = true;
+option java_outer_classname = "AccessProto";
+option java_package = "com.google.cloud.securitycenter.v1";
+option csharp_namespace = "Google.Cloud.SecurityCenter.V1";
+option php_namespace = "Google\\Cloud\\SecurityCenter\\V1";
+option ruby_package = "Google::Cloud::SecurityCenter::V1";
+
+// Represents an access event.
+message Access {
+  // Associated email, such as "[email protected]".
+  string principal_email = 1;
+
+  // Caller's IP address, such as "1.1.1.1".
+  string caller_ip = 2;
+
+  // The caller IP's geolocation, which identifies where the call came from.
+  Geolocation caller_ip_geo = 3;
+
+  // What kind of user agent is associated, e.g. operating system shells,
+  // embedded or stand-alone applications, etc.
+  string user_agent_family = 4;
+
+  // This is the API service that the service account made a call to, e.g.
+  // "iam.googleapis.com"
+  string service_name = 5;
+
+  // The method that the service account called, e.g. "SetIamPolicy".
+  string method_name = 6;
+}
+
+// Represents a geographical location for a given access.
+message Geolocation {
+  // A CLDR.
+  string region_code = 1;
+}

packages/google-cloud-securitycenter/protos/google/cloud/securitycenter/v1/finding.proto

@@ -16,15 +16,16 @@ syntax = "proto3";
 
 package google.cloud.securitycenter.v1;
 
+import "google/api/annotations.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/cloud/securitycenter/v1/access.proto";
 import "google/cloud/securitycenter/v1/external_system.proto";
 import "google/cloud/securitycenter/v1/indicator.proto";
 import "google/cloud/securitycenter/v1/security_marks.proto";
 import "google/cloud/securitycenter/v1/vulnerability.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
-import "google/api/annotations.proto";
 
 option csharp_namespace = "Google.Cloud.SecurityCenter.V1";
 option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter";
@@ -200,11 +201,12 @@ message Finding {
   // to the finding.
   SecurityMarks security_marks = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // The time at which the event took place, or when an update to the finding
-  // occurred. For example, if the finding represents an open firewall it would
-  // capture the time the detector believes the firewall became open. The
-  // accuracy is determined by the detector. If the finding were to be resolved
-  // afterward, this time would reflect when the finding was resolved. Must not
+  // The time the finding was first detected. If an existing finding is updated,
+  // then this is the time the update occurred.
+  // For example, if the finding represents an open firewall, this property
+  // captures the time the detector believes the firewall became open. The
+  // accuracy is determined by the detector. If the finding is later resolved,
+  // then this time reflects when the finding was resolved. This must not
   // be set to a value greater than the current timestamp.
   google.protobuf.Timestamp event_time = 9;
 
@@ -249,6 +251,10 @@ message Finding {
   // information and external system finding fields.
   map<string, ExternalSystem> external_systems = 22 [(google.api.field_behavior) = OUTPUT_ONLY];
 
+  // Access details associated to the Finding, such as more information on the
+  // caller, which method was accessed, from where, etc.
+  Access access = 26;
+
   // First known as mute_annotation. Records additional information about the
   // mute operation e.g. mute config that muted the finding, user who muted the
   // finding, etc.

packages/google-cloud-securitycenter/protos/google/cloud/securitycenter/v1/securitycenter_service.proto

@@ -16,7 +16,6 @@ syntax = "proto3";
 
 package google.cloud.securitycenter.v1;
 
-import public "google/cloud/securitycenter/v1/run_asset_discovery_response.proto";
 import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
@@ -28,6 +27,7 @@ import "google/cloud/securitycenter/v1/folder.proto";
 import "google/cloud/securitycenter/v1/mute_config.proto";
 import "google/cloud/securitycenter/v1/notification_config.proto";
 import "google/cloud/securitycenter/v1/organization_settings.proto";
+import public "google/cloud/securitycenter/v1/run_asset_discovery_response.proto";
 import "google/cloud/securitycenter/v1/security_marks.proto";
 import "google/cloud/securitycenter/v1/source.proto";
 import "google/iam/v1/iam_policy.proto";
@@ -1459,6 +1459,34 @@ message ListFindingsRequest {
 message ListFindingsResponse {
   // Result containing the Finding and its StateChange.
   message ListFindingsResult {
+    // The change in state of the finding.
+    //
+    // When querying across two points in time this describes
+    // the change in the finding between the two points: CHANGED, UNCHANGED,
+    // ADDED, or REMOVED. Findings can not be deleted, so REMOVED implies that
+    // the finding at timestamp does not match the filter specified, but it did
+    // at timestamp - compare_duration. If there was no compare_duration
+    // supplied in the request the state change will be: UNUSED
+    enum StateChange {
+      // State change is unused, this is the canonical default for this enum.
+      UNUSED = 0;
+
+      // The finding has changed state in some way between the points in time
+      // and existed at both points.
+      CHANGED = 1;
+
+      // The finding has not changed state between the points in time and
+      // existed at both points.
+      UNCHANGED = 2;
+
+      // The finding was created between the points in time.
+      ADDED = 3;
+
+      // The finding at timestamp does not match the filter specified, but it
+      // did at timestamp - compare_duration.
+      REMOVED = 4;
+    }
+
     // Information related to the Google Cloud resource that is
     // associated with this finding.
     message Resource {
@@ -1490,34 +1518,6 @@ message ListFindingsResponse {
       string display_name = 8;
     }
 
-    // The change in state of the finding.
-    //
-    // When querying across two points in time this describes
-    // the change in the finding between the two points: CHANGED, UNCHANGED,
-    // ADDED, or REMOVED. Findings can not be deleted, so REMOVED implies that
-    // the finding at timestamp does not match the filter specified, but it did
-    // at timestamp - compare_duration. If there was no compare_duration
-    // supplied in the request the state change will be: UNUSED
-    enum StateChange {
-      // State change is unused, this is the canonical default for this enum.
-      UNUSED = 0;
-
-      // The finding has changed state in some way between the points in time
-      // and existed at both points.
-      CHANGED = 1;
-
-      // The finding has not changed state between the points in time and
-      // existed at both points.
-      UNCHANGED = 2;
-
-      // The finding was created between the points in time.
-      ADDED = 3;
-
-      // The finding at timestamp does not match the filter specified, but it
-      // did at timestamp - compare_duration.
-      REMOVED = 4;
-    }
-
     // Finding matching the search request.
     Finding finding = 1;
 
@@ -1681,6 +1681,7 @@ message UpdateSecurityMarksRequest {
 
   // The time at which the updated SecurityMarks take effect.
   // If not set uses current server time.  Updates will be applied to the
-  // SecurityMarks that are active immediately preceding this time.
+  // SecurityMarks that are active immediately preceding this time. Must be
+  // smaller or equal to the server time.
   google.protobuf.Timestamp start_time = 3;
 }