Overview of custom modules for Security Health Analytics

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:

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.

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
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
Image
compute.googleapis.com/Image
Instance
compute.googleapis.com/Instance
Instance Group
compute.googleapis.com/InstanceGroup
Instance Group Manager
compute.googleapis.com/InstanceGroupManagers
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
Namespace
k8s.io/Namespace
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
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
Router
compute.googleapis.com/Router
Role
rbac.authorization.k8s.io/Role
Role Binding
rbac.authorization.k8s.io/RoleBinding
Secret Manager
secretmanager.googleapis.com/Secret
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
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
VPC Connector
vpcaccess.googleapis.com/Connector
VPN Gateway
compute.googleapis.com/VpnGateway
VPN Tunnel
compute.googleapis.com/VpnTunnel

What's next