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 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 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 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 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

Permissions required	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

Access Context Manager: accesscontextmanager.googleapis.com/AccessLevel; accesscontextmanager.googleapis.com/AccessPolicy; accesscontextmanager.googleapis.com/ServicePerimeter
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
Api Keys: apikeys.googleapis.com/Key
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 Model: bigquery.googleapis.com/Model
BigQuery Table: bigquery.googleapis.com/Table
Bucket: storage.googleapis.com/Bucket
Cloud Billing Project Billing Info: cloudbilling.googleapis.com/ProjectBillingInfo
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 Autoscaling Policy: dataproc.googleapis.com/AutoscalingPolicy
Dataproc Batch: dataproc.googleapis.com/Batch
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
Dialogflow CX: dialogflow.googleapis.com/Agent
Disk: compute.googleapis.com/Disk
DLP Deidentify Template: dlp.googleapis.com/DeidentifyTemplate
DLP Inspect Template: dlp.googleapis.com/InspectTemplate
DLP Job: dlp.googleapis.com/DlpJob
DLP Job Trigger: dlp.googleapis.com/JobTrigger
DLP Stored Info Type: dlp.googleapis.com/StoredInfoType
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
Monitoring Notification Channel: monitoring.googleapis.com/NotificationChannel
Namespace: k8s.io/Namespace
NetApp Snapshot: netapp.googleapis.com/Snapshot
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
Private CA Certificate Revocation List: privateca.googleapis.com/CertificateRevocationList
Project: cloudresourcemanager.googleapis.com/Project
Pubsub Snapshot: pubsub.googleapis.com/Snapshot
Pubsub Subscription: pubsub.googleapis.com/Subscription
Pubsub Topic: pubsub.googleapis.com/Topic
Redis Cluster: redis.googleapis.com/Cluster
Redis Instance: redis.googleapis.com/Instance
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 Backup: spanner.googleapis.com/Backup
Spanner Database: spanner.googleapis.com/Database
Spanner Instance: spanner.googleapis.com/Instance
SQL Backup Run: sqladmin.googleapis.com/BackupRun
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/Featurestore; aiplatform.googleapis.com/HyperparameterTuningJob; aiplatform.googleapis.com/Index; aiplatform.googleapis.com/MetadataStore; aiplatform.googleapis.com/Model; aiplatform.googleapis.com/SpecialistPool; aiplatform.googleapis.com/Tensorboard; aiplatform.googleapis.com/TrainingPipeline; aiplatform.googleapis.com/NotebookRuntimeTemplate
Vertex AI Workbench: notebooks.googleapis.com/Instance
VMware Engine: vmwareengine.googleapis.com/Cluster; vmwareengine.googleapis.com/ExternalAccessRule; vmwareengine.googleapis.com/ExternalAddress; vmwareengine.googleapis.com/VmwareEngineNetwork; 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 .