Create and manage custom modules for Event Threat Detection

Premium tier only: This feature is available only with the Security Command Center Premium tier.

This page explains how to create and manage custom modules for Event Threat Detection.

Before you begin

This section describes the requirements for using custom modules for Event Threat Detection.

Security Command Center Premium and Event Threat Detection

To use Event Threat Detection custom modules, Event Threat Detection must be enabled. To enable Event Threat Detection, see Enable or disable a built-in service.

IAM roles

IAM roles determine the actions that you can perform with Event Threat Detection custom modules.

Important: On or after January 22, 2024, the custom module functionality in the Google Cloud console will migrate to a new underlying API.

If your business uses custom IAM roles for strict control of access to Google Cloud resources, to continue working with custom modules in the Google Cloud console after that date, you need to ask your security administrator to add the following permissions to your custom role before the migration date, as appropriate to your responsibilities:

• To view or test Event Threat Detection custom detection modules, you need the following permissions, which are contained in the IAM role Security Center Management ETD Custom Modules Viewer (securitycentermanagement.etdCustomModulesViewer):
  • securitycentermanagement.eventThreatDetectionCustomModules.list
  • securitycentermanagement.eventThreatDetectionCustomModules.get
  • securitycentermanagement.effectiveEventThreatDetectionCustomModules.list
  • securitycentermanagement.effectiveEventThreatDetectionCustomModules.get
  • securitycentermanagement.eventThreatDetectionCustomModules.validate
• To edit Event Threat Detection custom detection modules, in addition to the preceding permissions, you also need the following permissions, which are contained in the IAM role Security Center Management Custom ETD Modules Editor (securitycentermanagement.etdCustomModulesEditor):
  • securitycentermanagement.eventThreatDetectionCustomModules.create
  • securitycentermanagement.eventThreatDetectionCustomModules.update
  • securitycentermanagement.eventThreatDetectionCustomModules.delete

If your business uses predefined IAM roles, you do not need to do anything. The new permissions are already included in the predefined roles.

The following table contains a list of Event Threat Detection custom module permissions and the predefined IAM roles that include them. These permissions are valid until at least January 22, 2024. After that date, the permissions that are listed in the second following table will be required.

You can use the Google Cloud console or Security Command Center API to apply these roles at the organization, folder, or project level.

Permissions required before January 22, 2024	Role
securitycenter.eventthreatdetectioncustommodules.create securitycenter.eventthreatdetectioncustommodules.update securitycenter.eventthreatdetectioncustommodules.delete	roles/securitycenter.settingsEditor roles/securitycenter.admin
securitycenter.eventthreatdetectioncustommodules.get securitycenter.eventthreatdetectioncustommodules.list	roles/securitycenter.settingsViewer roles/securitycenter.adminViewer roles/securitycenter.admin

The following table contains a list of Event Threat Detection custom module permissions that will be required on or after January 22, 2024, as well as the predefined IAM roles that include them.

You can use the Google Cloud console or Security Command Center API to apply these roles at the organization, folder, or project level.

Permissions required after January 22, 2024	Role
securitycentermanagement.eventThreatDetectionCustomModules.create securitycentermanagement.eventThreatDetectionCustomModules.update securitycentermanagement.eventThreatDetectionCustomModules.delete	roles/securitycentermanagement.etdCustomModulesEditor roles/securitycenter.settingsEditor roles/securitycenter.admin
securitycentermanagement.eventThreatDetectionCustomModules.list securitycentermanagement.eventThreatDetectionCustomModules.get securitycentermanagement.effectiveEventThreatDetectionCustomModules.list securitycentermanagement.effectiveEventThreatDetectionCustomModules.get securitycentermanagement.eventThreatDetectionCustomModules.validate	roles/securitycentermanagement.etdCustomModulesViewer roles/securitycentermanagement.etdCustomModulesEditor roles/securitycenter.adminViewer roles/securitycenter.admin

If you encounter access errors in Security Command Center, ask your administrator for assistance. See one of the following pages depending on the level at which you activated Security Command Center:

• IAM for organization-level activations of Security Command Center

• IAM for project-level activations of Security Command Center

Required logs

Make sure that the relevant logs are turned on for your organization, folders, and projects. For information about which logs are required by each custom module type, see the table in Custom modules and templates.

