Create and manage custom modules for Event Threat Detection

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.

Required IAM roles and permissions

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

The following table contains a list of Event Threat Detection custom module permissions that are required 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	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:

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.

Choose a template from Custom modules and templates.
Copy the code to a local file.
Update the parameters that you want to use to evaluate your logs.
Save the file as a JSON file.
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, the gcloud CLI, the REST API, and Terraform. Each Event Threat Detection custom module has a size limit of 6 MB.

To create a custom module, follow these steps:

Console

View the modules of the Event Threat Detection service. The predefined and custom modules appear in a list.
Click Create module.
Click the module template that you want to use.
Click Select.
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.
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.
Click Next.
For Severity, enter the severity level that you want to assign to findings generated by the new custom module.
For Description, enter a description for the new custom module.
For Next steps, enter the recommended actions in plain text format. Any paragraph breaks that you add are ignored.
Click Create.

gcloud

The gcloud scc manage custom-modules etd create command creates an Event Threat Detection custom module for an organization, folder, or project.

Before using any of the command data below, make the following replacements:

RESOURCE_TYPE: the type of resource that the custom modules belong to (organization, folder, or project)
RESOURCE_ID: the numeric identifier for the organization, folder, or project for the custom module. For projects, you can also use the alphanumeric project ID.
MODULE_CONFIG: the configuration settings for the custom module. Use a custom module template as a starting point.
MODULE_TYPE: the type of custom module. For a list of supported types, see Custom modules and templates.
MODULE_DISPLAY_NAME: the human-readable display name for the custom module. It can contain letters, numbers, and underscores (_). It can be up to 128 characters long.

Save the following content in a file called request.json:

{
  MODULE_CONFIG
}

Execute the gcloud scc manage custom-modules etd create command:

Linux, macOS, or Cloud Shell

gcloud scc manage custom-modules etd create \
    --RESOURCE_TYPE=RESOURCE_ID \
    --custom-config-file=request.json \
    --display-name=MODULE_DISPLAY_NAME \
    --module-type=MODULE_TYPE \
    --enablement-state=ENABLED

Windows (PowerShell)

gcloud scc manage custom-modules etd create `
    --RESOURCE_TYPE=RESOURCE_ID `
    --custom-config-file=request.json `
    --display-name=MODULE_DISPLAY_NAME `
    --module-type=MODULE_TYPE `
    --enablement-state=ENABLED

Windows (cmd.exe)

gcloud scc manage custom-modules etd create ^
    --RESOURCE_TYPE=RESOURCE_ID ^
    --custom-config-file=request.json ^
    --display-name=MODULE_DISPLAY_NAME ^
    --module-type=MODULE_TYPE ^
    --enablement-state=ENABLED

REST

The Security Command Center Management API's RESOURCE_TYPE.locations.eventThreatDetectionCustomModules.create method creates an Event Threat Detection custom module for an organization, folder, or project.

Before using any of the request data, make the following replacements:

RESOURCE_TYPE: the type of resource that the custom module belongs to (organizations, folders, or projects).
QUOTA_PROJECT: the project ID to use for billing and quota tracking.
RESOURCE_ID: the numeric identifier for the organization, folder, or project for the custom module. For projects, you can also use the alphanumeric project ID.
MODULE_CONFIG: the configuration settings for the custom module. Use a custom module template as a starting point.
MODULE_TYPE: the type of custom module. For a list of supported types, see Custom modules and templates.
MODULE_DISPLAY_NAME: the human-readable display name for the custom module. It can contain letters, numbers, and underscores (_). It can be up to 128 characters long.

HTTP method and URL:

POST https://securitycentermanagement.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/eventThreatDetectionCustomModules

Request JSON body:

{
  "config": MODULE_CONFIG,
  "enablementState": "ENABLED",
  "type": "MODULE_TYPE",
  "displayName": "MODULE_DISPLAY_NAME"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: QUOTA_PROJECT" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://securitycentermanagement.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/eventThreatDetectionCustomModules"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "QUOTA_PROJECT" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://securitycentermanagement.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/eventThreatDetectionCustomModules" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/1234567890123/locations/global/eventThreatDetectionCustomModules/98765432109876543210",
  "config": {
    "metadata": {
      "severity": "MEDIUM",
      "description": "An IAM custom role contains permissions that aren't allowed.",
      "recommendation": "Remove the permissions from the custom role."
    },
    "permissions": [
      "accessapproval.requests.get",
      "accessapproval.requests.invalidate",
      "accessapproval.requests.list",
      "accessapproval.settings.delete"
    ]
  },
  "enablementState": "ENABLED",
  "type": "CONFIGURABLE_CUSTOM_ROLE_WITH_PROHIBITED_PERMISSION",
  "displayName": "iam_custom_role_prohibited_permissions",
  "updateTime": "2026-03-16T19:44:58.588134Z"
}

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands. For more information, see the Terraform provider reference documentation.

resource "google_scc_management_organization_event_threat_detection_custom_module" "example" {
  organization = "123456789"
  location = "global"
  display_name = "basic_custom_module"
  enablement_state = "ENABLED"
  type = "CONFIGURABLE_BAD_IP"
  description = "My Event Threat Detection Custom Module"
  config = jsonencode({
    "metadata": {
      "severity": "LOW",
      "description": "Flagged by Forcepoint as malicious",
      "recommendation": "Contact the owner of the relevant project."
    },
    "ips": [
      "192.0.2.1",
      "192.0.2.0/24"
    ]
  })
}

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 or REST API.

Console

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

Go to Findings
Select your Google Cloud project or organization.
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.
To view the details of a specific finding, click the finding name in the Category column. The details panel for the finding opens and displays the Summary tab.
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.
Optional: To view the full JSON definition of the finding, click the JSON tab.

gcloud

Find the source ID

The gcloud scc sources describe command shows information about a findings source for Security Command Center.

Before using any of the command data below, make the following replacements:

RESOURCE_TYPE: the type of resource that the source belongs to (organizations, folders, or projects).
RESOURCE_ID: the numeric identifier for the organization, folder, or project. For projects, you can also use the alphanumeric project ID.

Execute the gcloud scc sources describe command:

Linux, macOS, or Cloud Shell

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

Windows (PowerShell)

gcloud scc sources describe RESOURCE_TYPE/RESOURCE_ID `
    --source-display-name="Event Threat Detection Custom Modules"

