This page provides an overview of Security Health Analytics custom modules. For information about built-in modules, see Security Health Analytics built-in detectors.
With custom modules, you can extend Security Health Analytics's detection capabilities by creating custom detectors that scan the Google Cloud resources and policies that you specify using rules that you define to check for vulnerabilities, misconfigurations, or compliance violations.
The configuration or definition of a custom module, whether you create it in the Google Cloud console or code it yourself, determines the resources that the detector checks, the properties the detector evaluates, and the information that the detector returns when a vulnerability or misconfiguration is detected.
You can create custom modules for any resource or asset that Security Command Center supports.
If you code custom module definitions yourself, you use YAML and Common Expression Language (CEL) expressions. If you use the Google Cloud console to create your custom modules, most of the coding is done for you, although you do need to code the CEL expressions.
For an example of custom module definition in a YAML file, see Example custom module definition.
Custom modules run alongside Security Health Analytics's built-in detectors in both real-time and batch scans. In real-time mode, scans are triggered whenever an asset's configuration changes. Batch-mode scans run with all detectors for enrolled organizations or projects once a day.
During a scan, each custom detector is applied to all matching assets in each organization, folder, or project for which it is enabled.
Findings from custom detectors are written to Security Command Center.
For more information, see the following:
- Creating custom modules
- Security Health Analytics scan types
- Supported resource types
- YAML
- Introduction to CEL
Comparing built-in detectors and custom modules
Custom modules offer broader detection capabilities than built-in Security Health Analytics detectors. However, custom modules lack support for some Security Command Center features that the built-in detectors provide.
Feature support
Security Health Analytics custom modules are not supported by attack path simulations. Findings that are produced by custom modules don't include attack exposure scores or attack paths.
Comparing detection logic
As an example of some of the things that you can do with a
custom module, compare what the built-in detector PUBLIC_SQL_INSTANCE
checks for with what you can do with a custom module.
The built-in detector PUBLIC_SQL_INSTANCE checks whether the
authorizedNetworks property of Cloud SQL instances is set to 0.0.0.0/0.
If it is, the detector generates a finding that states that the Cloud SQL
instance is open to the public, because it accepts connections from all IP
addresses.
With a custom module, you can implement more complex detection logic to check Cloud SQL instances for things like:
- IP addresses with specific prefixes, by using wildcards.
- The value of the
stateproperty, which you can use to ignore instances if the value is set toMAINTENANCEor trigger findings if the value is something else. - The value of the
regionproperty, which you can use to trigger findings only for instances with public IP addresses in specific regions.
Required IAM roles and permissions
IAM roles determine the actions that you can perform with Security Health Analytics custom modules.
The following table contains a list of Security Health Analytics 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 | Roles |
|---|---|
securitycentermanagement.securityHealthAnalyticsCustomModules.create |
roles/securitycentermanagement.shaCustomModulesEditor |
securitycentermanagement.securityHealthAnalyticsCustomModules.list |
roles/securitycentermanagement.shaCustomModulesViewer
|
For more information about IAM permissions and roles and how to grant them, see Grant an IAM role by using the Google Cloud console.
Custom module quotas
Security Health Analytics custom modules are subject to quota limits.
The default quota limit for the creation of custom modules is 100, but you can request a quota increase, if necessary.
API calls to custom module methods are also subject to quota limits. The following table shows the default quota limits for custom module API calls.
| API Call Type | Limit |
|---|---|
| CustomModules Read Requests (Get, List) | 1,000 API calls per minute, per organization |
| CustomModules Write Requests (Create, Update, Delete) | 60 API calls per minute, per organization |
| CustomModules Test Requests | 12 API calls per minute, per organization |
For quota increases, submit a request in the Google Cloud console on the Quotas page.
For more information about Security Command Center quotas, see Quotas and limits.
Supported resource types
This section summarizes the Google Cloud resource types supported with custom modules.
What's next
- To work with custom modules, see Using custom modules for Security Health Analytics.
- To code custom module definitions yourself, see Code custom modules for Security Health Analytics.
- To test your custom modules, see Test custom modules for Security Health Analytics.