Logs from sources outside of Google Cloud aren't supported.

Custom module levels

This document uses the following terms to describe the level at which a custom module was created:

Residential module

The module was created at the current view or scope. For example, if you're in the organization view of the Google Cloud console, the residential modules are the modules that were created at the organization level.

Inherited module

The module was created at a parent view or scope. For example, a module created at organization level is an inherited module at any folder or project level.

Descendant module

The module was created at a child view or scope. For example, a module created at a folder or project level is a descendant module at the organization level.

Create custom modules

You can create Event Threat Detection custom modules through the Google Cloud console or by modifying a JSON template and submitting it through the gcloud CLI. You need JSON templates only if you plan to use the gcloud CLI to create custom modules.

For a list of supported module templates, see Custom modules and templates.

Template structure

Templates define the parameters that custom modules use to identify threats in your logs. Templates are written in JSON and are similar in structure to the findings generated by Security Command Center. You need to configure a JSON template only if you plan to use the gcloud CLI to create a custom module.

Each template contains customizable fields:

• severity: the severity or risk level you want assigned to findings of this type, LOW, MEDIUM, HIGH, or CRITICAL.
• description: the description of the custom module.
• recommendation: recommended actions for addressing findings generated by the custom module.
• Detection parameters: the variables used to evaluate logs and trigger findings. Detection parameters differ for each module, but they include one or more the following:
  • domains: web domains to watch for
  • ips: IP addresses to watch for
  • permissions: permissions to watch for
  • regions: regions where new Compute Engine instances are allowed
  • roles: roles to watch for
  • accounts: accounts to watch for
  • Parameters that define the allowed Compute Engine instance types—for example, series, cpus, and ram_mb.
  • Regular expressions to check properties against—for example, caller_pattern and resource_pattern.

The following code sample is an example JSON template for Configurable Bad IP.

{
  "metadata": {
    "severity": "LOW",
    "description": "Flagged by Cymbal as malicious",
    "recommendation": "Contact the owner of the relevant project."
  },
  "ips": [
    "192.0.2.1",
    "192.0.2.0/24"
  ]
}

In the preceding example, the custom module generates a low-severity finding if your logs indicate a resource connected to the IP address 192.0.2.1 or 192.0.2.0/24.

Modify a module template

To create modules, you choose a module template and modify it.

If you plan to use the Google Cloud CLI to create your custom module, you must perform this task.

If you plan to use the Google Cloud console to create your custom module, skip this task. You will use the options presented on the screen to modify the parameters of the template.

1. Choose a template from Custom modules and templates.
2. Copy the code to a local file.
3. Update the parameters that you want to use to evaluate your logs.
4. Save the file as a JSON file.
5. Create a custom module through the gcloud CLI using the JSON file.

Create a custom module

This section describes how to create a custom module through the Google Cloud console and through the gcloud CLI. Each Event Threat Detection custom module has a size limit of 6 MB.

To create a custom module, follow these steps:

Console

1. View the modules of the Event Threat Detection service. The predefined and custom modules appear in a list.
2. Click Create module.
3. Click the module template that you want to use.
4. Click Select.
5. For Module name, enter a display name for the new template. The name must not exceed 128 characters and must contain only alphanumeric characters and underscores—for example, example_custom_module.
6. Select or add the requested parameter values. The parameters differ for each module. For example, if you selected the Configurable allowed Compute Engine region module template, you select one or more regions. Alternatively, provide the list in JSON format.
7. Click Next.
8. For Severity, enter the severity level that you want to assign to findings generated by the new custom module.
9. For Description, enter a description for the new custom module.
10. For Next steps, enter the recommended actions in plain text format. Any paragraph breaks that you add are ignored.
11. Click Create.

gcloud

1. Create a JSON file containing the custom module's definition. Use the templates in Custom modules and templates as your guide.

2. Create the custom module by sending the JSON file in a gcloud command:

 gcloud alpha scc custom-modules etd create \
     --RESOURCE_FLAG=RESOURCE_ID \
     --display-name="DISPLAY_NAME" \
     --module-type="MODULE_TYPE" \
     --enablement-state="ENABLED" \
     --custom-config-from-file=PATH_TO_JSON_FILE

