Setting up finding notifications

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.

Security Command Center roles are granted at the organization, folder, or project level. Your ability to view, edit, create, or update findings, assets, security sources, and security marks 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 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.

Note: By default, Pub/Sub subscriptions expire after 31 days of inactivity, defined as subscriptions without active connections, pull requests, or push successes. To keep subscriptions longer, set the --expiration-period flag to a higher value or the special value never, indicating the subscription never expires. See Using subscription properties for more information.

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 or roles/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.
1. Set your organization name:
```
  export ORGANIZATION_ID=ORGANIZATION_ID
```
  Replace ORGANIZATION_ID with your organization ID.
2. 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.
3. 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.
4. Set the topic ID or use the topic set from Step 1.
```
  export TOPIC_ID=TOPIC_ID
```
  Replace TOPIC_ID with your topic name.
5. Grant the gcloud tool 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'
```
6. Grant the gcloud tool account a role for the organization that includes all of the securitycenter.notification permissions, like roles/securitycenter.notificationConfigEditor or roles/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:
1. Set your organization name:
```
  export ORGANIZATION_ID=ORGANIZATION_ID
```
  Replace ORGANIZATION_ID with your organization ID.
2. 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.
3. 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.
4. 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 the KEY_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, like roles/securitycenter.notificationConfigEditor or roles/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:
1. Set the topic ID:
```
  export TOPIC_ID=TOPIC_ID
```
2. 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.
3. 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.

Note: By default, Pub/Sub subscriptions expire after 31 days of inactivity, defined as subscriptions without active connections, pull requests, or push successes. To keep subscriptions longer, set the --expiration-period flag to a higher value or the special value never, indicating the subscription never expires. See Using subscription properties for more information.

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:
1. Set your organization name:
```
  export ORGANIZATION_ID=ORGANIZATION_ID
