This page explains how to enable Security Command Center API notifications.
Notifications send findings and finding updates to a Pub/Sub topic within minutes. Security Command Center API notifications include all of the finding information that is displayed by Security Command Center in the Google Cloud console.
You can connect Security Command Center notifications in Pub/Sub directly to Cloud Run functions actions. For example functions that can help with response, enrichment, and remediation, see the Security Command Center open-source repository of Cloud Run functions code. The repository contains solutions to help you take automated actions on security findings.
Alternatively, you can export findings to BigQuery, or you can set up Continuous Exports for Pub/Sub in the Google Cloud console.
Before you begin
To set up and configure notifications, you must have the following Identity and Access Management (IAM) roles:
- Security Center Admin (
roles/securitycenter.Admin
): to enable Security Command Center API notifications - Security Center Admin Viewer (
roles/securitycenter.adminViewer
): to access Security Command Center in the Google Cloud console - To grant roles to the notifications service account or
gcloud CLI account at either the organization level,
folder level, or project level, one of the following roles:
- Organization Administrator (
roles/resourcemanager.organizationAdmin
) - Folder IAM Admin (
roles/resourcemanager.folderIamAdmin
) - Project IAM Admin (
roles/resourcemanager.projectIamAdmin
)
- Organization Administrator (
The IAM roles for Security Command Center can be granted at the organization, folder, or project level. Your ability to view, edit, create, or update findings, assets, and security sources depends on the level for which you are granted access. To learn more about Security Command Center roles, see Access control.
Setting up Security Command Center API notifications
To set up notifications, first enable the Security Command Center API.
Enabling the Security Command Center API
To enable the Security Command Center API:
Go to the API Library page in the Google Cloud console.
Select the project for you which you want to enable the notifications API.
In the Search box, enter
Security Command Center
, and then click Security Command Center in the search results.On the API page that appears, click Enable.
The Security Command Center API is enabled for your project. Next, you use the gcloud CLI or the client libraries to subscribe to a Pub/Sub topic and set up permissions.
Data residency and notifications
If data residency
is enabled for Security Command Center, the configurations that define
continuous exports to
Pub/Sub—notificationConfig
resources—are subject
to data residency control and are stored in your
Security Command Center location.
To export findings in a Security Command Center location to Pub/Sub, you must configure the continuous export in the same Security Command Center location as the findings.
Because the filters that are used in continuous exports can contain data that is subject to residency controls, make sure you specify the correct location before you create them. Security Command Center does not restrict which location you create exports in.
Continuous exports are stored only in the location in which they are created and cannot be viewed or edited in other locations.
After you create a continuous export, you can't change its location. To change the location, you need to delete the continuous export and recreate it in the new location.
To retrieve a continuous export by using API calls,
you need to specify the location in the full resource name of the
notificationConfig
. For example:
GET https://securitycenter.googleapis.com/v2/{name=organizations/123/locations/eu/notificationConfigs/my-pubsub-export-01}
Similarly, to retrieve a continuous export by using
the gcloud CLI, you need to specify the location either
in the full resource name of the configuration or by using the --locations
flag. For example:
gcloud scc notifications describe myContinuousExport organizations/123 \ --location=locations/us
Setting up a Pub/Sub topic
In this step, you create and subscribe to the Pub/Sub topic that you want to send notifications to. If you don't need to programmatically call the API, the gcloud CLI commands are recommended.
gcloud
To set up the Security Command Center API notifications feature using gcloud CLI, you perform the following steps:
- Set up a Pub/Sub topic and subscription.
- Set up the gcloud CLI account permissions.
Step 1: Set up Pub/Sub
To set up and subscribe to a Pub/Sub topic, do the following:
Go to the Google Cloud console.
Select the project for which you enabled the Security Command Center API.
Click Activate Cloud Shell.
To create a new Pub/Sub topic, or use an existing topic, run the following command:
gcloud pubsub topics create TOPIC_ID
Replace
TOPIC_ID
with your topic name.Set topic ID environment variable:
export TOPIC_ID=TOPIC_ID
Create a subscription to the topic:
gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic TOPIC_ID
Replace
SUBSCRIPTION_ID
with your subscription name.
To learn more about setting up Pub/Sub, see Managing topics and subscriptions.
Next, you set up permissions for your account.
Step 2: Set up gcloud CLI account permissions
To create a NotificationConfig
, you need to grant the following roles
to your gcloud CLI account:
- Security Center Admin (
roles/securitycenter.admin
) or the Security Center Notification configurations Editor (roles/securitycenter.notificationConfigEditor
). This role needs to be granted at the same level—organization, folder, or project—at which you are creating theNotificationConfig
. - Pub/Sub Admin (
roles/pubsub.admin
) on the Pub/Sub topic that is receiving notifications
the at the organization, folder, or project level
To grant these permissions, do the following:
Go to the Google Cloud console.
Select the project for which you enabled the Security Command Center API.
Click Activate Cloud Shell.
Set your organization name:
export ORGANIZATION_ID=ORGANIZATION_ID
Replace
ORGANIZATION_ID
with your organization ID.Set the project ID for the project that the Pub/Sub topic belongs to:
export PUBSUB_PROJECT=PROJECT_ID
Replace
PROJECT_ID
with your project ID.Set the gcloud CLI account that you are using:
export GCLOUD_ACCOUNT=EMAIL
Replace
EMAIL
with the email address of the account running gcloud CLI commands.Set the topic ID or use the topic you previously set up.
export TOPIC_ID=TOPIC_ID
Replace
TOPIC_ID
with your topic name.Grant the gcloud CLI account a Pub/Sub role that has the
pubsub.topics.setIamPolicy
permission:gcloud pubsub topics add-iam-policy-binding \ projects/$PUBSUB_PROJECT/topics/$TOPIC_ID \ --member="user:$GCLOUD_ACCOUNT" \ --role='roles/pubsub.admin'
Grant the gcloud CLI account a role that includes all of the
securitycenter.notification
permissions, likeroles/securitycenter.notificationConfigEditor
orroles/securitycenter.admin
. You can grant the role at the project, folder, or organization level.To grant the role at a project level:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member="user:$GCLOUD_ACCOUNT" \ --role='ROLE_NAME'
Replace the following:
PROJECT_ID
: the ID of the project in which Security Command Center is enabledROLE_NAME
: the role to be assigned
To grant the role at the organization level:
gcloud organizations add-iam-policy-binding $ORGANIZATION_ID \ --member="user:$GCLOUD_ACCOUNT" \ --role='ROLE_NAME'
Replace
ROLE_NAME
with the role to be assigned.
Next, you create a NotificationConfig.
Client libraries
To set up the Security Command Center API notifications feature using the client libraries, you perform the following steps:
- Set up a service account.
- Download API client libraries.
- Set up a development environment.
- Set up a Pub/Sub topic and subscription.
Step 1: Setting up a service account
The Security Command Center API notifications feature uses a service account with appropriate permissions to configure notifications. This service account is only used for the initial setup of a config, and you can re-use it to create more notification configs later. This service account is separate from the service account that was created for you when you set up Security Command Center.
To create a service account, do the following:
Go to the Google Cloud console.
Select the project for which you enabled the Security Command Center API.
Click Activate Cloud Shell.
Set environment variables:
Set your organization name:
export ORGANIZATION_ID=ORGANIZATION_ID
Replace
ORGANIZATION_ID
with your organization ID.Set the project ID for the project in which you want to enable the notifications API:
export PROJECT_ID=PROJECT_ID
Replace
PROJECT_ID
with your project ID.Set the custom ID you want to use for the new service account, like
scc-notifications
. The service account name must be between 6 and 30 characters, begin with a letter, and be all lowercase alphanumeric characters and hyphens:export SERVICE_ACCOUNT=CUSTOM_ID
Replace
CUSTOM_ID
with the custom name for the service account.Set the path in which the service account key should be stored, like
export KEY_LOCATION=/home/$USER/mykeys/$SERVICE_ACCOUNT.json
:export KEY_LOCATION=FULL_KEY_LOCATION_PATH # This is used by client libraries to find the key export GOOGLE_APPLICATION_CREDENTIALS=$KEY_LOCATION
Replace
FULL_KEY_LOCATION_PATH
with the full path to your service account key.
Create a service account that's associated with your project ID:
gcloud iam service-accounts create $SERVICE_ACCOUNT --display-name \ "Service Account for [USER]" --project $PROJECT_ID
Create a key to associate with the service account. The key is used when you create a
NotificationConfig
, and is persistently stored at theKEY_LOCATION
that you specified in previous steps.gcloud iam service-accounts keys create $KEY_LOCATION --iam-account \ $SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com
Grant the service account a role that includes all of the
securitycenter.notification
permissions, likeroles/securitycenter.notificationConfigEditor
orroles/securitycenter.admin
. You can grant the role at the project, folder, or organization level.To grant the role at the project level:
gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com" \ --role='ROLE_NAME'
Replace
ROLE_NAME
with the role to be assigned.To grant the role at the organization level:
gcloud organizations add-iam-policy-binding $ORGANIZATION_ID \ --member="serviceAccount:$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com" \ --role='ROLE_NAME'
Replace
ROLE_NAME
with the role to be assigned.
The service account is now set up to use with notifications and the service
account key is stored at the KEY_LOCATION
you
specified. To learn more about service accounts, see
creating and managing service account keys.
Step 2: Setting up a development environment
To use the Security Command Center API notifications feature, you can use gcloud CLI or download the client libraries and set up a development environment for the language of your choice.
Python
Optional: Before you install the Python library, we recommend using Virtualenv to create an isolated Python environment.
virtualenv YOUR_ENV source YOUR_ENV/bin/activate
Replace
YOUR_ENV
with the name of your virtual environment.Install pip to manage the Python library installation.
Run the following commands to install the Python library:
pip install google-cloud-securitycenter
Java
To include the Security Command Center Java library as a dependency in your
project, select an artifact from the Maven repository.
Notifications are included in library version 0.119.0
and higher.
If you're using Intellij, set the GOOGLE_APPLICATION_CREDENTIALS
environment variable to the absolute path of the notifications service
account key that you downloaded in the previous steps:
- In Intellij, click Run > Edit Configurations.
Set the following variable under Application > Run_Configuration_For_Sample > Environment Variables:
GOOGLE_APPLICATION_CREDENTIALS=ABSOLUTE_PATH_TO_SERVICE_ACCOUNT_KEY
Replace
ABSOLUTE_PATH_TO_SERVICE_ACCOUNT_KEY
with the full path to your service account key.
Go
To install notifications API Go dependencies, download the Go library:
go get cloud.google.com/go/securitycenter/apiv1
Node.js
In the project folder, use npm
to install any needed notifications API
dependencies:
npm install --save @google-cloud/security-center/
Step 3: Setting up Pub/Sub
To deliver notifications to Pub/Sub, you subscribe to a
Pub/Sub topic and grant the notifications service account an
IAM role that includes the pubsub.topics.setIamPolicy
permission:
Create a new Pub/Sub topic or use an existing topic:
gcloud pubsub topics create TOPIC_ID
Replace
TOPIC_ID
with your topic ID.Set environment variables:
Set the topic ID:
export TOPIC_ID=TOPIC_ID
Set the project ID for the project in which you enabled the notifications API:
export CONSUMER_PROJECT=PROJECT_ID
Replace
PROJECT_ID
with your project ID.Set the email of the service account that you created in previous steps:
export SERVICE_ACCOUNT_EMAIL=SERVICE_ACCOUNT_NAME@$CONSUMER_PROJECT.iam.gserviceaccount.com
Replace
SERVICE_ACCOUNT_NAME
with the name of the service account.
Create a subscription to the topic:
gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic TOPIC_ID
Replace
SUBSCRIPTION_ID
with the subscription ID.Grant the notifications service account a role with the
pubsub.topics.setIamPolicy
permission:gcloud pubsub topics add-iam-policy-binding \ projects/$CONSUMER_PROJECT/topics/$TOPIC_ID \ --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \ --role='roles/pubsub.admin'
To learn more about setting up Pub/Sub, see
Managing topics and subscriptions. In the
next step, you complete setup by creating a
NotificationConfig
.
Creating a NotificationConfig
Before you create a NotificationConfig
, note that each organization
can have a limited number of NotificationConfig
files. For more
information, see Quotas and limits.
The NotificationConfig
includes a filter
field that limits notifications to
useful events. This field accepts all of the filters that are available in the
Security Command Center API findings.list
method.
When you create a NotificationConfig
, you specify a parent for the
NotificationConfig
from the Google Cloud resource hierarchy,
either an organization, a folder, or a project. If you need to retrieve,
update, or delete the NotificationConfig
later, you need to include
the numerical ID of the parent organization, folder, or project when you
reference it.
To create the NotificationConfig
using the language or platform
of your choice:
gcloud
gcloud scc notifications create NOTIFICATION_NAME \ --PARENT=PARENT_ID \ --location=LOCATION --description="NOTIFICATION_DESCRIPTION" \ --pubsub-topic=PUBSUB_TOPIC \ --filter="FILTER"
Replace the following:
NOTIFICATION_NAME
: the name of the notification. Must be between 1 and 128 characters and contain alphanumeric characters, underscores, or hyphens only.PARENT
: the scope in the resource hierarchy to which the notification applies,organization
,folder
, orproject
.PARENT_ID
: the ID of the parent organization, folder, or project, specified in the format oforganizations/123
,folders/456
, orprojects/789
.LOCATION
: If data residency is enabled, specify the Security Command Center location in which to create the notification. The resultingnotificationConfig
resource is stored only in this location. Only findings that are issued in this location are sent to Pub/Sub.If data residency is not enabled, specifying the
--location
flag creates the notification by using Security Command Center API v2, and the only valid value for the flag isglobal
.NOTIFICATION_DESCRIPTION
: a description of the notification of no more than 1,024 characters.PUBSUB_TOPIC
: The Pub/Sub topic that will receive notifications. Its format isprojects/PROJECT_ID/topics/TOPIC
.FILTER
: the expression you define to select which findings get sent to Pub/Sub. For example,state="ACTIVE"
.
Python
The following sample uses the v1 API. To modify
the sample for v2, replace v1
with v2
and add
/locations/LOCATION
to the resource name.
For most resources, add /locations/LOCATION
to the
resource name after /PARENT/PARENT_ID
, where
PARENT
is organizations
, folders
,
or projects
.
For findings, add /locations/LOCATION
to the resource
name after /sources/SOURCE_ID
, where SOURCE_ID
is the ID of the
Security Command Center service
that issued the finding.
Java
The following sample uses the v1 API. To modify
the sample for v2, replace v1
with v2
and add
/locations/LOCATION
to the resource name.
For most resources, add /locations/LOCATION
to the
resource name after /PARENT/PARENT_ID
, where
PARENT
is organizations
, folders
,
or projects
.
For findings, add /locations/LOCATION
to the resource
name after /sources/SOURCE_ID
, where SOURCE_ID
is the ID of the
Security Command Center service
that issued the finding.
Go
The following sample uses the v1 API. To modify
the sample for v2, replace v1
with v2
and add
/locations/LOCATION
to the resource name.
For most resources, add /locations/LOCATION
to the
resource name after /PARENT/PARENT_ID
, where
PARENT
is organizations
, folders
,
or projects
.
For findings, add /locations/LOCATION
to the resource
name after /sources/SOURCE_ID
, where SOURCE_ID
is the ID of the
Security Command Center service
that issued the finding.
Node.js
The following sample uses the v1 API. To modify
the sample for v2, replace v1
with v2
and add
/locations/LOCATION
to the resource name.
For most resources, add /locations/LOCATION
to the
resource name after /PARENT/PARENT_ID
, where
PARENT
is organizations
, folders
,
or projects
.
For findings, add /locations/LOCATION
to the resource
name after /sources/SOURCE_ID
, where SOURCE_ID
is the ID of the
Security Command Center service
that issued the finding.
PHP
The following sample uses the v1 API. To modify
the sample for v2, replace v1
with v2
and add
/locations/LOCATION
to the resource name.
For most resources, add /locations/LOCATION
to the
resource name after /PARENT/PARENT_ID
, where
PARENT
is organizations
, folders
,
or projects
.
For findings, add /locations/LOCATION
to the resource
name after /sources/SOURCE_ID
, where SOURCE_ID
is the ID of the
Security Command Center service
that issued the finding.
Ruby
The following sample uses the v1 API. To modify
the sample for v2, replace v1
with v2
and add
/locations/LOCATION
to the resource name.
For most resources, add /locations/LOCATION
to the
resource name after /PARENT/PARENT_ID
, where
PARENT
is organizations
, folders
,
or projects
.
For findings, add /locations/LOCATION
to the resource
name after /sources/SOURCE_ID
, where SOURCE_ID
is the ID of the
Security Command Center service
that issued the finding.
C#
The following sample uses the v1 API. To modify
the sample for v2, replace v1
with v2
and add
/locations/LOCATION
to the resource name.
For most resources, add /locations/LOCATION
to the
resource name after /PARENT/PARENT_ID
, where
PARENT
is organizations
, folders
,
or projects
.
For findings, add /locations/LOCATION
to the resource
name after /sources/SOURCE_ID
, where SOURCE_ID
is the ID of the
Security Command Center service
that issued the finding.
Notifications are now published to the Pub/Sub topic you specified.
To publish notifications, a service account is created for you in the form of
service-org-ORGANIZATION_ID@gcp-sa-scc-notification.iam.gserviceaccount.com
.
This service account is created when you create your first NotificationConfig
and is automatically granted the securitycenter.notificationServiceAgent
role
on the IAM policy for PUBSUB_TOPIC when creating the notification config.
This service account role is required for notifications to function.
Granting perimeter access in VPC Service Controls
If you use VPC Service Controls and your Pub/Sub topic is part of a project inside a service perimeter, you must grant access to projects in order to create notifications.
To grant access to projects, create ingress and egress rules for the principals
and projects that are used to create notifications. The rules allow
access to protected resources and let Pub/Sub verify that users
have the setIamPolicy
permission on the Pub/Sub topic.
Before creating a NotificationConfig
Before completing the steps in Creating a NotificationConfig, do the following:
Go to the VPC Service Controls page in the Google Cloud console.
If necessary, select your organization.
Click the name of the service perimeter you want to change.
To find the service perimeter you need to modify, you can check your logs for entries that show
RESOURCES_NOT_IN_SAME_SERVICE_PERIMETER
violations. In those entries, check theservicePerimeterName
field:accessPolicies/ACCESS_POLICY_ID/servicePerimeters/SERVICE_PERIMETER_NAME
.Click Edit Perimeter.
In the navigation menu, click Ingress Policy.
To configure ingress rules for users or service accounts, use the following parameters:
- FROM attributes of the API client:
- In the Source drop-down menu, select All Sources.
- In the Identities drop-down menu, choose Selected identities.
- Click Select, and then enter the principal that is used to call the Security Command Center API.
- TO attributes of Google Cloud services/resources:
- In the Project drop-down menu, choose Selected projects.
- Click Select, and then enter the project that contains the Pub/Sub topic.
- In the Services drop-down menu, choose Selected services, and then select Cloud Pub/Sub API.
- In the Methods drop-down menu, choose All actions.
- FROM attributes of the API client:
Click Save.
In the navigation menu, click Egress Policy.
Click Add Rule.
To configure egress rules for user or service accounts, enter the following parameters:
- FROM attributes of the API client:
- In the Identities drop-down menu, choose Selected identities.
- Click Select, and then enter the principal that is used to call the Security Command Center API.
- TO attributes of Google Cloud services/resources:
- In the Project drop-down menu, choose All projects.
- In the Services drop-down menu, choose Selected services, and then select Cloud Pub/Sub API.
- In the Methods drop-down menu, choose All actions.
- FROM attributes of the API client:
Click Save.
Create an ingress rule for the NotificationConfig
To create an ingress rule for a NotificationConfig
, do the following:
- Complete the instructions in Creating a NotificationConfig.
- Re-open the service perimeter from the previous section.
- Click Ingress Policy.
- Click Add Rule.
- To configure the ingress rule for the
NotificationConfig
service account you created, enter the following parameters:- FROM attributes of the API client:
- In the Source drop-down menu, select All Sources.
- In the Identities drop-down menu, choose Selected identities.
- Click Select, and then enter the name of the
NotificationConfig
service account:service-org-ORGANIZATION_ID@gcp-sa-scc-notification.iam.gserviceaccount.com
- TO attributes of GCP services/resources:
- In the Project drop-down menu, choose Selected projects.
- Click Select, and then select the project that contains the Pub/Sub topic.
- In the Services drop-down menu, choose Selected services, and then select Cloud Pub/Sub API.
- In the Methods drop-down menu, choose All actions.
- FROM attributes of the API client:
- In the navigation menu, click Save.
The selected projects, users, and services accounts can now access the protected resources and create notifications.
If you followed all of the steps in this guide, and notifications are working properly, you can now delete the following:
- The ingress rule for the principal
- The egress rule for the principal
Those rules were only needed to configure the NotificationConfig
. However, for
notifications to continue working, you must keep the ingress rule for the
NotificationConfig
, which lets it publish notifications to your
Pub/Sub topic behind the service perimeter.
What's next
- Learn about enabling real-time email and chat notifications.
- Learn how to manage the notifications API.
- Learn about filtering notifications.