Replace the following:

• RESOURCE_FLAG: the scope of the parent resource where the custom module will be created; one of organization, folder, or project.
• RESOURCE_ID: the resource ID of the parent resource; that is, the organization ID, folder ID, or project ID.
• DISPLAY_NAME: a display name for the new template. The name must not exceed 128 characters and must contain only alphanumeric characters and underscores.
• MODULE_TYPE: the type of custom module that you want to create—for example, CONFIGURABLE_ALLOWED_COMPUTE_ENGINE_REGION.
• PATH_TO_JSON_FILE: the JSON file containing the custom module's JSON definition based on the module template.

Your custom module is created and starts scanning. To delete a module, see Delete a custom module.

The category name of the custom module contains the finding category of the module type and the module display name that you set. For example, the category name of a custom module can be Unexpected Compute Engine Region: example_custom_module. In the Google Cloud console, underscores are displayed as spaces. However, in your queries, you must include the underscores.

Quotas govern your use of custom modules for Event Threat Detection.

Detection latency

The detection latency for Event Threat Detection and all other built-in Security Command Center services are described in Scan latency.

Review findings

Findings generated by custom modules can be viewed in the Google Cloud console or by using the gcloud CLI.

Console

1. In the Google Cloud console, go to the Findings page of Security Command Center.

   Go to Findings

2. Select your Google Cloud project or organization.
3. In the Quick filters section, in the Source display name subsection, select Event Threat Detection Custom Modules. The findings query results are updated to show only the findings from this source.
4. To view the details of a specific finding, click the finding name under Category. The details panel for the finding opens and displays the Summary tab.
5. On the Summary tab, review the details of the finding, including information about what was detected, the affected resource, and—if available—steps that you can take to remediate the finding.
6. Optional: To view the full JSON definition of the finding, click the JSON tab.

gcloud

To use the gcloud CLI to view findings, do the following:

1. Open a terminal window.

2. Get the source ID for Event Threat Detection custom modules. The command depends on whether you activated Security Command Center at the organization level or the project level:

   gcloud scc sources describe RESOURCE_LEVEL/RESOURCE_ID \
       --source-display-name='Event Threat Detection Custom Modules'
   

   Replace the following:

   • RESOURCE_LEVEL: the activation level of your Security Command Center instance; one of organizations or projects.
   • RESOURCE_ID: the resource ID of your organization or project.

   The output resembles the following. SOURCE_ID is a server-assigned ID for security sources.

   canonicalName: RESOURCE_LEVEL/RESOURCE_ID/sources/SOURCE_ID
   description: Provider used by Event Threat Detection Custom Modules
   displayName: Event Threat Detection Custom Modules
   name: RESOURCE_LEVEL/RESOURCE_ID/sources/SOURCE_ID

3. To list all findings for Event Threat Detection custom modules, run the following command with the source ID from the previous step:

   gcloud scc findings list RESOURCE_LEVEL/RESOURCE_ID --source=SOURCE_ID
   

   Replace the following:

   • RESOURCE_LEVEL: the resource level in which you want to list findings; one of organizations, folders, or projects.
   • RESOURCE_ID: the ID of the resource; that is, the organization ID, folder ID, or project ID.
   • SOURCE_ID: the source ID for Event Threat Detection custom modules.

4. To list findings for a specific custom module, run the following command:

   MODULE="CUSTOM_MODULE_CATEGORY_NAME"
   FILTER="category=\"$MODULE\""
   gcloud scc findings list RESOURCE_LEVEL/RESOURCE_ID --source=SOURCE_ID --filter="$FILTER"
   

   Replace the following:

   • CUSTOM_MODULE_CATEGORY_NAME: the category name of the custom module. This name is composed of the finding category of the module type (as listed in Custom modules and templates) and the module display name with underscores instead of spaces. For example, the category name of a custom module can be Unexpected Compute Engine region: example_custom_module.
   • RESOURCE_LEVEL: the resource level in which you want to list findings; one of organizations, folders, or projects.
   • RESOURCE_ID: the ID of the resource; that is, the organization ID, folder ID, or project ID.
   • SOURCE_ID: the source ID of your Event Threat Detection custom modules.

To learn more about filtering findings, see Listing security findings.

