This page describes how to use the Security Command Center API notifications feature, including the following examples:
- Create a
NotificationConfig
- Get a
NotificationConfig
- Update a
NotificationConfig
- Delete a
NotificationConfig
- List
NotificationConfig
- Receive Pub/Sub notifications
Before you begin
To use the examples on this page, you need to complete the guide to Set up finding notifications.
To execute the following examples, you need an Identity and Access Management (IAM) role with appropriate permissions:
- Get and List
NotificationConfig
: Security Center Notification Viewer or Editor - Update and Delete
NotificationConfig
: Security Center Notification Editor
Learn more about Security Command Center roles.
Creating a NotificationConfig
To create a NotificationConfig
, you must have:
- An existing Pub/Sub topic that you want to send notifications to.
- Required IAM roles for your service account or the account
you're using to run
gcloud
tool commands.
For more information, see the step to Set up a Pub/Sub topic in the guide to Set up finding notifications.
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 so
that you can 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
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:Set the email of the account used to run
gcloud
tool commands:export EMAIL=your-username@email.com
Or set the email of the service account:
export EMAIL=service-account-name@$CONSUMER_PROJECT.iam.gserviceaccount.com
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, Security Command Center uses an
organization-level service account in the form of
service-org-organization-id@gcp-sa-scc-notification.iam.gserviceaccount.com
with the role securitycenter.notificationServiceAgent
. This organization-level
service account role is required for notifications to function.
Getting a NotificationConfig
To get a NotificationConfig
, you must have an IAM role
that includes the securitycenter.notification.get
permission.
gcloud
# The numeric ID of the organization and the name of the notification that you want to get
NOTIFICATION="organizations/organization-id/notificationConfigs/notification-name"
gcloud scc notifications describe $NOTIFICATION
Python
Java
Go
Node.js
PHP
Ruby
C#
Updating a NotificationConfig
To update a NotificationConfig
, you must have an IAM role
that includes the securitycenter.notification.update
permission.
When you update using a field mask, only the fields you specify are updated. If
you don't use a field mask, all mutable fields in the NotificationConfig
are
replaced by the new values. You can use a field mask to update the
Pub/Sub topic and description.
To complete this example, you must be subscribed to the new topic, and your
notifications service account must have the pubsub.topics.setIamPolicy
permission on the topic. To grant an appropriate role:
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
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
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'
After you grant the service account role, update the NotificationConfig
description, Pub/Sub topic and filter using the language of your
choice:
gcloud
# The topic to which the notifications are published
PUBSUB_TOPIC="projects/project-id/topics/topic-id"
# The description for the NotificationConfig
DESCRIPTION="description"
# The numeric ID of the organization and the name of the notification that you want to update
NOTIFICATION="organizations/organization-id/notificationConfigs/notification-name"
gcloud scc notifications update $NOTIFICATION
--description "$DESCRIPTION" \
--pubsub-topic $PUBSUB_TOPIC \
--filter $FILTER
Python
Java
Go
Node.js
PHP
Ruby
C#
Deleting a NotificationConfig
To delete a NotificationConfig
, you must have an IAM role
that includes the securitycenter.notification.delete
permission.
When you delete a NotificationConfig
, the
securitycenter.notificationServiceAgent
role stays on the
Pub/Sub topic. If you aren't using the Pub/Sub topic
in any other NotificationConfig
, remove the role from the topic. For more
information, see access control.
Delete a NotificationConfig
using the language of your choice:
gcloud
# The numeric ID of the organization and the name of the notification that you want to delete
NOTIFICATION="organizations/organization-id/notificationConfigs/notification-name"
gcloud scc notifications delete $NOTIFICATION
Python
Java
Go
Node.js
PHP
Ruby
C#
Listing NotificationConfigs
To list NotificationConfigs
, you must have an IAM role
that includes the securitycenter.notification.list
permission.
All Security Command Center API lists are paginated. Each response returns a page of
results and a token to return the next page. The default pageSize
is 10. You
can configure page size to a minimum of 1, and a maximum of 1000.
List NotificationConfigs
using the language of your choice:
gcloud
# The numeric ID of the organization
ORGANIZATION=organization-id
gcloud scc notifications list $ORGANIZATION
Python
Java
Go
Node.js
PHP
Ruby
C#
Receiving Pub/Sub notifications
This section provides a sample notification message and examples that show how
to convert a Pub/Sub message into a NotificationMessage
that
contains a finding.
Notifications are published to Pub/Sub in the JSON
format.
Following is an example of a notification message:
{
"notificationConfigName": "organizations/organization-id/notificationConfigs/config-id",
"finding": {
"name": "organizations/organization-id/sources/source-id/findings/finding-id",
"parent": "organizations/organization-id/sources/source-id",
"state": "ACTIVE",
"category": "TEST-CATEGORY",
"securityMarks": {
"name": "organizations/organization-id/sources/source-id/findings/finding-id/securityMarks"
},
"eventTime": "2019-07-26T07:32:37Z",
"createTime": "2019-07-29T18:45:27.243Z"
}
}
Convert a Pub/Sub message into a NotificationMessage
using
the language of your choice:
gcloud
The gcloud
tool doesn't support converting a Pub/Sub
message into a NotificationMessage
. You can use the gcloud
tool to
get a NotificationMessage
and print the JSON
directly in your terminal:
# The subscription used to receive published messages from a topic
PUBSUB_SUBSCRIPTION="projects/project-id/subscriptions/subscription-id"
gcloud pubsub subscriptions pull $PUBSUB_SUBSCRIPTION
Python
Java
Go
Node.js
What's next
- Learn about Filtering notifications.