Overview of custom modules for Security Health Analytics

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

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

You can detect things with custom modules that you cannot detect with the built-in Security Health Analytics detectors; however, built-in detectors support certain Security Command Center features that custom modules do not.

Feature support

Security Health Analytics custom modules are not supported by attack path simulations, so findings that are produced by custom modules do not get 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 issues 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 state property, which you can use to ignore instances if the value is set to MAINTENANCE or trigger findings if the value is something else.
• The value of the region property, 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.

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 Security Health Analytics custom detection modules, you need the following permissions, which are contained in the IAM role Security Center Management SHA Custom Modules Viewer (roles/securitycentermanagement.shaCustomModulesViewer):
  • securitycentermanagement.securityHealthAnalyticsCustomModules.list
  • securitycentermanagement.securityHealthAnalyticsCustomModules.get
  • securitycentermanagement.effectiveSecurityHealthAnalyticsCustomModules.list
  • securitycentermanagement.effectiveSecurityHealthAnalyticsCustomModules.get
  • securitycentermanagement.securityHealthAnalyticsCustomModules.simulate
  • securitycentermanagement.securityHealthAnalyticsCustomModules.test
• To edit Security Health Analytics 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 SHA Custom Modules Editor (securitycentermanagement.shaCustomModulesEditor):
  • securitycentermanagement.securityHealthAnalyticsCustomModules.create
  • securitycentermanagement.securityHealthAnalyticsCustomModules.update
  • securitycentermanagement.securityHealthAnalyticsCustomModules.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 Security Health Analytics 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	Roles
securitycenter.securityhealthanalyticscustommodules.create securitycenter.securityhealthanalyticscustommodules.update securitycenter.securityhealthanalyticscustommodules.delete	roles/securitycenter.settingsEditor roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.get securitycenter.securityhealthanalyticscustommodules.list	roles/securitycenter.settingsViewer roles/securitycenter.adminViewer roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.test	roles/securitycenter.securityHealthAnalyticsCustomModulesTester roles/securitycenter.adminViewer roles/securitycenter.adminEditor roles/securitycenter.admin

The following table contains a list of Security Health Analytics 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 on or after January 22, 2024	Roles
securitycentermanagement.securityHealthAnalyticsCustomModules.create securitycentermanagement.securityHealthAnalyticsCustomModules.update securitycentermanagement.securityHealthAnalyticsCustomModules.delete securitycentermanagement.securityHealthAnalyticsCustomModules.list securitycentermanagement.securityHealthAnalyticsCustomModules.get securitycentermanagement.effectiveSecurityHealthAnalyticsCustomModules.list securitycentermanagement.effectiveSecurityHealthAnalyticsCustomModules.get securitycentermanagement.securityHealthAnalyticsCustomModules.simulate securitycentermanagement.securityHealthAnalyticsCustomModules.test	roles/securitycentermanagement.shaCustomModulesEditor roles/securitycenter.settingsEditor roles/securitycenter.admin
securitycentermanagement.securityHealthAnalyticsCustomModules.list securitycentermanagement.securityHealthAnalyticsCustomModules.get securitycentermanagement.effectiveSecurityHealthAnalyticsCustomModules.list securitycentermanagement.effectiveSecurityHealthAnalyticsCustomModules.get securitycentermanagement.securityHealthAnalyticsCustomModules.simulate securitycentermanagement.securityHealthAnalyticsCustomModules.test	roles/securitycentermanagement.shaCustomModulesViewer roles/securitycenter.settingsViewer roles/securitycenter.adminViewer roles/securitycenter.admin

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

Address

compute.googleapis.com/Address

Alert Policy

monitoring.googleapis.com/AlertPolicy

AlloyDB for PostgreSQL

alloydb.googleapis.com/Backup

alloydb.googleapis.com/Cluster

alloydb.googleapis.com/Instance

Artifact Registry Repository

artifactregistry.googleapis.com/Repository

Autoscaler

compute.googleapis.com/Autoscaler

Backend Bucket

compute.googleapis.com/BackendBucket

Backend Service

compute.googleapis.com/BackendService

BigQuery Data Transfer Service

bigquerydatatransfer.googleapis.com/TransferConfig

BigQuery Table

bigquery.googleapis.com/Table

Bucket

storage.googleapis.com/Bucket

Cloud Data Fusion

datafusion.googleapis.com/Instance

Cloud Function

cloudfunctions.googleapis.com/CloudFunction

Cloud Run

run.googleapis.com/DomainMapping

run.googleapis.com/Execution

run.googleapis.com/Job

run.googleapis.com/Revision

run.googleapis.com/Service

Cluster

container.googleapis.com/Cluster

Cluster Role

rbac.authorization.k8s.io/ClusterRole

Cluster Role Binding

rbac.authorization.k8s.io/ClusterRoleBinding

Commitment

compute.googleapis.com/Commitment

Composer Environment

composer.googleapis.com/Environment

Compute Project

compute.googleapis.com/Project

compute.googleapis.com/SecurityPolicy

CryptoKey

cloudkms.googleapis.com/CryptoKey

CryptoKey Version

cloudkms.googleapis.com/CryptoKeyVersion

Dataflow Job

dataflow.googleapis.com/Job

Dataproc Cluster

dataproc.googleapis.com/Cluster

Dataproc Job

dataproc.googleapis.com/Job

Dataset

bigquery.googleapis.com/Dataset

Datastream Connection Profile

datastream.googleapis.com/ConnectionProfile

Datastream Private Connection

datastream.googleapis.com/PrivateConnection

Datastream Stream

datastream.googleapis.com/Stream

Disk

compute.googleapis.com/Disk

DNS Policy

dns.googleapis.com/Policy

