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 toMAINTENANCE
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 |
roles/securitycenter.settingsEditor |
securitycenter.securityhealthanalyticscustommodules.get |
roles/securitycenter.settingsViewer |
securitycenter.securityhealthanalyticscustommodules.test |
roles/securitycenter.securityHealthAnalyticsCustomModulesTester |
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
|
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
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 DaemonSet
-
k8s.io/DaemonSet
Kubernetes Deployment
-
k8s.io/Deployment
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
- 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.