Enable finding notifications for Pub/Sub

This page explains how to use the Security Command Center API to enable finding notifications for Pub/Sub.

You can configure notifications to automatically send new findings and finding updates to a Pub/Sub topic in near-real time. You can use these notifications to trigger automated actions, such as invoking Cloud Run functions for response, enrichment, or remediation. For example solutions, see the Security Command Center open-source repository of Cloud Run functions code.

If you prefer a simplified setup experience using the Google Cloud console instead of the API, see Continuous exports. Continuous exports provide the same functionality as API notifications.

Alternatively, you can export findings to BigQuery for analysis.

Before you begin

Before you enable finding notifications, you must obtain specific Identity and Access Management (IAM) roles and permissions, enable the Security Command Center API, and familiarize yourself with data residency limitations.

Required roles

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.

Enable the Security Command Center API

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 learn how to use Security Command Center when data residency is enabled, see Security Command Center regional endpoints.

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:

1. Go to the Google Cloud console.

   Go to the Google Cloud console

2. Select the project where you enabled the Security Command Center API.

3. Click Activate Cloud Shell.

4. 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.

5. Create a subscription to the topic:

   gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID
   

   Replace the following:

   • SUBSCRIPTION_ID: the subscription ID
   • TOPIC_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:

1. Go to the Google Cloud console.

   Go to the Google Cloud console

2. Select the project for which you enabled the Security Command Center API.

3. Click Activate Cloud Shell.

4. 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 topic
   • TOPIC_ID: the topic ID
   • GOOGLE_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.

To create the NotificationConfig using the language or platform of your choice:

gcloud scc notifications create NOTIFICATION_NAME \
  --PARENT=PARENT_ID \
  --location=LOCATION \
  --description="NOTIFICATION_DESCRIPTION" \
  --pubsub-topic=PUBSUB_TOPIC \
  --filter="FILTER"

resource "google_pubsub_topic" "scc_v2_organization_notification_config" {
  name = "my-topic"
}

resource "google_scc_v2_organization_notification_config" "custom_organization_notification_config" {
  config_id    = "my-config"
  organization = "123456789"
  location     = "global"
  description  = "My custom Cloud Security Command Center Finding Organization Notification Configuration"
  pubsub_topic = google_pubsub_topic.scc_v2_organization_notification_config.id

  streaming_config {
    filter = "category = \"OPEN_FIREWALL\" AND state = \"ACTIVE\""
  }
}

resource "google_folder" "folder" {
  parent       = "organizations/123456789"
  display_name = "folder-name"
}

resource "google_pubsub_topic" "scc_v2_folder_notification_config" {
  name = "my-topic"
}

resource "google_scc_v2_folder_notification_config" "custom_notification_config" {
  config_id    = "my-config"
  folder       = google_folder.folder.folder_id
  location     = "global"
  description  = "My custom Cloud Security Command Center Finding Notification Configuration"
  pubsub_topic =  google_pubsub_topic.scc_v2_folder_notification_config.id

  streaming_config