mmv1/products/securitycentermanagement/ProjectSecurityHealthAnalyticsCustomModule.yaml

# 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.

---
name: 'ProjectSecurityHealthAnalyticsCustomModule'
api_resource_type_kind: SecurityHealthAnalyticsCustomModule
api_variant_patterns:
  - 'projects/{project}/locations/{location}/securityHealthAnalyticsCustomModules/{securityHealthAnalyticsCustomModule}'
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:
  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/projects.locations.securityHealthAnalyticsCustomModules'
docs:
base_url: 'projects/{{project}}/locations/{{location}}/securityHealthAnalyticsCustomModules'
self_link: 'projects/{{project}}/locations/{{location}}/securityHealthAnalyticsCustomModules/{{name}}'
update_verb: 'PATCH'
update_mask: true
mutex: 'projects/{{project}}/locations/{{location}}/securityHealthAnalyticsCustomModules'
timeouts:
  insert_minutes: 20
  update_minutes: 20
  delete_minutes: 20
custom_code:
sweeper:
  url_substitutions:
    - region: "global"
examples:
  - name: 'scc_management_organization_project_security_health_analytics_custom_module_basic'
    primary_resource_id: 'example'
    vars:
      display_name: 'basic_custom_module'
    exclude_test: true
  - name: 'scc_management_organization_project_security_health_analytics_custom_module_full'
    primary_resource_id: 'example'
    vars:
      display_name: 'full_custom_module'
    exclude_test: true
parameters:
  - name: 'location'
    type: String
    description: |
      Location ID of the parent organization. If not provided, 'global' will be used as the default location.

    url_param_only: true
    required: false
    immutable: true
    default_value: "global"
properties:
  - name: 'name'
    type: String
    description: |
      The resource name of the custom module. Its format is "projects/{project}/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.
    output: true
    custom_flatten: 'templates/terraform/custom_flatten/name_from_self_link.tmpl'
  - name: 'displayName'
    type: String
    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.
    required: false
    immutable: true
    # API error for invalid display names is just "INVALID_ARGUMENT" with no details
    validation:
      function: 'verify.ValidateRegexp(`^[a-z][\w_]{0,127}$`)'
  - name: 'enablementState'
    type: Enum
    description: |
      The enablement state of the custom module.
    required: false
    enum_values:
      - 'ENABLED'
      - 'DISABLED'
  - name: 'updateTime'
    type: String
    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".
    output: true
  - name: 'lastEditor'
    type: String
    description: |
      The editor that last updated the custom module.
    output: true
  - name: 'ancestorModule'
    type: String
    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.
    output: true
  - name: 'customConfig'
    type: NestedObject
    description: |
      The user specified custom configuration for the module.
    required: false
    properties:
      - name: 'predicate'
        type: NestedObject
        description: |
          The CEL expression to evaluate to produce findings. When the expression evaluates
          to true against a resource, a finding is generated.
        required: true
        properties:
          - name: 'expression'
            type: String
            description: |
              Textual representation of an expression in Common Expression Language syntax.
            required: true
          - name: 'title'
            type: String
            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.
          - name: 'description'
            type: String
            description: |
              Description of the expression. This is a longer text which describes the
              expression, e.g. when hovered over it in a UI.
          - name: 'location'
            type: String
            description: |
              String indicating the location of the expression for error reporting, e.g. a
              file name and a position in the file.
      - name: 'customOutput'
        type: NestedObject
        description: |
          Custom output properties.
        properties:
          - name: 'properties'
            type: Array
            description: |
              A list of custom output properties to add to the finding.
            item_type:
              type: NestedObject
              properties:
                - name: 'name'
                  type: String
                  description: |
                    Name of the property for the custom output.
                - name: 'valueExpression'
                  type: NestedObject
                  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:
                    - name: 'expression'
                      type: String
                      description: |
                        Textual representation of an expression in Common Expression Language syntax.
                      required: true
                    - name: 'title'
                      type: String
                      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.
                    - name: 'description'
                      type: String
                      description: |
                        Description of the expression. This is a longer text which describes the
                        expression, e.g. when hovered over it in a UI.
                    - name: 'location'
                      type: String
                      description: |
                        String indicating the location of the expression for error reporting, e.g. a
                        file name and a position in the file.
      - name: 'resourceSelector'
        type: NestedObject
        description: |
          The resource types that the custom module operates on. Each custom module
          can specify up to 5 resource types.
        required: true
        properties:
          - name: 'resourceTypes'
            type: Array
            description: |
              The resource types to run the detector on.
            required: true
            item_type:
              type: String
      - name: 'severity'
        type: Enum
        description: |
          The severity to assign to findings generated by the module.
        required: true
        enum_values:
          - 'CRITICAL'
          - 'HIGH'
          - 'MEDIUM'
          - 'LOW'
      - name: 'description'
        type: String
        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.
      - name: 'recommendation'
        type: String
        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.
        required: true