feat: Add SimulateSecurityHealthAnalyticsCustomModule API for testing SHA custom module

Google APIs · copybara-github · commit c768e7a7d35c · 2023-10-18T15:06:08.000-07:00
PiperOrigin-RevId: 574612611
diff --git a/google/cloud/securitycenter/v1/BUILD.bazel b/google/cloud/securitycenter/v1/BUILD.bazel
@@ -66,6 +66,7 @@ proto_library(
         "//google/iam/v1:policy_proto",
         "//google/longrunning:operations_proto",
         "//google/type:expr_proto",
+        "//google/rpc:status_proto",
         "@com_google_protobuf//:duration_proto",
         "@com_google_protobuf//:empty_proto",
         "@com_google_protobuf//:field_mask_proto",
@@ -166,6 +167,7 @@ go_proto_library(
         "//google/iam/v1:iam_go_proto",
         "//google/longrunning:longrunning_go_proto",
         "//google/type:expr_go_proto",
+        "//google/rpc:status_go_proto",
     ],
 )
 
diff --git a/google/cloud/securitycenter/v1/securitycenter_service.proto b/google/cloud/securitycenter/v1/securitycenter_service.proto
@@ -30,6 +30,7 @@ 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 "google/cloud/securitycenter/v1/run_asset_discovery_response.proto";
+import "google/cloud/securitycenter/v1/security_health_analytics_custom_config.proto";
 import "google/cloud/securitycenter/v1/security_health_analytics_custom_module.proto";
 import "google/cloud/securitycenter/v1/security_marks.proto";
 import "google/cloud/securitycenter/v1/source.proto";
@@ -41,6 +42,7 @@ import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
+import "google/rpc/status.proto";
 
 option csharp_namespace = "Google.Cloud.SecurityCenter.V1";
 option go_package = "cloud.google.com/go/securitycenter/apiv1/securitycenterpb;securitycenterpb";
@@ -515,6 +517,25 @@ service SecurityCenter {
     option (google.api.method_signature) = "resource,permissions";
   }
 
+  // Simulates a given SecurityHealthAnalyticsCustomModule and Resource.
+  rpc SimulateSecurityHealthAnalyticsCustomModule(
+      SimulateSecurityHealthAnalyticsCustomModuleRequest)
+      returns (SimulateSecurityHealthAnalyticsCustomModuleResponse) {
+    option (google.api.http) = {
+      post: "/v1/{parent=organizations/*/securityHealthAnalyticsSettings}/customModules:simulate"
+      body: "*"
+      additional_bindings {
+        post: "/v1/{parent=folders/*/securityHealthAnalyticsSettings}/customModules:simulate"
+        body: "*"
+      }
+      additional_bindings {
+        post: "/v1/{parent=projects/*/securityHealthAnalyticsSettings}/customModules:simulate"
+        body: "*"
+      }
+    };
+    option (google.api.method_signature) = "parent,custom_config,resource";
+  }
+
   // Updates external system. This is for a given finding.
   rpc UpdateExternalSystem(UpdateExternalSystemRequest)
       returns (ExternalSystem) {
@@ -2030,6 +2051,62 @@ message RunAssetDiscoveryRequest {
   ];
 }
 
+// Request message to simulate a CustomConfig against a given test resource.
+// Maximum size of the request is 4 MB by default.
+message SimulateSecurityHealthAnalyticsCustomModuleRequest {
+  // Manually constructed resource. If the custom module only evaluates against
+  // the resource data, the iam_policy_data field can be omitted, and vice
+  // versa.
+  message SimulatedResource {
+    // Required. The type of the resource, e.g. `compute.googleapis.com/Disk`.
+    string resource_type = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Optional. A representation of the GCP resource. Should match the GCP
+    // resource JSON format.
+    google.protobuf.Struct resource_data = 2
+        [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. A representation of the IAM policy.
+    google.iam.v1.Policy iam_policy_data = 3
+        [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // Required. The relative resource name of the organization, project, or
+  // folder. See:
+  // https://cloud.google.com/apis/design/resource_names#relative_resource_name
+  // An example is:
+  // "organizations/{organization_id}".
+  string parent = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The user specified custom configuration to test.
+  CustomConfig custom_config = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. Resource data to simulate custom module against.
+  SimulatedResource resource = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Response message for simulating a SecurityHealthAnalyticsCustomModule against
+// a given resource.
+message SimulateSecurityHealthAnalyticsCustomModuleResponse {
+  // Possible test result.
+  message SimulatedResult {
+    oneof result {
+      // Finding that would be published for the test case,
+      // if a violation is detected.
+      Finding finding = 1;
+
+      // Indicates that the test case does not trigger any violation.
+      google.protobuf.Empty no_violation = 2;
+
+      // Error encountered during the test.
+      google.rpc.Status error = 3;
+    }
+  }
+
+  // Result for test case in the corresponding request.
+  SimulatedResult result = 1;
+}
+
 // Request message for updating a ExternalSystem resource.
 message UpdateExternalSystemRequest {
   // Required. The external system resource to update.