```
  Replace ORGANIZATION_ID with your organization ID.
2. 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

View on GitHub

from google.cloud import securitycenter as securitycenter

client = securitycenter.SecurityCenterClient()

# TODO: organization_id = "your-org-id"
# TODO: notification_config_id = "your-config-id"
# TODO: pubsub_topic = "projects/{your-project-id}/topics/{your-topic-ic}"
# Ensure this ServiceAccount has the "pubsub.topics.setIamPolicy" permission on the new topic.

org_name = "organizations/{org_id}".format(org_id=organization_id)

created_notification_config = client.create_notification_config(
    request={
        "parent": org_name,
        "config_id": notification_config_id,
        "notification_config": {
            "description": "Notification for active findings",
            "pubsub_topic": pubsub_topic,
            "streaming_config": {"filter": 'state = "ACTIVE"'},
        },
    }
)

print(created_notification_config)

Java

View on GitHub

import com.google.cloud.securitycenter.v1.CreateNotificationConfigRequest;
import com.google.cloud.securitycenter.v1.NotificationConfig;
import com.google.cloud.securitycenter.v1.NotificationConfig.StreamingConfig;
import com.google.cloud.securitycenter.v1.SecurityCenterClient;
import java.io.IOException;

  public static NotificationConfig createNotificationConfig(
      String organizationId, String notificationConfigId, String projectId, String topicName)
      throws IOException {
    // String organizationId = "{your-org-id}";
    // String notificationConfigId = {"your-unique-id"};
    // String projectId = "{your-project}"";
    // String topicName = "{your-topic}";

    String orgName = String.format("organizations/%s", organizationId);

    // Ensure this ServiceAccount has the "pubsub.topics.setIamPolicy" permission on the topic.
    String pubsubTopic = String.format("projects/%s/topics/%s", projectId, topicName);

    try (SecurityCenterClient client = SecurityCenterClient.create()) {
      CreateNotificationConfigRequest request =
          CreateNotificationConfigRequest.newBuilder()
              .setParent(orgName)
              .setConfigId(notificationConfigId)
              .setNotificationConfig(
                  NotificationConfig.newBuilder()
                      .setDescription("Java notification config")
                      .setPubsubTopic(pubsubTopic)
                      .setStreamingConfig(
                          StreamingConfig.newBuilder().setFilter("state = \"ACTIVE\"").build())
                      .build())
              .build();

      NotificationConfig response = client.createNotificationConfig(request);
      System.out.println(String.format("Notification config was created: %s", response));
      return response;
    }
  }

Go

View on GitHub

import (
	"context"
	"fmt"
	"io"

	securitycenter "cloud.google.com/go/securitycenter/apiv1"
	securitycenterpb "google.golang.org/genproto/googleapis/cloud/securitycenter/v1"
)

func createNotificationConfig(w io.Writer, orgID string, pubsubTopic string, notificationConfigID string) error {
	// orgID := "your-org-id"
	// pubsubTopic := "projects/{your-project}/topics/{your-topic}"
	// notificationConfigID := "your-config-id"

	ctx := context.Background()
	client, err := securitycenter.NewClient(ctx)

	if err != nil {
		return fmt.Errorf("securitycenter.NewClient: %v", err)
	}
	defer client.Close()

	req := &securitycenterpb.CreateNotificationConfigRequest{
		Parent:   fmt.Sprintf("organizations/%s", orgID),
		ConfigId: notificationConfigID,
		NotificationConfig: &securitycenterpb.NotificationConfig{
			Description: "Go sample config",
			PubsubTopic: pubsubTopic,
			NotifyConfig: &securitycenterpb.NotificationConfig_StreamingConfig_{
				StreamingConfig: &securitycenterpb.NotificationConfig_StreamingConfig{
					Filter: `state = "ACTIVE"`,
				},
			},
		},
	}

	notificationConfig, err := client.CreateNotificationConfig(ctx, req)
	if err != nil {
		return fmt.Errorf("Failed to create notification config: %v", err)
	}
	fmt.Fprintln(w, "New NotificationConfig created: ", notificationConfig)

	return nil
}

Node.js

View on GitHub

// npm install @google-cloud/security-center/
const {SecurityCenterClient} = require('@google-cloud/security-center');

const client = new SecurityCenterClient();

// organizationId = "your-org-id";
// configId = "your-config-name";
// pubsubTopic = "projects/{your-project}/topics/{your-topic}";
// Ensure this Service Account has the "pubsub.topics.setIamPolicy" permission on this topic.

const orgName = client.organizationPath(organizationId);

async function createNotificationConfig() {
  const [response] = await client.createNotificationConfig({
    parent: orgName,
    configId: configId,
    notificationConfig: {
      description: 'Sample config for node.js',
      pubsubTopic: pubsubTopic,
      streamingConfig: {filter: 'state = "ACTIVE"'},
    },
  });
  console.log('Notification config creation succeeded: ', response);
}

createNotificationConfig();

PHP

View on GitHub

use Google\Cloud\SecurityCenter\V1\SecurityCenterClient;
use Google\Cloud\SecurityCenter\V1\NotificationConfig;
use Google\Cloud\SecurityCenter\V1\NotificationConfig\StreamingConfig;

/** Uncomment and populate these variables in your code */
// $organizationId = "{your-org-id}";
// $notificationConfigId = {"your-unique-id"};
// $projectId = "{your-project}"";
// $topicName = "{your-topic}";

$securityCenterClient = new SecurityCenterClient();
$organizationName = $securityCenterClient::organizationName($organizationId);
$pubsubTopic = $securityCenterClient::topicName($projectId, $topicName);

$streamingConfig = (new StreamingConfig())->setFilter("state = \"ACTIVE\"");
$notificationConfig = (new NotificationConfig())
    ->setDescription('A sample notification config')
    ->setPubsubTopic($pubsubTopic)
    ->setStreamingConfig($streamingConfig);

$response = $securityCenterClient->createNotificationConfig(
    $organizationName,
    $notificationConfigId,
    $notificationConfig
);
printf('Notification config was created: %s' . PHP_EOL, $response->getName());

Ruby

View on GitHub

require "google/cloud/security_center"

# Your organization id. e.g. for "organizations/123", this would be "123".
# org_id = "YOUR_ORGANZATION_ID"

# Your notification config id. e.g. for
# "organizations/123/notificationConfigs/my-config" this would be "my-config".
# config_id = "YOUR_CONFIG_ID"

# The PubSub topic where notifications will be published.
# pubsub_topic = "YOUR_TOPIC"

client = Google::Cloud::SecurityCenter.security_center

org_path = client.organization_path organization: org_id

notification_config = {
  description:      "Sample config for Ruby",
  pubsub_topic:     pubsub_topic,
  streaming_config: { filter: 'state = "ACTIVE"' }
}

response = client.create_notification_config(
  parent:              org_path,
  config_id:           config_id,
  notification_config: notification_config
)
puts "Created notification config #{config_id}: #{response}."

C#

View on GitHub


using Google.Api.Gax.ResourceNames;
using Google.Cloud.SecurityCenter.V1;
using System;

///<summary> Create NotificationConfig Snippet. </summary>
public class CreateNotificationConfigSnippets
{
    public static NotificationConfig CreateNotificationConfig(
        string organizationId, string notificationConfigId, string projectId, string topicName)
    {
        OrganizationName orgName = new OrganizationName(organizationId);
        TopicName pubsubTopic = new TopicName(projectId, topicName);

        SecurityCenterClient client = SecurityCenterClient.Create();
        CreateNotificationConfigRequest request = new CreateNotificationConfigRequest
        {
            ParentAsOrganizationName = orgName,
            ConfigId = notificationConfigId,
            NotificationConfig = new NotificationConfig
            {
                Description = ".Net notification config",
                PubsubTopicAsTopicName = pubsubTopic,
                StreamingConfig = new NotificationConfig.Types.StreamingConfig { Filter = "state = \"ACTIVE\"" }
            }
        };

        NotificationConfig response = client.CreateNotificationConfig(request);
        Console.WriteLine($"Notification config was created: {response}");
        return response;
    }
}

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.

Setting up finding notifications

Before you begin

Setting up Security Command Center API notifications

Enabling the Security Command Center API

Setting up a Pub/Sub topic

gcloud

Step 1: Set up Pub/Sub

Step 2: Set up gcloud tool account permissions

Client libraries

Step 1: Setting up a service account

Step 2: Setting up a development environment

Python

Java

Go

Node.js

Step 3: Setting up Pub/Sub

Creating a NotificationConfig

gcloud

Python

Java

Go

Node.js

PHP

Ruby

C#

What's next

Step 2: Set up `gcloud` tool account permissions