File Instance

file.googleapis.com/Instance

Firewall

compute.googleapis.com/Firewall

Firewall Policy

compute.googleapis.com/FirewallPolicy

Folder

cloudresourcemanager.googleapis.com/Folder

Forwarding Rule

compute.googleapis.com/ForwardingRule

Global Forwarding Rule

compute.googleapis.com/GlobalForwardingRule

Health Check

compute.googleapis.com/HealthCheck

Hub

gkehub.googleapis.com/Feature

gkehub.googleapis.com/Membership

IAM Role

iam.googleapis.com/Role

Image

compute.googleapis.com/Image

Instance

compute.googleapis.com/Instance

Instance Group

compute.googleapis.com/InstanceGroup

Instance Group Manager

compute.googleapis.com/InstanceGroupManagers

Instance Template

compute.googleapis.com/InstanceTemplate

Interconnect Attachment

compute.googleapis.com/InterconnectAttachment

Keyring

cloudkms.googleapis.com/KeyRing

KMS Import Job

cloudkms.googleapis.com/ImportJob

Kubernetes CronJob

k8s.io/CronJob

Kubernetes DaemonSet

k8s.io/DaemonSet

Kubernetes Deployment

k8s.io/Deployment

Kubernetes Ingress

k8s.io/Ingress

Kubernetes NetworkPolicy

k8s.io/NetworkPolicy

Kubernetes ReplicaSet

k8s.io/ReplicaSet

Kubernetes Service

k8s.io/Service

Kubernetes StatefulSet

k8s.io/StatefulSet

Log Bucket

logging.googleapis.com/LogBucket

Log Metric

logging.googleapis.com/LogMetric

Log Sink

logging.googleapis.com/LogSink

Managed Zone

dns.googleapis.com/ManagedZone

Machine Image

compute.googleapis.com/MachineImage

Namespace

k8s.io/Namespace

NetApp Volume

netapp.googleapis.com/Volume

Network

compute.googleapis.com/Network

Network Endpoint Group

compute.googleapis.com/NetworkEndpointGroup

Node

k8s.io/Node

Node Group

compute.googleapis.com/NodeGroup

Node Template

compute.googleapis.com/NodeTemplate

Nodepool

container.googleapis.com/NodePool

Organization

cloudresourcemanager.googleapis.com/Organization

Organization Policy Service v2

orgpolicy.googleapis.com/CustomConstraint

orgpolicy.googleapis.com/Policy

Packet Mirroring

compute.googleapis.com/PacketMirroring

Pod

k8s.io/Pod

Private CA Certificate

privateca.googleapis.com/Certificate

Project

cloudresourcemanager.googleapis.com/Project

Pubsub Snapshot

pubsub.googleapis.com/Snapshot

Pubsub Subscription

pubsub.googleapis.com/Subscription

Pubsub Topic

pubsub.googleapis.com/Topic

Region Backend Service

compute.googleapis.com/RegionBackendService

Region Disk

compute.googleapis.com/RegionDisk

Reservation

compute.googleapis.com/Reservation

Resource Policy

compute.googleapis.com/ResourcePolicy

Route

compute.googleapis.com/Route

Router

compute.googleapis.com/Router

Role

rbac.authorization.k8s.io/Role

Role Binding

rbac.authorization.k8s.io/RoleBinding

Secret Manager

secretmanager.googleapis.com/Secret

Secret Version

secretmanager.googleapis.com/SecretVersion

Service Account Key

iam.googleapis.com/ServiceAccountKey

ServiceUsage Service

serviceusage.googleapis.com/Service

Snapshot

compute.googleapis.com/Snapshot

Spanner Database

spanner.googleapis.com/Database

Spanner Instance

spanner.googleapis.com/Instance

SQL Instance

sqladmin.googleapis.com/Instance

SSL Certificate

compute.googleapis.com/SslCertificate

SSL Policy

compute.googleapis.com/SslPolicy

Subnetwork

compute.googleapis.com/Subnetwork

Tag Binding

cloudresourcemanager.googleapis.com/TagBinding

Target HTTP Proxy

compute.googleapis.com/TargetHttpProxy

Target HTTPS Proxy

compute.googleapis.com/TargetHttpsProxy

Target Instance

compute.googleapis.com/TargetInstance

Target Pool

compute.googleapis.com/TargetPool

Target SSL Proxy

compute.googleapis.com/TargetSslProxy

Target VPN Gateway

compute.googleapis.com/TargetVpnGateway

URL Map

compute.googleapis.com/UrlMap

Vertex AI

aiplatform.googleapis.com/BatchPredictionJob

aiplatform.googleapis.com/CustomJob

aiplatform.googleapis.com/Dataset

aiplatform.googleapis.com/Endpoint

aiplatform.googleapis.com/HyperparameterTuningJob

aiplatform.googleapis.com/Model

aiplatform.googleapis.com/SpecialistPool

aiplatform.googleapis.com/TrainingPipeline

Vertex AI Workbench

notebooks.googleapis.com/Instance

VMware Engine

vmwareengine.googleapis.com/Cluster

vmwareengine.googleapis.com/ExternalAccessRule

vmwareengine.googleapis.com/ExternalAddress

vmwareengine.googleapis.com/NetworkPeering

vmwareengine.googleapis.com/NetworkPolicy

vmwareengine.googleapis.com/PrivateCloud

vmwareengine.googleapis.com/PrivateConnection

VPC Connector

vpcaccess.googleapis.com/Connector

VPN Gateway

compute.googleapis.com/VpnGateway

VPN Tunnel

compute.googleapis.com/VpnTunnel

Workstations

workstations.googleapis.com/Workstation

workstations.googleapis.com/WorkstationConfig

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.