Windows (cmd.exe)

gcloud scc sources describe RESOURCE_TYPE/RESOURCE_ID ^
    --source-display-name="Event Threat Detection Custom Modules"

You should receive a response similar to the following:

canonicalName: organizations/123456789012/sources/98765432109876543210
description: Provider used by Event Threat Detection Custom Modules
displayName: Event Threat Detection Custom Modules
name: organizations/123456789012/sources/98765432109876543210

The source ID is the numeric value at the end of the canonicalName and name fields—for example, 98765432109876543210.

List all findings for Event Threat Detection custom modules

The gcloud scc findings list command lists findings for a source in a specific location.

Before using any of the command data below, make the following replacements:

RESOURCE_TYPE: the type of resource to get (organizations, folders, or projects).
RESOURCE_ID: the numeric identifier for the organization, folder, or project to get. For projects, you can also use the alphanumeric project ID.
LOCATION: the Security Command Center location to use, such as eu. If data residency is not enabled, use global.
SOURCE_ID: the numeric identifier for the findings source.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud scc findings list RESOURCE_TYPE/RESOURCE_ID \
    --source=SOURCE_ID \
    --location=LOCATION

Windows (PowerShell)

gcloud scc findings list RESOURCE_TYPE/RESOURCE_ID `
    --source=SOURCE_ID `
    --location=LOCATION

Windows (cmd.exe)

gcloud scc findings list RESOURCE_TYPE/RESOURCE_ID ^
    --source=SOURCE_ID ^
    --location=LOCATION

The response contains a list of findings.

List findings for a specific custom module

The gcloud scc findings list command lists findings for a source in a specific location.

Before using any of the command data below, make the following replacements:

RESOURCE_TYPE: the type of resource to get (organizations, folders, or projects).
RESOURCE_ID: the numeric identifier for the organization, folder, or project to get. For projects, you can also use the alphanumeric project ID.
LOCATION: the Security Command Center location to use, such as eu. If data residency is not enabled, use global.
SOURCE_ID: the numeric identifier for the findings source.
CUSTOM_MODULE_CATEGORY_NAME: the custom module's category name, composed of the module's finding category (as listed in Custom modules and templates); a colon; a space; and the module display name with spaces replaced by underscores. For example, Unexpected Compute Engine region: example_custom_module.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud scc findings list RESOURCE_TYPE/RESOURCE_ID \
    --source=SOURCE_ID \
    --location=LOCATION \
    --filter="category=\"CUSTOM_MODULE_CATEGORY_NAME\""

Windows (PowerShell)

gcloud scc findings list RESOURCE_TYPE/RESOURCE_ID `
    --source=SOURCE_ID `
    --location=LOCATION `
    --filter="category=\"CUSTOM_MODULE_CATEGORY_NAME\""

Windows (cmd.exe)

gcloud scc findings list RESOURCE_TYPE/RESOURCE_ID ^
    --source=SOURCE_ID ^
    --location=LOCATION ^
    --filter="category=\"CUSTOM_MODULE_CATEGORY_NAME\""

The response contains a list of findings.

REST

Find the source ID

The Security Command Center API's RESOURCE_TYPE.sources.list method lists information about Security Command Center finding sources.

Before using any of the request data, make the following replacements:

RESOURCE_TYPE: the type of parent resource (organizations, folders, or projects).

Create and manage custom modules for Event Threat Detection Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Security Command Center Premium and Event Threat Detection

Required IAM roles and permissions

Required logs

Custom module levels

Create custom modules

Template structure

Modify a module template

Create a custom module

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Terraform

Detection latency

Review findings

Console

gcloud

Find the source ID

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

List all findings for Event Threat Detection custom modules

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

List findings for a specific custom module

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

Find the source ID

Create and manage custom modules for Event Threat Detection