feat(v1): add canonical_name and folder fields (#379)

Assets and findings may be created in organizations, folders or projects, however in the current API version the name field for resources will always be prefixed by "organizations/...", for historical reasons. The "canonical_name" field shows the actual location of the resource, and in requests either the name or "canonical name" can be used for the "name" in the request.

The "folder" field contains the folders in the resource's ancestry.

PiperOrigin-RevId: 372965035

Source-Link: googleapis/googleapis@0a992df

Source-Link: googleapis/googleapis-gen@3874faa

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

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// 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.
@@ -16,11 +16,12 @@ syntax = "proto3";
 
 package google.cloud.securitycenter.v1;
 
-import "google/api/annotations.proto";
 import "google/api/resource.proto";
+import "google/cloud/securitycenter/v1/folder.proto";
 import "google/cloud/securitycenter/v1/security_marks.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";
@@ -40,6 +41,8 @@ message Asset {
   option (google.api.resource) = {
     type: "securitycenter.googleapis.com/Asset"
     pattern: "organizations/{organization}/assets/{asset}"
+    pattern: "folders/{folder}/assets/{asset}"
+    pattern: "projects/{project}/assets/{asset}"
   };
 
   // Security Command Center managed properties. These properties are managed by
@@ -75,6 +78,11 @@ message Asset {
 
     // The user defined display name for the project of this resource.
     string resource_project_display_name = 8;
+
+    // Contains a Folder message for each folder in the assets ancestry.
+    // The first folder is the deepest nested folder, and the last folder is the
+    // folder directly under the Organization.
+    repeated Folder folders = 10;
   }
 
   // Cloud IAM Policy information associated with the Google Cloud resource
@@ -109,13 +117,19 @@ message Asset {
   // The time at which the asset was created in Security Command Center.
   google.protobuf.Timestamp create_time = 9;
 
-  // The time at which the asset was last updated, added, or deleted in Security
-  // Command Center.
+  // The time at which the asset was last updated or added in Cloud SCC.
   google.protobuf.Timestamp update_time = 10;
 
   // Cloud IAM Policy information associated with the Google Cloud resource
   // described by the Security Command Center asset. This information is managed
   // and defined by the Google Cloud resource and cannot be modified by the
   // user.
   IamPolicy iam_policy = 11;
+
+  // The canonical name of the resource. It's either
+  // "organizations/{organization_id}/assets/{asset_id}",
+  // "folders/{folder_id}/assets/{asset_id}" or
+  // "projects/{project_number}/assets/{asset_id}", depending on the closest CRM
+  // ancestor of the resource.
+  string canonical_name = 13;
 }

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

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// 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.
@@ -16,12 +16,12 @@ 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/security_marks.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";
@@ -41,6 +41,8 @@ message Finding {
   option (google.api.resource) = {
     type: "securitycenter.googleapis.com/Finding"
     pattern: "organizations/{organization}/sources/{source}/findings/{finding}"
+    pattern: "folders/{folder}/sources/{source}/findings/{finding}"
+    pattern: "projects/{project}/sources/{source}/findings/{finding}"
   };
 
   // The state of the finding.
@@ -164,7 +166,8 @@ message 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.
+  // afterward, this time would reflect when the finding was resolved. Must not
+  // be set to a value greater than the current timestamp.
   google.protobuf.Timestamp event_time = 9;
 
   // The time at which the finding was created in Security Command Center.
@@ -173,4 +176,12 @@ message Finding {
   // The severity of the finding. This field is managed by the source that
   // writes the finding.
   Severity severity = 12;
+
+  // The canonical name of the finding. It's either
+  // "organizations/{organization_id}/sources/{source_id}/findings/{finding_id}",
+  // "folders/{folder_id}/sources/{source_id}/findings/{finding_id}" or
+  // "projects/{project_number}/sources/{source_id}/findings/{finding_id}",
+  // depending on the closest CRM ancestor of the resource associated with the
+  // finding.
+  string canonical_name = 14;
 }

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

@@ -0,0 +1,38 @@
+// 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 csharp_namespace = "Google.Cloud.SecurityCenter.V1";
+option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter";
+option java_multiple_files = true;
+option java_outer_classname = "FolderProto";
+option java_package = "com.google.cloud.securitycenter.v1";
+option php_namespace = "Google\\Cloud\\SecurityCenter\\V1";
+option ruby_package = "Google::Cloud::SecurityCenter::V1";
+
+// Message that contains the resource name and display name of a folder
+// resource.
+message Folder {
+  // Full resource name of this folder. See:
+  // https://cloud.google.com/apis/design/resource_names#full_resource_name
+  string resource_folder = 1;
+
+  // The user defined display name for this folder.
+  string resource_folder_display_name = 2;
+}

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

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// 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.
@@ -16,9 +16,9 @@ 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/api/annotations.proto";
 
 option csharp_namespace = "Google.Cloud.SecurityCenter.V1";
 option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter";

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

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// 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.
@@ -16,9 +16,9 @@ syntax = "proto3";
 
 package google.cloud.securitycenter.v1;
 
-import "google/api/annotations.proto";
 import "google/cloud/securitycenter/v1/finding.proto";
 import "google/cloud/securitycenter/v1/resource.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";

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

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// 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.
@@ -16,8 +16,8 @@ syntax = "proto3";
 
 package google.cloud.securitycenter.v1;
 
-import "google/api/annotations.proto";
 import "google/api/resource.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";
@@ -63,6 +63,10 @@ message OrganizationSettings {
 
     // The mode to use for filtering asset discovery.
     InclusionMode inclusion_mode = 2;
+
+    // The folder ids to use for filtering asset discovery.
+    // It consists of only digits, e.g., 756619654966.
+    repeated string folder_ids = 3;
   }
 
   // The relative resource name of the settings. See:

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

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// 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.
@@ -16,6 +16,8 @@ syntax = "proto3";
 
 package google.cloud.securitycenter.v1;
 
+import "google/api/field_behavior.proto";
+import "google/cloud/securitycenter/v1/folder.proto";
 import "google/api/annotations.proto";
 
 option csharp_namespace = "Google.Cloud.SecurityCenter.V1";
@@ -43,4 +45,9 @@ message Resource {
 
   // The human readable name of resource's parent.
   string parent_display_name = 5;
+
+  // Output only. Contains a Folder message for each folder in the assets ancestry.
+  // The first folder is the deepest nested folder, and the last folder is the
+  // folder directly under the Organization.
+  repeated Folder folders = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
 }

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

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// 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.
@@ -16,8 +16,8 @@ syntax = "proto3";
 
 package google.cloud.securitycenter.v1;
 
-import "google/api/annotations.proto";
 import "google/protobuf/duration.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";

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

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// 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.
@@ -16,8 +16,8 @@ syntax = "proto3";
 
 package google.cloud.securitycenter.v1;
 
-import "google/api/annotations.proto";
 import "google/api/resource.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";
@@ -35,6 +35,10 @@ message SecurityMarks {
     type: "securitycenter.googleapis.com/SecurityMarks"
     pattern: "organizations/{organization}/assets/{asset}/securityMarks"
     pattern: "organizations/{organization}/sources/{source}/findings/{finding}/securityMarks"
+    pattern: "folders/{folder}/assets/{asset}/securityMarks"
+    pattern: "projects/{project}/assets/{asset}/securityMarks"
+    pattern: "folders/{folder}/sources/{source}/findings/{finding}/securityMarks"
+    pattern: "projects/{project}/sources/{source}/findings/{finding}/securityMarks"
   };
 
   // The relative resource name of the SecurityMarks. See:
@@ -53,4 +57,14 @@ message SecurityMarks {
   //   * Values have leading and trailing whitespace trimmed, remaining
   //     characters must be between 1 - 4096 characters (inclusive)
   map<string, string> marks = 2;
+
+  // The canonical name of the marks.
+  // Examples:
+  // "organizations/{organization_id}/assets/{asset_id}/securityMarks"
+  // "folders/{folder_id}/assets/{asset_id}/securityMarks"
+  // "projects/{project_number}/assets/{asset_id}/securityMarks"
+  // "organizations/{organization_id}/sources/{source_id}/findings/{finding_id}/securityMarks"
+  // "folders/{folder_id}/sources/{source_id}/findings/{finding_id}/securityMarks"
+  // "projects/{project_number}/sources/{source_id}/findings/{finding_id}/securityMarks"
+  string canonical_name = 3;
 }