Findings generated by custom modules can be managed like all findings in Security Command Center. For more information, see the following:

• Using security marks
• Setting up finding notifications
• Exporting Security Command Center data

Manage Event Threat Detection custom modules

This section describes how to view, list, update, and delete Event Threat Detection custom modules.

View or list custom modules

Console

1. View the modules of the Event Threat Detection service. The predefined and custom modules appear in a list.
2. Optional: To view only the custom modules, in the Filter field, enter Type:Custom.

The results include the following:

• All residential Event Threat Detection custom modules.
• All inherited Event Threat Detection custom modules. For example, if you're in the project view, the custom modules created in that project's parent folders and organization are included in the results.
• All descendant Event Threat Detection custom modules created in child resources. For example, if you're in the organization view, the custom modules that were created in folders and projects under that organization are included in the results.

gcloud

gcloud alpha scc custom-modules etd list \
    --RESOURCE_FLAG=RESOURCE_ID

Replace the following:

• RESOURCE_FLAG: the scope in which you want to list custom modules; one of organization, folder, or project.
• RESOURCE_ID: the ID of the resource; that is, the organization ID, folder ID, or project ID.

The results include the following:

• All residential Event Threat Detection custom modules.
• All inherited Event Threat Detection custom modules. For example, when you list custom modules at the project level, the custom modules created in that project's parent folders and organization are included in the results.

Each item in the results includes the module's name, status, and properties. The properties differ for each module.

The name of each module contains its custom module ID. Many gcloud operations on this page require the custom module ID.

name: RESOURCE_LEVEL/RESOURCE_ID/eventThreatDetectionSettings/customModules/CUSTOM_MODULE_ID

Disable a custom module

Console

See Enable or disable a module.

When you disable an inherited custom module, your changes are only applied to your current resource level. The original custom module residing at the parent level isn't affected. For example, if you're at the project level, and you disable a custom module that was inherited from the parent folder, the custom module is only disabled at the project level.

You can't disable a descendant custom module. For example, if you're in the organization view, you can't disable a custom module that was created at the project level.

gcloud

gcloud alpha scc custom-modules etd update CUSTOM_MODULE_ID \
    --RESOURCE_FLAG=RESOURCE_ID \
    --enablement-state="DISABLED"

Replace the following:

• CUSTOM_MODULE_ID: the numerical ID of the Event Threat Detection custom module—for example, 1234567890. You can get the numerical ID from the name field of the relevant custom module when you view the list of custom modules.
• RESOURCE_FLAG: the scope of the parent resource where the custom module resides; one of organization, folder, or project.
• RESOURCE_ID: the ID of the parent resource; that is, the organization ID, folder ID, or project ID.

Enable a custom module

Console

See Enable or disable a module.

When you enable an inherited custom module, your changes are only applied to your current resource level. The original custom module residing at the parent level isn't affected. For example, if you're at the project level, and you enable a custom module that was inherited from the parent folder, the custom module is only enabled at the project level.

You can't enable a descendant custom module. For example, if you're in the organization view, you can't enable a custom module that was created at the project level.

gcloud

gcloud alpha scc custom-modules etd update CUSTOM_MODULE_ID \
    --RESOURCE_FLAG=RESOURCE_ID \
    --enablement-state="ENABLED"

Replace the following:

• CUSTOM_MODULE_ID: the numerical ID of the Event Threat Detection custom module—for example, 1234567890. You can get the numerical ID from the name field of the relevant custom module when you view the list of custom modules.
• RESOURCE_FLAG: the scope of the parent resource where the custom module resides; one of organization, folder, or project.
• RESOURCE_ID: the ID of the parent resource; that is, the organization ID, folder ID, or project ID.

Update the definition of a custom module

This section describes how to update a custom module through the Google Cloud console and through the gcloud CLI. Each Event Threat Detection custom module has a size limit of 6 MB.

You can't update the module type of a custom module.

To update a custom module, follow these steps:

Console

You can edit only residential custom modules. For example, if you're in the organization view, you can edit only the custom modules that were created at the organization level.

1. View the modules of the Event Threat Detection service. The predefined and custom modules appear in a list.
2. Find the custom module that you want to edit.
3. For that custom module, click Actions > Edit.
4. Edit the custom module as needed.
5. Click Save.

