Add Resource SCC Management Organization Security Health Analytics Cu…

…stom Module (#10815)

mmv1/products/securitycentermanagement/OrganizationSecurityHealthAnalyticsCustomModule.yaml

@@ -0,0 +1,225 @@
+# Copyright 2024 Google Inc.
+# 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.
+
+--- !ruby/object:Api::Resource
+name: 'OrganizationSecurityHealthAnalyticsCustomModule'
+description: |
+  Represents an instance of a Security Health Analytics custom module, including
+  its full module name, display name, enablement state, and last updated time.
+  You can create a custom module at the organization, folder, or project level.
+  Custom modules that you create at the organization or folder level are inherited
+  by the child folders and projects.
+references: !ruby/object:Api::Resource::ReferenceLinks
+  guides:
+    'Overview of custom modules for Security Health Analytics': 'https://cloud.google.com/security-command-center/docs/custom-modules-sha-overview'
+  api: 'https://cloud.google.com/security-command-center/docs/reference/security-center-management/rest/v1/organizations.locations.securityHealthAnalyticsCustomModules'
+base_url: 'organizations/{{organization}}/locations/{{location}}/securityHealthAnalyticsCustomModules'
+self_link: 'organizations/{{organization}}/locations/{{location}}/securityHealthAnalyticsCustomModules/{{name}}'
+mutex: 'organizations/{{organization}}/locations/{{location}}/securityHealthAnalyticsCustomModules'
+update_verb: :PATCH
+update_mask: true
+examples:
+  - !ruby/object:Provider::Terraform::Examples
+    name: "scc_management_organization_security_health_analytics_custom_module_basic"
+    primary_resource_id: "example"
+    skip_test: true
+    vars:
+      display_name: basic_custom_module
+    test_env_vars:
+      org_id: :ORG_ID
+    test_vars_overrides:
+      sleep: "true"
+  - !ruby/object:Provider::Terraform::Examples
+    name: "scc_management_organization_security_health_analytics_custom_module_full"
+    primary_resource_id: "example"
+    skip_test: true
+    vars:
+      display_name: full_custom_module
+    test_env_vars:
+      org_id: :ORG_ID
+    test_vars_overrides:
+      sleep: "true"
+
+parameters:
+  - !ruby/object:Api::Type::String
+    name: 'organization'
+    immutable: true
+    required: true
+    url_param_only: true
+    description: |
+      Numerical ID of the parent organization.
+  - !ruby/object:Api::Type::String
+    name: 'location'
+    immutable: true
+    required: false
+    url_param_only: true
+    default_value: 'global'
+    description: |
+      Location ID of the parent organization. If not provided, 'global' will be used as the default location.
+
+properties:
+  - !ruby/object:Api::Type::String
+    name: 'name'
+    output: true
+    custom_flatten: templates/terraform/custom_flatten/name_from_self_link.erb
+    description: |
+      The resource name of the custom module. Its format is "organizations/{organization}/locations/{location}/securityHealthAnalyticsCustomModules/{securityHealthAnalyticsCustomModule}".
+      The id {securityHealthAnalyticsCustomModule} is server-generated and is not user settable. It will be a numeric id containing 1-20 digits.
+  - !ruby/object:Api::Type::String
+    name: 'displayName'
+    immutable: true
+    # API error for invalid display names is just "INVALID_ARGUMENT" with no details
+    validation: !ruby/object:Provider::Terraform::Validation
+      function: 'verify.ValidateRegexp(`^[a-z][\w_]{0,127}$`)'
+    description: |
+      The display name of the Security Health Analytics custom module. This
+      display name becomes the finding category for all findings that are
+      returned by this custom module. The display name must be between 1 and
+      128 characters, start with a lowercase letter, and contain alphanumeric
+      characters or underscores only.
+  - !ruby/object:Api::Type::Enum
+    name: 'enablementState'
+    description: |
+      The enablement state of the custom module.
+    values:
+      - :ENABLED
+      - :DISABLED
+  - !ruby/object:Api::Type::String
+    name: 'updateTime'
+    output: true
+    description: |
+      The time at which the custom module was last updated.
+
+      A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and
+      up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
+  - !ruby/object:Api::Type::String
+    name: 'lastEditor'
+    output: true
+    description: |
+      The editor that last updated the custom module.
+  - !ruby/object:Api::Type::String
+    name: 'ancestorModule'
+    output: true
+    description: |
+      If empty, indicates that the custom module was created in the organization, folder,
+      or project in which you are viewing the custom module. Otherwise, ancestor_module
+      specifies the organization or folder from which the custom module is inherited.
+  - !ruby/object:Api::Type::NestedObject
+    name: 'customConfig'
+    description: |
+      The user specified custom configuration for the module.
+    properties:
+      - !ruby/object:Api::Type::NestedObject
+        name: 'predicate'
+        required: true
+        description: |
+          The CEL expression to evaluate to produce findings. When the expression evaluates
+          to true against a resource, a finding is generated.
+        properties:
+          - !ruby/object:Api::Type::String
+            name: 'expression'
+            required: true
+            description: |
+              Textual representation of an expression in Common Expression Language syntax.
+          - !ruby/object:Api::Type::String
+            name: 'title'
+            description: |
+              Title for the expression, i.e. a short string describing its purpose. This can
+              be used e.g. in UIs which allow to enter the expression.
+          - !ruby/object:Api::Type::String
+            name: 'description'
+            description: |
+              Description of the expression. This is a longer text which describes the
+              expression, e.g. when hovered over it in a UI.
+          - !ruby/object:Api::Type::String
+            name: 'location'
+            description: |
+              String indicating the location of the expression for error reporting, e.g. a
+              file name and a position in the file.
+      - !ruby/object:Api::Type::NestedObject
+        name: 'customOutput'
+        description: |
+          Custom output properties.
+        properties:
+          - !ruby/object:Api::Type::Array
+            name: 'properties'
+            description: |
+              A list of custom output properties to add to the finding.
+            item_type: !ruby/object:Api::Type::NestedObject
+              properties:
+                - !ruby/object:Api::Type::String
+                  name: 'name'
+                  description: |
+                    Name of the property for the custom output.
+                - !ruby/object:Api::Type::NestedObject
+                  name: 'valueExpression'
+                  description: |
+                    The CEL expression for the custom output. A resource property can be specified
+                    to return the value of the property or a text string enclosed in quotation marks.
+                  properties:
+                    - !ruby/object:Api::Type::String
+                      name: 'expression'
+                      required: true
+                      description: |
+                        Textual representation of an expression in Common Expression Language syntax.
+                    - !ruby/object:Api::Type::String
+                      name: 'title'
+                      description: |
+                        Title for the expression, i.e. a short string describing its purpose. This can
+                        be used e.g. in UIs which allow to enter the expression.
+                    - !ruby/object:Api::Type::String
+                      name: 'description'
+                      description: |
+                        Description of the expression. This is a longer text which describes the
+                        expression, e.g. when hovered over it in a UI.
+                    - !ruby/object:Api::Type::String
+                      name: 'location'
+                      description: |
+                        String indicating the location of the expression for error reporting, e.g. a
+                        file name and a position in the file.
+      - !ruby/object:Api::Type::NestedObject
+        name: 'resourceSelector'
+        required: true
+        description: |
+          The resource types that the custom module operates on. Each custom module
+          can specify up to 5 resource types.
+        properties:
+          - !ruby/object:Api::Type::Array
+            name: 'resourceTypes'
+            required: true
+            description: |
+              The resource types to run the detector on.
+            item_type: Api::Type::String
+      - !ruby/object:Api::Type::Enum
+        name: 'severity'
+        required: true
+        description: |
+          The severity to assign to findings generated by the module.
+        values:
+          - :CRITICAL
+          - :HIGH
+          - :MEDIUM
+          - :LOW
+      - !ruby/object:Api::Type::String
+        name: 'description'
+        description: |
+          Text that describes the vulnerability or misconfiguration that the custom
+          module detects. This explanation is returned with each finding instance to
+          help investigators understand the detected issue. The text must be enclosed in quotation marks.
+      - !ruby/object:Api::Type::String
+        name: 'recommendation'
+        required: true
+        description: |
+          An explanation of the recommended steps that security teams can take to resolve
+          the detected issue. This explanation is returned with each finding generated by
+          this module in the nextSteps property of the finding JSON.

mmv1/templates/terraform/examples/scc_management_organization_security_health_analytics_custom_module_basic.tf.erb

@@ -0,0 +1,19 @@
+resource "google_scc_management_organization_security_health_analytics_custom_module" "<%= ctx[:primary_resource_id] %>" {
+  organization = "<%= ctx[:test_env_vars]['org_id'] %>"
+  display_name = "<%= ctx[:vars]['display_name'] %>"
+  location = "global"
+  enablement_state = "ENABLED"
+  custom_config {
+    predicate {
+      expression = "resource.rotationPeriod > duration(\"2592000s\")"
+    }
+    resource_selector {
+      resource_types = [
+        "cloudkms.googleapis.com/CryptoKey",
+      ]
+    }
+    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
+    recommendation = "Set the rotation period to at most 30 days."
+    severity = "MEDIUM"
+  }
+}

mmv1/templates/terraform/examples/scc_management_organization_security_health_analytics_custom_module_full.tf.erb

@@ -0,0 +1,33 @@
+resource "google_scc_management_organization_security_health_analytics_custom_module" "<%= ctx[:primary_resource_id] %>" {
+  organization = "<%= ctx[:test_env_vars]['org_id'] %>"
+  display_name = "<%= ctx[:vars]['display_name'] %>"
+  location = "global"
+  enablement_state = "ENABLED"
+  custom_config {
+    predicate {
+      expression = "resource.rotationPeriod > duration(\"2592000s\")"
+      title = "Purpose of the expression"
+      description = "description of the expression"
+      location = "location of the expression"
+    }
+    custom_output {
+      properties {
+        name = "duration"
+        value_expression {
+          expression = "resource.rotationPeriod"
+          title = "Purpose of the expression"
+          description = "description of the expression"
+          location = "location of the expression"
+        }
+      }
+    }
+    resource_selector {
+      resource_types = [
+        "cloudkms.googleapis.com/CryptoKey",
+      ]
+    }
+    severity = "LOW"
+    description = "Description of the custom module"
+    recommendation = "Steps to resolve violation"
+  }
+}