Setting up finding notifications

This page describes how to 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.

Before you begin

To enable Security Command Center API notifications, you must have the Security Center Admin Cloud Identity and Access Management (Cloud IAM) role.
To access the Security Command Center dashboard, you must have the Security Center Admin Viewer Cloud IAM role.
To grant appropriate roles to the notifications service account or gcloud tool account, you must have the Organization Administrator Cloud 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. To create a new topic:
```
   gcloud pubsub topics create topic-id
```
Set environment variables:
1. Set the topic ID:
```
  export TOPIC_ID=topic-id
```

Create a subscription to the topic:

   gcloud pubsub subscriptions create subscription-id --topic topic-id

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 Cloud 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
```
2. Set the project ID for the project that the Pub/Sub topic belongs under:
```
  export PUBSUB_PROJECT=project-id
```
3. Set the gcloud tool account that you are using:
```
  export GCLOUD_ACCOUNT=your-username@email.com
```
4. Set the topic ID or use the topic set from Step 1.
```
  export TOPIC_ID=topic-id
```
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 beta organizations add-iam-policy-binding $ORGANIZATION_ID \
    --member="user:$GCLOUD_ACCOUNT" \
    --role='role-name'
```

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
```
2. Set the project ID for the project in which you want to enable the notifications API:
```
  export PROJECT_ID=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
```
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
```

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 beta organizations add-iam-policy-binding $ORGANIZATION_ID \
     --member="serviceAccount:$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com" \
     --role='role-name'
```

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
```
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
```

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 a Cloud 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
```
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
```
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
```

Create a subscription to the topic:

   gcloud pubsub subscriptions create subscription-id --topic topic-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

Each organization can have a limited number of NotificationConfigs. 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.

To complete this step, you must have the Organization Administrator Cloud IAM role so that you can grant appropriate roles to the notifications service account or gcloud tool account.

To grant the account the Security Center Notifications Configurations Editor Cloud IAM role using the gcloud command-line tool:

Set environment variables:
1. Set your organization name:
```
  export ORGANIZATION_ID=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:
  - 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 beta organizations add-iam-policy-binding \
     $ORGANIZATION_ID \
     --member="user:$EMAIL" \
     --role='roles/securitycenter.notificationConfigEditor'
     ```

Or grant the role to the service account:

   gcloud beta 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 alpha 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(
    org_name,
    notification_config_id,
    {
        "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();

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.

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 gcloud tool. You can optionally revoke the permissions you granted to this account. To learn more, see Granting, changing, and revoking access in the Cloud IAM documentation.

What's next

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

What's next

Step 2: Set up `gcloud` tool account permissions