feat: Add Resource to the v1 NotificationMessage, which contains reso…

…urce-related fields associated to the Finding notification.

docs: Adjusted wording from Cloud SCC to Security Command Center, and updated filtering docs for List APIs.

PiperOrigin-RevId: 315715539

google/cloud/securitycenter/v1/BUILD.bazel

@@ -17,6 +17,7 @@ proto_library(
         "notification_config.proto",
         "notification_message.proto",
         "organization_settings.proto",
+        "resource.proto",
         "run_asset_discovery_response.proto",
         "security_marks.proto",
         "securitycenter_service.proto",
@@ -136,8 +137,8 @@ go_gapic_library(
     deps = [
         ":securitycenter_go_proto",
         "//google/iam/v1:iam_go_proto",
-        "//google/longrunning:longrunning_go_gapic",
         "//google/longrunning:longrunning_go_proto",
+        "@com_google_cloud_go//longrunning/autogen:go_default_library",
         "@com_google_cloud_go//longrunning:go_default_library",
         "@io_bazel_rules_go//proto/wkt:duration_go_proto",
         "@io_bazel_rules_go//proto/wkt:struct_go_proto",

google/cloud/securitycenter/v1/asset.proto

@@ -29,30 +29,31 @@ option java_package = "com.google.cloud.securitycenter.v1";
 option php_namespace = "Google\\Cloud\\SecurityCenter\\V1";
 option ruby_package = "Google::Cloud::SecurityCenter::V1";
 
-// Cloud Security Command Center's (Cloud SCC) representation of a Google Cloud
-// Platform (GCP) resource.
+// Security Command Center representation of a Google Cloud
+// resource.
 //
-// The Asset is a Cloud SCC resource that captures information about a single
-// GCP resource. All modifications to an Asset are only within the context of
-// Cloud SCC and don't affect the referenced GCP resource.
+// The Asset is a Security Command Center resource that captures information
+// about a single Google Cloud resource. All modifications to an Asset are only
+// within the context of Security Command Center and don't affect the referenced
+// Google Cloud resource.
 message Asset {
   option (google.api.resource) = {
     type: "securitycenter.googleapis.com/Asset"
     pattern: "organizations/{organization}/assets/{asset}"
   };
 
-  // Cloud SCC managed properties. These properties are managed by Cloud SCC and
-  // cannot be modified by the user.
+  // Security Command Center managed properties. These properties are managed by
+  // Security Command Center and cannot be modified by the user.
   message SecurityCenterProperties {
-    // The full resource name of the GCP resource this asset
+    // The full resource name of the Google Cloud resource this asset
     // represents. This field is immutable after create time. See:
     // https://cloud.google.com/apis/design/resource_names#full_resource_name
     string resource_name = 1;
 
-    // The type of the GCP resource. Examples include: APPLICATION,
+    // The type of the Google Cloud resource. Examples include: APPLICATION,
     // PROJECT, and ORGANIZATION. This is a case insensitive field defined by
-    // Cloud SCC and/or the producer of the resource and is immutable
-    // after create time.
+    // Security Command Center and/or the producer of the resource and is
+    // immutable after create time.
     string resource_type = 2;
 
     // The full resource name of the immediate parent of the resource. See:
@@ -76,9 +77,10 @@ message Asset {
     string resource_project_display_name = 8;
   }
 
-  // IAM Policy information associated with the GCP resource described by the
-  // Cloud SCC asset. This information is managed and defined by the GCP
-  // resource and cannot be modified by the user.
+  // 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.
   message IamPolicy {
     // The JSON representation of the Policy associated with the asset.
     // See https://cloud.google.com/iam/reference/rest/v1/Policy for format
@@ -92,27 +94,28 @@ message Asset {
   // "organizations/{organization_id}/assets/{asset_id}".
   string name = 1;
 
-  // Cloud SCC managed properties. These properties are managed by
-  // Cloud SCC and cannot be modified by the user.
+  // Security Command Center managed properties. These properties are managed by
+  // Security Command Center and cannot be modified by the user.
   SecurityCenterProperties security_center_properties = 2;
 
   // Resource managed properties. These properties are managed and defined by
-  // the GCP resource and cannot be modified by the user.
+  // the Google Cloud resource and cannot be modified by the user.
   map<string, google.protobuf.Value> resource_properties = 7;
 
   // User specified security marks. These marks are entirely managed by the user
   // and come from the SecurityMarks resource that belongs to the asset.
   SecurityMarks security_marks = 8;
 
-  // The time at which the asset was created in Cloud SCC.
+  // 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 Cloud
-  // SCC.
+  // The time at which the asset was last updated, added, or deleted in Security
+  // Command Center.
   google.protobuf.Timestamp update_time = 10;
 
-  // IAM Policy information associated with the GCP resource described by the
-  // Cloud SCC asset. This information is managed and defined by the GCP
-  // resource and cannot be modified by the user.
+  // 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;
 }

google/cloud/securitycenter/v1/finding.proto

@@ -30,11 +30,11 @@ option java_package = "com.google.cloud.securitycenter.v1";
 option php_namespace = "Google\\Cloud\\SecurityCenter\\V1";
 option ruby_package = "Google::Cloud::SecurityCenter::V1";
 
-// Cloud Security Command Center (Cloud SCC) finding.
+// Security Command Center finding.
 //
 // A finding is a record of assessment data like security, risk, health, or
-// privacy, that is ingested into Cloud SCC for presentation, notification,
-// analysis, policy testing, and enforcement. For example, a
+// privacy, that is ingested into Security Command Center for presentation,
+// notification, analysis, policy testing, and enforcement. For example, a
 // cross-site scripting (XSS) vulnerability in an App Engine application is a
 // finding.
 message Finding {
@@ -69,12 +69,12 @@ message Finding {
   // "organizations/{organization_id}/sources/{source_id}"
   string parent = 2;
 
-  // For findings on Google Cloud Platform (GCP) resources, the full resource
-  // name of the GCP resource this finding is for. See:
+  // For findings on Google Cloud resources, the full resource
+  // name of the Google Cloud resource this finding is for. See:
   // https://cloud.google.com/apis/design/resource_names#full_resource_name
-  // When the finding is for a non-GCP resource, the resourceName can be a
-  // customer or partner defined string.
-  // This field is immutable after creation time.
+  // When the finding is for a non-Google Cloud resource, the resourceName can
+  // be a customer or partner defined string. This field is immutable after
+  // creation time.
   string resource_name = 3;
 
   // The state of the finding.
@@ -85,9 +85,9 @@ message Finding {
   // Example: "XSS_FLASH_INJECTION"
   string category = 5;
 
-  // The URI that, if available, points to a web page outside of Cloud SCC
-  // where additional information about the finding can be found. This field is
-  // guaranteed to be either empty or a well formed URL.
+  // The URI that, if available, points to a web page outside of Security
+  // Command Center where additional information about the finding can be found.
+  // This field is guaranteed to be either empty or a well formed URL.
   string external_uri = 6;
 
   // Source specific properties. These properties are managed by the source
@@ -106,6 +106,6 @@ message Finding {
   // the firewall became open. The accuracy is determined by the detector.
   google.protobuf.Timestamp event_time = 9;
 
-  // The time at which the finding was created in Cloud SCC.
+  // The time at which the finding was created in Security Command Center.
   google.protobuf.Timestamp create_time = 10;
 }

google/cloud/securitycenter/v1/notification_message.proto

@@ -18,6 +18,7 @@ package google.cloud.securitycenter.v1;
 
 import "google/api/annotations.proto";
 import "google/cloud/securitycenter/v1/finding.proto";
+import "google/cloud/securitycenter/v1/resource.proto";
 
 option csharp_namespace = "Google.Cloud.SecurityCenter.V1";
 option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter";
@@ -38,4 +39,7 @@ message NotificationMessage {
     // populated.
     Finding finding = 2;
   }
+
+  // The Cloud resource tied to this notification's Finding.
+  Resource resource = 3;
 }

google/cloud/securitycenter/v1/organization_settings.proto

@@ -26,8 +26,8 @@ option java_package = "com.google.cloud.securitycenter.v1";
 option php_namespace = "Google\\Cloud\\SecurityCenter\\V1";
 option ruby_package = "Google::Cloud::SecurityCenter::V1";
 
-// User specified settings that are attached to the Cloud Security Command
-// Center (Cloud SCC) organization.
+// User specified settings that are attached to the Security Command
+// Center organization.
 message OrganizationSettings {
   option (google.api.resource) = {
     type: "securitycenter.googleapis.com/OrganizationSettings"

google/cloud/securitycenter/v1/resource.proto

@@ -0,0 +1,46 @@
+// Copyright 2020 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 = "ResourceProto";
+option java_package = "com.google.cloud.securitycenter.v1";
+option php_namespace = "Google\\Cloud\\SecurityCenter\\V1";
+option ruby_package = "Google::Cloud::SecurityCenter::V1";
+
+// Information related to the Google Cloud resource.
+message Resource {
+  // The full resource name of the resource. See:
+  // https://cloud.google.com/apis/design/resource_names#full_resource_name
+  string name = 1;
+
+  // The full resource name of project that the resource belongs to.
+  string project = 2;
+
+  // The human readable name of project that the resource belongs to.
+  string project_display_name = 3;
+
+  // The full resource name of resource's parent.
+  string parent = 4;
+
+  // The human readable name of resource's parent.
+  string parent_display_name = 5;
+}

google/cloud/securitycenter/v1/security_marks.proto

@@ -26,9 +26,9 @@ option java_package = "com.google.cloud.securitycenter.v1";
 option php_namespace = "Google\\Cloud\\SecurityCenter\\V1";
 option ruby_package = "Google::Cloud::SecurityCenter::V1";
 
-// User specified security marks that are attached to the parent Cloud Security
-// Command Center (Cloud SCC) resource. Security marks are scoped within a Cloud
-// SCC organization -- they can be modified and viewed by all users who have
+// User specified security marks that are attached to the parent Security
+// Command Center resource. Security marks are scoped within a Security Command
+// Center organization -- they can be modified and viewed by all users who have
 // proper permissions on the organization.
 message SecurityMarks {
   option (google.api.resource) = {

google/cloud/securitycenter/v1/securitycenter_service.proto

@@ -438,15 +438,15 @@ message GroupAssetsRequest {
   //
   //   Usage: This should be milliseconds since epoch or an RFC3339 string.
   //   Examples:
-  //     "update_time = \"2019-06-10T16:07:18-07:00\""
-  //     "update_time = 1560208038000"
+  //     `update_time = "2019-06-10T16:07:18-07:00"`
+  //     `update_time = 1560208038000`
   //
   // * create_time: `=`, `>`, `<`, `>=`, `<=`
   //
   //   Usage: This should be milliseconds since epoch or an RFC3339 string.
   //   Examples:
-  //     "create_time = \"2019-06-10T16:07:18-07:00\""
-  //     "create_time = 1560208038000"
+  //     `create_time = "2019-06-10T16:07:18-07:00"`
+  //     `create_time = 1560208038000`
   //
   // * iam_policy.policy_blob: `=`, `:`
   // * resource_properties: `=`, `:`, `>`, `<`, `>=`, `<=`
@@ -461,6 +461,12 @@ message GroupAssetsRequest {
   // * security_center_properties.resource_owners: `=`, `:`
   //
   // For example, `resource_properties.size = 100` is a valid filter string.
+  //
+  // Use a partial match on the empty string to filter based on a property
+  // existing:`resource_properties.my_property : ""`
+  //
+  // Use a negated partial match on the empty string to filter based on a
+  // property not existing: `-resource_properties.my_property : ""`
   string filter = 2;
 
   // Required. Expression that defines what assets fields to use for grouping.
@@ -595,13 +601,19 @@ message GroupFindingsRequest {
   //
   //   Usage: This should be milliseconds since epoch or an RFC3339 string.
   //   Examples:
-  //     "event_time = \"2019-06-10T16:07:18-07:00\""
-  //     "event_time = 1560208038000"
+  //     `event_time = "2019-06-10T16:07:18-07:00"`
+  //     `event_time = 1560208038000`
   //
   // * security_marks.marks: `=`, `:`
   // * source_properties: `=`, `:`, `>`, `<`, `>=`, `<=`
   //
   // For example, `source_properties.size = 100` is a valid filter string.
+  //
+  // Use a partial match on the empty string to filter based on a property
+  // existing: `source_properties.my_property : ""`
+  //
+  // Use a negated partial match on the empty string to filter based on a
+  // property not existing: `-source_properties.my_property : ""`
   string filter = 2;
 
   // Required. Expression that defines what assets fields to use for grouping
@@ -803,15 +815,15 @@ message ListAssetsRequest {
   //
   //   Usage: This should be milliseconds since epoch or an RFC3339 string.
   //   Examples:
-  //     "update_time = \"2019-06-10T16:07:18-07:00\""
-  //     "update_time = 1560208038000"
+  //     `update_time = "2019-06-10T16:07:18-07:00"`
+  //     `update_time = 1560208038000`
   //
   // * create_time: `=`, `>`, `<`, `>=`, `<=`
   //
   //   Usage: This should be milliseconds since epoch or an RFC3339 string.
   //   Examples:
-  //     "create_time = \"2019-06-10T16:07:18-07:00\""
-  //     "create_time = 1560208038000"
+  //     `create_time = "2019-06-10T16:07:18-07:00"`
+  //     `create_time = 1560208038000`
   //
   // * iam_policy.policy_blob: `=`, `:`
   // * resource_properties: `=`, `:`, `>`, `<`, `>=`, `<=`
@@ -826,6 +838,12 @@ message ListAssetsRequest {
   // * security_center_properties.resource_owners: `=`, `:`
   //
   // For example, `resource_properties.size = 100` is a valid filter string.
+  //
+  // Use a partial match on the empty string to filter based on a property
+  // existing: `resource_properties.my_property : ""`
+  //
+  // Use a negated partial match on the empty string to filter based on a
+  // property not existing: `-resource_properties.my_property : ""`
   string filter = 2;
 
   // Expression that defines what fields and order to use for sorting. The
@@ -992,13 +1010,19 @@ message ListFindingsRequest {
   //
   //   Usage: This should be milliseconds since epoch or an RFC3339 string.
   //   Examples:
-  //     "event_time = \"2019-06-10T16:07:18-07:00\""
-  //     "event_time = 1560208038000"
+  //     `event_time = "2019-06-10T16:07:18-07:00"`
+  //     `event_time = 1560208038000`
   //
   // security_marks.marks: `=`, `:`
   // source_properties: `=`, `:`, `>`, `<`, `>=`, `<=`
   //
   // For example, `source_properties.size = 100` is a valid filter string.
+  //
+  // Use a partial match on the empty string to filter based on a property
+  // existing: `source_properties.my_property : ""`
+  //
+  // Use a negated partial match on the empty string to filter based on a
+  // property not existing: `-source_properties.my_property : ""`
   string filter = 2;
 
   // Expression that defines what fields and order to use for sorting. The
@@ -1078,7 +1102,7 @@ message ListFindingsRequest {
 message ListFindingsResponse {
   // Result containing the Finding and its StateChange.
   message ListFindingsResult {
-    // Information related to the Google Cloud Platform (GCP) resource that is
+    // Information related to the Google Cloud resource that is
     // associated with this finding.
     message Resource {
       // The full resource name of the resource. See:

google/cloud/securitycenter/v1/securitycenter_v1.yaml

@@ -1,19 +1,20 @@
 type: google.api.Service
 config_version: 3
 name: securitycenter.googleapis.com
-title: Cloud Security Command Center API
+title: Security Command Center API
 
 apis:
 - name: google.cloud.securitycenter.v1.SecurityCenter
 
 types:
 - name: google.cloud.securitycenter.v1.NotificationMessage
+- name: google.cloud.securitycenter.v1.Resource
 - name: google.cloud.securitycenter.v1.RunAssetDiscoveryResponse
 
 documentation:
   summary: |-
-    Cloud Security Command Center API provides access to temporal views of
-    assets and findings within an organization.
+    Security Command Center API provides access to temporal views of assets and
+    findings within an organization.
 
 backend:
   rules: