Enable the Security Command Center API notifications feature. Notifications send information to a Pub/Sub topic to provide findings updates and new findings within minutes. Because Security Command Center works at the organization level, Security Command Center API notifications include all of the finding information that is displayed in the Security Command Center dashboard.
You can connect Security Command Center Pub/Sub notifications directly to Cloud Functions actions. For example security functions that can help with response, enrichment, and remediation, see the Security Command Center tools Alerts example app.
Alternatively, Security Command Center Premium customers can set up Continuous Exports for Pub/Sub in the Security Command Center dashboard.
Before you begin
- To enable Security Command Center API notifications, you must have the Security Center Admin IAM role.
- To access the Security Command Center dashboard, you must have the Security Center Admin Viewer IAM role.
- To grant appropriate roles to the notifications service account or
gcloud
tool account, you must have the Organization Administrator IAM role.
Learn more about Security Command Center roles.
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 Cloud Console.
Go to the API Library page - 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 now enabled for your project. Next, you use the
gcloud
tool or the client libraries to subscribe to a
Pub/Sub topic and set up permissions.
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
tool commands are recommended because it's
easier to set up.
gcloud
To set up the Security Command Center API notifications feature using
gcloud
tool, you:
- Set up a Pub/Sub topic and subscription.
- Set up the
gcloud
tool account permissions.
Step 1: Set up Pub/Sub
To set up and subscribe to a Pub/Sub topic:
- Go to the Google Cloud Console.
Go to the Google Cloud Console - Select the project for which you enabled the Security Command Center API.
- Click Activate Cloud Shell.
Create a new topic or re-use an existing topic. Run the following command to create a new topic:
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
tool account permissions
To create a NotificationConfig
, you need the following
Identity and Access Management (IAM) roles on your gcloud
tool account:
roles/securitycenter.admin
orroles/securitycenter.notificationConfigEditor
roles/pubsub.admin
on the Pub/Sub topic that is receiving notifications
To grant these permissions:
- Go to the Google Cloud Console.
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 under:
export PUBSUB_PROJECT=PROJECT_ID
Replace PROJECT_ID with your project ID.
Set the
gcloud
tool account that you are using:export GCLOUD_ACCOUNT=EMAIL
Replace EMAIL with your email address of the account running
gcloud
tool commands.Set the topic ID or use the topic set from Step 1.
export TOPIC_ID=TOPIC_ID
Replace TOPIC_ID with your topic name.
Grant the
gcloud
tool account a Pub/Sub role that has thepubsub.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
tool account a role for the organization that includes all of thesecuritycenter.notification
permissions, likeroles/securitycenter.notificationConfigEditor
orroles/securitycenter.admin
.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:
- 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:
- Go to the Google Cloud Console.
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, must begin with a letter, and must 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 the 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 for the organization that includes all of the
securitycenter.notification
permissions, likeroles/securitycenter.notificationConfigEditor
orroles/securitycenter.admin
.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
tool or download the client libraries and set up your
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, run:
To download the Go library, run:
go get -u 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 topic or re-use an existing topic. To create a new 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 the 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 the following:
- Each organization can have a limited number of
NotificationConfig
files. For more information, see Quotas and limits. - You must have the Organization Administrator IAM role to
grant appropriate roles to the notifications service account or
gcloud
tool account.
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.
To grant the account the Security Center Notifications Configurations Editor
IAM role using the gcloud
command-line tool:
Set environment variables:
Set your organization name:
export ORGANIZATION_ID=ORGANIZATION_ID
Replace ORGANIZATION_ID with your organization ID.
Set the email of the service account that you created when you set up finding notifications or the account you're using to run
gcloud
tool commands:export EMAIL=EMAIL_ADDRESS
Or set the email of the service account:
export EMAIL=SERVICE_ACCOUNT@$CONSUMER_PROJECT.iam.gserviceaccount.com
Depending on your choice, replace the following:
- EMAIL_ADDRESS with the email address of the account used to run
gcloud
tool commands. - SERVICE_ACCOUNT with the service account name.
Grant the necessary role to the service account or the account you used with
gcloud
tool commands:Grant the role to the account used to run
gcloud
tool commands:gcloud organizations add-iam-policy-binding \ $ORGANIZATION_ID \ --member="user:$EMAIL" \ --role='roles/securitycenter.notificationConfigEditor'
Or grant the role to the service account:
gcloud organizations add-iam-policy-binding \ $ORGANIZATION_ID \ --member="serviceAccount:$EMAIL" \ --role='roles/securitycenter.notificationConfigEditor'
After you grant the service account or gcloud
tool account
permissions, create the NotificationConfig
using the language or platform
of your choice:
gcloud
# The numeric ID of the organization
ORGANIZATION_ID=ORGANIZATION_ID
# The topic to which the notifications are published
PUBSUB_TOPIC="projects/PROJECT_ID/topics/TOPIC_ID"
# The description for the NotificationConfig
DESCRIPTION="Notifies for active findings"
# Filters for active findings
FILTER="state=\"ACTIVE\""
gcloud scc notifications create NOTIFICATION_NAME \
--organization "$ORGANIZATION_ID" \
--description "$DESCRIPTION" \
--pubsub-topic $PUBSUB_TOPIC \
--filter "$FILTER"
Python
Java
Go
Node.js
PHP
Ruby
C#
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
at the organization level. This service account role is required for
notifications to function.
In the preceding steps, you created either a project-level notifications service
account in the form of
SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com
or used a user account with the gcloud
tool.
You can optionally revoke the permissions you granted to this account. To learn more, see
Granting, changing, and revoking access in the IAM
documentation.
What's next
- Learn about Enabling real-time email and chat notifications
- Learn how to Manage the notifications API.
- Learn about Filtering notifications.