Use custom modules for Security Health Analytics

Google Cloud console

To create a custom module in the Google Cloud console, complete the following steps:

1. Go to the Security Command Center Settings page in the Google Cloud console.

   Go to Settings

2. If prompted, select the organization, folder, or project in which you need to create the custom module.

3. On the Security Health Analytics card, click Manage Settings.

4. Click the Modules tab.

5. Click add_box Create module. The Create module for Security Health Analytics page opens.

6. On the Configure module panel, define the display name, resources to scan, and the detection logic:

   1. In the Module name field, specify a name for the module. The name must be between 1 and 128 characters, start with a lowercase letter, and contain alphanumeric characters or underscores only. This name becomes the finding category of the findings that this detector produces. You can't change the name after the module is created.

   2. Under Add resource type, specify one to five resource types to scan. You cannot specify a resource type more than once.

      For a list of supported resource types, see Supported resource types.

   3. In the Expression editor, write CEL expressions to run boolean checks on one or more properties of the resource that you specified in the last step. To trigger a finding, the expression must resolve to TRUE. For example, the following expression triggers a finding if a CryptoKey resource has a rotation period defined and the rotation period is longer than 2,592,000 seconds (30 days):

      has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))
      

      For more information, see the following:

      • Write CEL expressions
      • Referencing resource and policy properties in custom modules
      • List of Standard CEL Definitions

   4. Click Next. The Define finding details panel opens.

7. On the Define finding details panel, describe the issue that the custom module detects, including its severity, what the issue is, how to fix the issue, and any data that you want to include in the findings as custom source properties:

   1. In the Severity field, specify the severity of the issue. You can specify Low, Medium, High, or Critical. Medium is the default.

      For information about severity levels, see Severity classifications for findings.

   2. In the Finding description field, explain the issue that the custom module detects. This explanation appears in each finding instance to help security teams understand and address the detected issue.

   3. In the Finding next steps field, explain the steps that your security team can take to fix or otherwise address the detected issue.

      The steps display with each finding instance. Include specific steps that the security team can take to address the issue as quickly as possible.

   4. Optional: In the Custom finding properties field, specify up to 10 name-value pairs to define custom source properties to return with each finding instance. The information is returned as source properties in the finding JSON and is displayed on the Source properties tab in the finding details in the Google Cloud console. Specify the text or property values as key-value pairs:

      • In the Property name field, specify a name for the custom source property. The name must conform to the following rules:
        • The name must begin with a lowercase letter.
        • The name must contain only alphanumeric characters or underscores.
        • The name must be between 1 and 128 characters in length.
        • Each name must be unique among the other source properties.
      • In the Property value field, specify one of the following values in 1024 characters or less:
        • A text string enclosed in quotation marks. The quotation marks are included in the 1024 character limit. For example, "This string provides additional useful information."
        • Any property of the resource that is being scanned. For example, if you are checking the CryptoKey resource, you might specify resource.rotationPeriod. The value of the rotationPeriod property is returned.

   5. Click Next. The Enable module panel opens.

8. Optional: Use the drop-down menu of the Enable module panel to specify whether the custom module is enabled or disabled upon creation. By default, custom modules are enabled upon creation. If you specify Disable, you can enable the module later on the Modules tab in the Security Health Analytics settings page.

9. Click Next. The Test module panel opens.

10. Optional: Before you create your custom module, we recommend that you test it.

    To test a custom module, follow these steps:

    1. Create a YAML file that contains test resource definitions for the resources that your custom module checks.

       For information about how to create a test data file, see Create test resources in a YAML file.

    2. Under Upload the YAML file, click Browse to upload the YAML file that contains the test resource definitions. The test starts automatically when the file is uploaded.

    3. Under Test results preview, check the results.

       • If there are syntax or other errors in your YAML file, a floating error message displays near the bottom of the browser page.

       • If the test is a success, the test returns the following information:

         • The display name of the custom module.
         • The arbitrary name that you specified on the resource property in the test data file.
         • The organization, folder, or project in which the custom module was, or will be, created.

    Test results are not stored or written to Security Command Center.

    For more information, see Testing custom modules.

11. Click Create. You are returned to the Modules page and should see the module that you created with a status of Enabled.

New custom modules are not immediately available for use by Security Health Analytics in scans. For more information, see Detection latency.

gcloud CLI

To create a custom module by using gcloud commands, you first need to code the definition of the custom module in a YAML file that includes CEL expressions for the detection logic and output properties.

After the definition is complete, you upload the definition to Security Command Center by using gcloud CLI commands.

1. Code a custom module definition in a YAML file according to the instructions in Code a custom module for Security Health Analytics.
2. Save the YAML file to a location that is accessible to your instance of gcloud CLI.

3. Upload the custom definition to Security Command Center:

   gcloud scc custom-modules sha create \
       PARENT_FLAG=PARENT_ID \
       --display-name="MODULE_DISPLAY_NAME" \
       --enablement-state="ENABLEMENT_STATE" \
       --custom-config-from-file=MODULE_FILE_NAME.yaml
   

   Replace the following:

   • PARENT_FLAG: the level at which you are creating the custom module, either --organization, --folder, or --project.
   • PARENT_ID: the ID of the organization, folder, or project in which you are creating the custom module.
   • ENABLEMENT_STATE: either enabled or disabled.
   • MODULE_DISPLAY_NAME: the finding category name that you want to display when the custom module returns a finding. The name must be between 1 and 128 characters, start with a lowercase letter, and contain alphanumeric characters or underscores only.
   • MODULE_FILE_NAME: the path and filename of the YAML file that contains the definition of the custom module.

Terraform

Create a custom module for an organization:

resource "google_scc_management_organization_security_health_analytics_custom_module" "example" {
  organization = "123456789"
  display_name = "basic_custom_module"
  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"
  }
}

Create a custom module for a folder:

resource "google_folder" "folder" {
  parent       = "organizations/123456789"
  display_name = "folder-name"
  deletion_protection = false
}

resource "google_scc_management_folder_security_health_analytics_custom_module" "example" {
  folder = google_folder.folder.folder_id
  location = "global"
  display_name = "basic_custom_module"
  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"
  }
}

Create a custom module for a project:

resource "google_scc_management_project_security_health_analytics_custom_module" "example" {
  location = "global"
  display_name = "basic_custom_module"
  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"
  }
}

Google Cloud console

To update an existing custom module in the Google Cloud console, follow these steps:

1. Go to the Security Command Center Settings page in the Google Cloud console.

   Go to Settings