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 get the permissions that you need to set up and configure Security Command Center API notifications, ask your administrator to grant you the following IAM roles:
-
Security Center Admin (
roles/securitycenter.admin
) on the organization or project where Security Command Center is activated -
Project IAM Admin (
roles/resourcemanager.projectIamAdmin
) on the project where you will create your Pub/Sub topic
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
-
Security Center Admin (
-
Enable the Security Command Center API:
gcloud services enable securitycenter.googleapis.com
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/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 by using the
--location
flag. For example:
gcloud scc notifications describe myContinuousExport --organization=123 \ --location=us
Set up a Pub/Sub topic
In this task, you create and subscribe to the Pub/Sub topic that you want to send notifications to.
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 where you enabled the Security Command Center API.
Click Activate Cloud Shell.
Optional: To create a new Pub/Sub topic, run the following command:
gcloud pubsub topics create TOPIC_ID
Replace
TOPIC_ID
with a topic name.Create a subscription to the topic:
gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID
Replace the following:
SUBSCRIPTION_ID
: the subscription IDTOPIC_ID
: the topic ID
To learn more about setting up Pub/Sub, see Managing topics and subscriptions.
Step 2: Grant role on Pub/Sub topic
To create a NotificationConfig
, you need the Pub/Sub Admin role
(roles/pubsub.admin
) on the Pub/Sub topic for which you created
a subscription.
To grant this role, 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.
Grant the required role to your Google Account on the Pub/Sub topic:
gcloud pubsub topics add-iam-policy-binding \ projects/PUBSUB_PROJECT/topics/TOPIC_ID \ --member="user:GOOGLE_ACCOUNT" \ --role="roles/pubsub.admin"
Replace the following:
PUBSUB_PROJECT
: the Google Cloud project that contains your Pub/Sub topicTOPIC_ID
: the topic IDGOOGLE_ACCOUNT
: the email address for your Google Account
Create 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.
In the Google Cloud console, some NotificationConfig
resources might have a Legacy
label, which indicates that they were created with the v1 Security Command Center API. You can manage these
NotificationConfig
resources with the Google Cloud console; the gcloud CLI; the v1
Security Command Center API; or the v1 client libraries for Security Command Center.
To manage these NotificationConfig
resources with the gcloud CLI, you must not specify
a location when you run the gcloud CLI command.
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, the Security Command Center location in which to ; if data residency is not enabled, use the valueglobal
.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\"
.
Terraform
Create a NotificationConfig
for an organization:
Create a NotificationConfig
for a folder:
Create a NotificationConfig
for a project:
Go
Java
Node.js
Python
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.
Grant 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, complete the following steps.
Console
-
In the Google Cloud console go to the VPC Service Controls page.
- Select your organization or project.
- If you selected an organization, click Select an access policy and then select the access policy associated with the perimeter that you want to update.
-
Click the name of the perimeter that you want to update.
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.
- Click Egress policy.
- Click Add an egress rule.
-
In the FROM section, set the following details:
- For Identity, select Select identities & groups.
- Click Add identities
-
Enter the email address of the principal used to call the Security Command Center API.
- Select the principal or press ENTER, and then click Add identities.
-
In the TO section, set the following details:
- For Project, select All projects.
- For Operations or IAM roles, select Select operations.
-
Click Add operations, and then add the following operations:
- Add the pubsub.googleapis.com service.
- Click All methods.
- Click Add all methods.
- Add the pubsub.googleapis.com service.
- Click Ingress policy.
- Click Add an ingress rule.
-
In the FROM section, set the following details:
- For Identity, select Select identities & groups.
- Click Add identities
-
Enter the email address of the principal used to call the Security Command Center API.
- Select the principal or press ENTER, and then click Add identities.
- For Sources, select All sources
-
In the TO section, set the following details:
- For Project, select Select projects.
- Click Add projects, and then add the project that contains the Pub/Sub topic.
- For Operations or IAM roles, select Select operations.
-
Click Add operations, and then add the following operations:
- Add the pubsub.googleapis.com service.
- Click All methods.
- Click Add all methods.
- Add the pubsub.googleapis.com service.
- Click Save.
gcloud
-
If a quota project isn't already set, then set it. Choose a project that has the Access Context Manager API enabled.
gcloud config set billing/quota_project QUOTA_PROJECT_ID
Replace
QUOTA_PROJECT_ID
with the ID of the project that you want to use for billing and quota. -
Create a file named
egress-rule.yaml
with the following contents:- egressFrom: identities: - PRINCIPAL_ADDRESS egressTo: operations: - serviceName: pubsub.googleapis.com methodSelectors: - method: '*' resources: - '*'
Replace
PRINCIPAL_ADDRESS
with the address of the principal used to call the Security Command Center API. -
Create a file named
ingress-rule.yaml
with the following contents:- ingressFrom: identities: - PRINCIPAL_ADDRESS sources: - accessLevel: '*' ingressTo: operations: - serviceName: pubsub.googleapis.com methodSelectors: - method: '*' resources: - '*'
Replace
PRINCIPAL_ADDRESS
with the address of the principal used to call the Security Command Center API. -
Add the egress rule to the perimeter:
gcloud access-context-manager perimeters update PERIMETER_NAME \ --set-egress-policies=egress-rule.yaml
Replace the following:
-
PERIMETER_NAME
: the name of the perimeter. For example,accessPolicies/1234567890/servicePerimeters/example_perimeter
.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
-
-
Add the ingress rule to the perimeter:
gcloud access-context-manager perimeters update PERIMETER_NAME \ --set-ingress-policies=ingress-rule.yaml
Replace the following:
-
PERIMETER_NAME
: the name of the perimeter. For example,accessPolicies/1234567890/servicePerimeters/example_perimeter
.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
-
See Ingress and egress rules for more information.
Create an ingress rule for the NotificationConfig
To create an ingress rule for a NotificationConfig
, complete the instructions
in Creating a NotificationConfig, and then
complete the following steps.
Console
-
Re-open the service perimeter from the previous section.
- Click Ingress policy.
- Click Add an ingress rule.
-
In the FROM section, set the following details:
- For Identity, select Select identities & groups.
- Click Add identities
-
Enter the email address of the
NotificationConfig
service agent. The service agent's address has the following format:service-org-ORGANIZATION_ID@gcp-sa-scc-notification.iam.gserviceaccount.com
Replace
ORGANIZATION_ID
with your organization ID. - Select the service agent or press ENTER, and then click Add identities.
- For Sources, select All sources
-
In the TO section, set the following details:
- For Project, select Select projects.
- Click Add projects, and then add the project that contains the Pub/Sub topic.
- For Operations or IAM roles, select Select operations.
-
Click Add operations, and then add the following operations:
- Add the pubsub.googleapis.com service.
- Click All methods.
- Click Add all methods.
- Add the pubsub.googleapis.com service.
- Click Save.
gcloud
-
If a quota project isn't already set, then set it. Choose a project that has the Access Context Manager API enabled.
gcloud config set billing/quota_project QUOTA_PROJECT_ID
Replace
QUOTA_PROJECT_ID
with the ID of the project that you want to use for billing and quota. -
Create a file named
ingress-rule.yaml
with the following contents:- ingressFrom: identities: - serviceAccount:service-org-ORGANIZATION_ID@gcp-sa-scc-notification.iam.gserviceaccount.com sources: - accessLevel: '*' ingressTo: operations: - serviceName: pubsub.googleapis.com methodSelectors: - method: '*' resources: - '*'
Replace
ORGANIZATION_ID
with your organization ID. -
Add the ingress rule to the perimeter:
gcloud access-context-manager perimeters update PERIMETER_NAME \ --set-ingress-policies=ingress-rule.yaml
Replace the following:
-
PERIMETER_NAME
: the name of the perimeter. For example,accessPolicies/1234567890/servicePerimeters/example_perimeter
.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
-
See Ingress and egress rules for more information.
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.