gcloud

To update a module, run the following command and include the updated module template JSON:

 gcloud alpha scc custom-modules etd update CUSTOM_MODULE_ID \
     --RESOURCE_FLAG=RESOURCE_ID \
     --enablement-state="ENABLED" \
     --custom-config-from-file=PATH_TO_JSON_FILE

Replace the following:

• CUSTOM_MODULE_ID: the numerical ID of the Event Threat Detection custom module—for example, 1234567890. You can get the numerical ID from the name field of the relevant custom module when you view the list of custom modules.
• RESOURCE_FLAG: the scope of the parent resource where the custom module resides; one of organization, folder, or project.
• RESOURCE_ID: the ID of the parent resource; that is, the organization ID, folder ID, or project ID.
• PATH_TO_JSON_FILE: the JSON file containing the custom module's JSON definition.

Check the status of a single custom module

Console

1. View the modules of the Event Threat Detection service. The predefined and custom modules appear in a list.
2. Find the custom module from the list.

The status of the custom module is shown in the Status column.

gcloud

 gcloud alpha scc custom-modules etd get CUSTOM_MODULE_ID \
     --RESOURCE_FLAG=RESOURCE_ID

Replace the following:

• CUSTOM_MODULE_ID: the numerical ID of the Event Threat Detection custom module—for example, 1234567890. You can get the numerical ID from the name field of the relevant custom module when you view the list of custom modules.
• RESOURCE_FLAG: the scope of the parent resource where the custom module resides; one of organization, folder, or project.
• RESOURCE_ID: the ID of the parent resource; that is, the organization ID, folder ID, or project ID.

The output resembles the following and includes the module's status and properties. The properties differ for each module.

config:
metadata:
  description: DESCRIPTION
  recommendation: RECOMMENDATION
  severity: SEVERITY
regions:
- region: REGION
displayName: USER_SPECIFIED_DISPLAY_NAME
enablementState: STATUS
lastEditor: LAST_EDITOR
name: RESOURCE_LEVEL/RESOURCE_ID/eventThreatDetectionSettings/customModules/CUSTOM_MODULE_ID
type: MODULE_TYPE
updateTime: 'UPDATE_TIME'

Delete a custom module

When you delete an Event Threat Detection custom module, the findings that it has generated aren't modified and remain available in Security Command Center. In contrast, when you delete a Security Health Analytics custom module, its generated findings are marked as inactive.

You can't recover a deleted custom module.

Console

You can't delete inherited custom modules. For example, if you're in the project view, you can't delete custom modules that were created at the folder or organization level.

To delete a custom module through the Google Cloud console, do the following:

1. View the modules of the Event Threat Detection service. The predefined and custom modules appear in a list.
2. Find the custom module that you want to delete.
3. For that custom module, click Actions > Delete. A message appears prompting you to confirm the deletion.
4. Click Delete.

gcloud

 gcloud alpha scc custom-modules etd delete CUSTOM_MODULE_ID \
     --RESOURCE_FLAG=RESOURCE_ID

Replace the following:

• CUSTOM_MODULE_ID: the numerical ID of the Event Threat Detection custom module—for example, 1234567890. You can get the numerical ID from the name field of the relevant custom module when you view the list of custom modules.
• RESOURCE_FLAG: the scope of the parent resource where the custom module resides; one of organization, folder, or project.
• RESOURCE_ID: the ID of the parent resource; that is, the organization ID, folder ID, or project ID.

Clone a custom module

When you clone a custom module, the resulting custom module is created as a resident of the resource that you're viewing. For example, if you clone a custom module that your project inherited from the organization, the new custom module is a residential module in the project.

You can't clone a descendant custom module.

Note: There is no gcloud command for cloning a custom module. To emulate the cloning process, you can run a get command to get the settings of a custom module and then run a create command to create a new module with the same settings.

To clone a custom module through the Google Cloud console, do the following:

1. View the modules of the Event Threat Detection service. The predefined and custom modules appear in a list.
2. Find the custom module that you want to clone.
3. For that custom module, click Actions > Clone.
4. Edit the custom module as needed.
5. Click Create.

What's next

• Learn more about custom modules for Event Threat Detection.