Code a custom module for Security Health Analytics

This page explains how to code a custom module definition by using the Common Expression Language (CEL) and YAML.

Use the Google Cloud CLI to upload your custom module definitions to Security Health Analytics.

In the YAML file, a custom module definition consists of a structured set of properties that you use to define the following elements of a Security Health Analytics custom module:

The resources to scan.
The detection logic to use.
The information to provide to your security teams so that they can quickly understand, triage, and resolve the detected issue.

The specific required and optional properties that make up a YAML definition are covered in Coding steps.

Avoid creating redundant detectors

To control finding volume, avoid creating and running modules that contain redundant functionality.

For example, if you create a custom module that checks for encryption keys that are not rotated after 30 days, consider disabling the built-in Security Health Analytics detector KMS_KEY_NOT_ROTATED, because its check, which uses a value of 90 days, would be superfluous.

For more information on disabling detectors, see Enable and disable detectors.

Coding steps

You code the definition of a custom module for Security Health Analytics as a series of YAML properties, some of which contain CEL expressions.

To code a custom definition module, follow these steps:

Create a text file with the yaml filename extension.
In the text file, create a resource_selector property and specify one to five resource types for the custom module to scan. A resource type cannot be specified more than once in a custom module definition. For example:
```
resource_selector:
 resource_types:
 ‐ cloudkms.googleapis.com/CryptoKey
```
The resource types that you specify must be supported by Security Command Center. For a list of supported resource types, see Supported resource types.
Create a predicate property and specify one or more CEL expressions that check properties of the resource types to be scanned. Any properties the you reference in the CEL expressions must exist in the Google Cloud API definition of each resource type that you specify under resource_selector. To trigger a finding, the expression must resolve to TRUE. For example, in the following expression, only rotationPeriod values greater than 2592000s trigger a finding.
```
predicate:
 expression: resource.rotationPeriod > duration("2592000s")
```
For help writing CEL expressions, see the following resources:
- Supported resource types. Click on each resource to see the properties that you can use in your CEL expressions.
- Writing CEL expressions.
- Referencing resource and policy properties in custom modules.
Create a description property that explains the vulnerability or misconfiguration that the custom module detects. This explanation appears in each finding instance to help investigators understand the detected issue. The text must be enclosed in quotation marks. For example:
```
description: "The rotation period of
 the identified cryptokey resource exceeds 30 days, the
 maximum rotation period that our security guidelines allow."
```
Create a recommendation property that explains how to fix the detected issue. The gcloud CLI requires an escape character before certain characters, such as quotation marks. The following example shows the use of the backslash to escape each set of quotation marks:
```
recommendation: "To fix this issue go to
  https://console.cloud.google.com/security/kms. Click the key-ring that
  contains the key. Click the key. Click \"Edit rotation period\". Then
  set the rotation period to at most 30 days."
```
If you create or update a custom module by using the Google Cloud console, escape characters are not required.
Create a severity property and specify the default severity for the findings that are created by this module. Commonly used values for the severity property are LOW, MEDIUM, HIGH, and CRITICAL. For example,
```
severity: MEDIUM
```
Optionally, create a custom_output property and specify additional information to return with each finding. Specify the information to return as one or more name-value pairs. You can return either the value of a property of the scanned resource or a literal string. Properties must be specified as resource.PROPERTY_NAME. Literal strings must be enclosed in quotation marks. The following example shows a custom_output definition that returns both a property value, the value of rotationPeriod in the scanned CryptoKey resource, and a text string, "Excessive rotation period for CryptoKey":
```
 custom_output:
   properties:
     - name: duration
       value_expression:
         expression: resource.rotationPeriod
     - name: note
       value_expression:
         expression: "'Excessive rotation period for CryptoKey'"
```
Save the file to a location that your gcloud CLI can access.
Upload the definition to Security Health Analytics with the following command:
```
 gcloud scc custom-modules sha create \
     --organization=organizations/ORGANIZATION_ID \
     --display-name="MODULE_DISPLAY_NAME" \
     --enablement-state="ENABLED" \
     --custom-config-from-file=DEFINITION_FILE_NAME.yaml
```
Replace the following values:
- ORGANIZATION_ID with the ID of the parent organization of the custom module or replace the --organization flag with either --folders or --project and specify the ID of the parent folder or project.
- MODULE_DISPLAY_NAME with a name to display as the finding category when the custom module returns findings. The name must be between 1 and 128 characters, start with a lowercase letter, and contain alphanumeric characters or underscores only.
- DEFINITION_FILE_NAME with the path and file name of the YAML file that contains the definition of the custom module.
For more information about working with Security Health Analytics custom modules, see Using custom modules for Security Health Analytics.

Scan latencies for new custom modules

Creating a custom module does not trigger a new scan.

Security Health Analytics doesn't start using a new custom module until either of the following:

The first batch scan after you create the custom module. Depending on when you create a custom module in your batch-scan schedule, you might have to wait up to 24 hours before Security Health Analytics starts using the custom module.
A change to a target resource triggers a real-time scan.

Example custom module definition

The following example shows a completed custom module definition that triggers a finding if the value of the rotationPeriod property of a cloudkms.googleapis.com/CryptoKey resource is greater than 2,592,000 seconds (30 days). The example returns two optional values in the custom_output section: the value of resource.rotationPeriod and a note as a text string.

In the example, note the following elements:

The type of asset or resource to check is listed in the resource_selector section under resource_types.
The check that the module performs on the resources, its detection logic, is defined in the predicate section preceded by expression.
Two custom source properties, duration and violation, are defined in the custom_output section.
The explanation of the issue that was detected is specified in the description property.
The guidance for remediating the detected issue is specified on the recommendation property. Because quotation marks appear in the guidance, a backslash escape character is required before each quotation mark.

severity: HIGH
description: "Regular key rotation helps provide protection against
compromised keys, and limits the number of encrypted messages available
to cryptanalysis for a specific key version."