Criar e gerir configurações de notificações

Esta página descreve como usar a funcionalidade de notificações da API Security Command Center, incluindo os seguintes exemplos:

  • Crie um NotificationConfig
  • Receba um NotificationConfig
  • Atualize um NotificationConfig
  • Elimine um NotificationConfig
  • Lista NotificationConfig
  • Receba notificações do Pub/Sub

Em alternativa, pode configurar exportações contínuas para o Pub/Sub no Security Command Center.

Antes de começar

Para usar os exemplos nesta página, tem de concluir o guia para configurar a receção de notificações de localização.

Para executar os exemplos seguintes, precisa de uma função de gestão de identidade e de acesso (IAM) com as autorizações adequadas:

  • Criar NotificationConfig: Security Center Notification Configurations Editor (roles/securitycenter.notificationConfigEditor)
  • Obter e listar NotificationConfig: visualizador de configurações de notificações do centro de segurança (roles/securitycenter.notificationConfigViewer) ou editor de configurações de notificações do centro de segurança (roles/securitycenter.notificationConfigEditor)
  • Atualizar e eliminar NotificationConfig: notificação do centro de segurança Editor de configurações (roles/securitycenter.notificationConfigEditor)

Para conceder funções adequadas a um principal que acede a um notificationConfig, tem de ter uma das seguintes funções de IAM:

  • Administrador da organização (roles/resourcemanager.organizationAdmin)
  • Administrador de IAM de pastas (roles/resourcemanager.folderIamAdmin)
  • Administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin)

As funções do IAM para o Security Command Center podem ser concedidas ao nível da organização, da pasta ou do projeto. A sua capacidade de ver, editar, criar ou atualizar resultados, recursos e origens de segurança depende do nível para o qual lhe é concedido acesso. Para saber mais sobre as funções do Security Command Center, consulte o artigo Controlo de acesso.

Residência de dados e notificações

Se a residência de dados estiver ativada para o Security Command Center, as configurações que definem exportações contínuas para recursos do Pub/Sub—notificationConfig—estão sujeitas ao controlo de residência de dados e são armazenadas na sua localização do Security Command Center.

Para exportar resultados numa localização do Security Command Center para o Pub/Sub, tem de configurar a exportação contínua na mesma localização do Security Command Center que os resultados.

Uma vez que os filtros usados em exportações contínuas podem conter dados sujeitos a controlos de residência, certifique-se de que especifica a localização correta antes de os criar. O Security Command Center não restringe a localização em que cria exportações.

As exportações contínuas são armazenadas apenas na localização em que são criadas e não podem ser vistas nem editadas noutras localizações.

Depois de criar uma exportação contínua, não pode alterar a respetiva localização. Para alterar a localização, tem de eliminar a exportação contínua e recriá-la na nova localização.

Para saber como usar o Security Command Center quando a residência de dados está ativada, consulte os endpoints regionais do Security Command Center.

Criar um NotificationConfig

Para criar um NotificationConfig, tem de ter:

  • Um tópico do Pub/Sub existente para o qual quer enviar notificações.
  • Funções de IAM necessárias para o principal que cria o notificationConfig.

Para mais informações, consulte o passo para configurar um tópico do Pub/Sub no guia para configurar notificações de localização.

Antes de criar um NotificationConfig, tenha em atenção que cada organização pode ter um número limitado de ficheiros NotificationConfig. Para mais informações, consulte o artigo Quotas e limites.

O NotificationConfig inclui um campo filter que limita as notificações a eventos úteis. Este campo aceita todos os filtros disponíveis no método Security Command Center API findings.list.

Quando cria um NotificationConfig, especifica um elemento principal para o NotificationConfig a partir da hierarquia de recursos Google Cloud , seja uma organização, uma pasta ou um projeto. Se precisar de obter, atualizar ou eliminar o NotificationConfig mais tarde, tem de incluir o ID numérico da organização principal, da pasta ou do projeto quando o referenciar.

Na Google Cloud consola, alguns recursos do NotificationConfig podem ter uma etiqueta Antigo que indica que foram criados com a API Security Command Center v1. Pode gerir estes recursos NotificationConfig com a consola Google Cloud ; a CLI gcloud; a API Security Command Center v1; ou as bibliotecas de cliente v1 para o Security Command Center.

Para gerir estes recursos NotificationConfig com a CLI gcloud, não pode especificar uma localização quando executar o comando da CLI gcloud.

Para criar o NotificationConfig com o idioma ou a plataforma da sua escolha:

gcloud

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

Substitua o seguinte:

  • NOTIFICATION_NAME: o nome da notificação. Tem de ter entre 1 e 128 carateres e conter apenas carateres alfanuméricos, sublinhados ou hífenes.
  • PARENT: o âmbito na hierarquia de recursos ao qual a notificação se aplica, organization, folder ou project.
  • PARENT_ID: o ID da organização principal, da pasta ou do projeto, especificado no formato de organizations/123, folders/456 ou projects/789.
  • LOCATION: a localização do Security Command Center na qual criar um NotificationConfig; se a residência de dados estiver ativada, use eu, sa ou us; caso contrário, use o valor global.
  • NOTIFICATION_DESCRIPTION: uma descrição da notificação com um máximo de 1024 carateres.
  • PUBSUB_TOPIC: o tópico do Pub/Sub que vai receber notificações. O formato é projects/PROJECT_ID/topics/TOPIC.
  • FILTER: a expressão que define para selecionar que descobertas são enviadas para o Pub/Sub. Por exemplo, state=\"ACTIVE\".

Terraform

Crie um NotificationConfig para uma organização:

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\""
  }
}

Crie um NotificationConfig para uma pasta:

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 {
    filter = "category = \"OPEN_FIREWALL\" AND state = \"ACTIVE\""
  }
}

Crie um NotificationConfig para um projeto:

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

resource "google_scc_v2_project_notification_config" "custom_notification_config" {
  config_id    = "my-config"
  project      = "my-project-name"
  location     = "global"
  description  = "My custom Cloud Security Command Center Finding Notification Configuration"
  pubsub_topic =  google_pubsub_topic.scc_v2_project_notification.id

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

Ir

import (
	"context"
	"fmt"
	"io"

	securitycenter "cloud.google.com/go/securitycenter/apiv2"
	"cloud.google.com/go/securitycenter/apiv2/securitycenterpb"
)

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: %w", err)
	}
	defer client.Close()

	req := &securitycenterpb.CreateNotificationConfigRequest{
		// Parent must be in one of the following formats:
		//		"organizations/{orgId}/locations/global"
		//		"projects/{projectId}/locations/global"
		//		"folders/{folderId}/locations/global"
		Parent:   fmt.Sprintf("organizations/%s/locations/global", 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: %w", err)
	}
	fmt.Fprintln(w, "New NotificationConfig created: ", notificationConfig)

	return nil
}

Java


package vtwo.notifications;

import com.google.cloud.securitycenter.v2.LocationName;
import com.google.cloud.securitycenter.v2.NotificationConfig;
import com.google.cloud.securitycenter.v2.SecurityCenterClient;
import java.io.IOException;

public class CreateNotification {

  public static void main(String[] args) throws IOException {
    // parentId: must be in one of the following formats:
    //    "organizations/{organization_id}"
    //    "projects/{project_id}"
    //    "folders/{folder_id}"
    String parentId = "{parent-id}";
    String topicName = "{your-topic}";
    String notificationConfigId = "{your-notification-id}";
    // Specify the location of the notification config.
    String location = "global";

    createNotificationConfig(parentId, location, topicName, notificationConfigId);
  }

  // Crete a notification config.
  // Ensure the ServiceAccount has the "pubsub.topics.setIamPolicy" permission on the new topic.
  public static NotificationConfig createNotificationConfig(
      String parentId, String location, String topicName, String notificationConfigId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (SecurityCenterClient client = SecurityCenterClient.create()) {

      String pubsubTopic = String.format("projects/%s/topics/%s", parentId, topicName);

      NotificationConfig notificationConfig = NotificationConfig.newBuilder()
          .setDescription("Java notification config")
          .setPubsubTopic(pubsubTopic)
          .setStreamingConfig(
              NotificationConfig.StreamingConfig.newBuilder().setFilter("state = \"ACTIVE\"")
                  .build())
          .build();

      NotificationConfig response = client.createNotificationConfig(
          LocationName.of(parentId, location), notificationConfig, notificationConfigId);

      System.out.printf("Notification config was created: %s%n", response);
      return response;
    }
  }
}

Node.js

// npm install '@google-cloud/security-center'
const {SecurityCenterClient} = require('@google-cloud/security-center').v2;
const uuidv1 = require('uuid').v1;

const client = new SecurityCenterClient();
/*
 *  Required. Resource name of the new notification config's parent. Its format
 *  is "organizations/[organization_id]/locations/[location_id]",
 *  "folders/[folder_id]/locations/[location_id]", or
 *  "projects/[project_id]/locations/[location_id]".
 */
const parent = `projects/${projectId}/locations/${location}`;

/**
 *  Required.
 *  Unique identifier provided by the client within the parent scope.
 *  It must be between 1 and 128 characters and contain alphanumeric
 *  characters, underscores, or hyphens only.
 */
const configId = 'notif-config-test-node-create-' + uuidv1();

// pubsubTopic = "projects/{your-project}/topics/{your-topic}";
const pubsubTopic = `projects/${projectId}/topics/${topicName}`;

/**
 *  Required. The notification config being created. The name and the service
 *  account will be ignored as they are both output only fields on this
 *  resource.
 */
const notificationConfig = {
  description: 'Sample config for node v2',
  pubsubTopic: pubsubTopic,
  streamingConfig: {filter: 'state = "ACTIVE"'},
};

// Build the request.
const createNotificationRequest = {
  parent: parent,
  configId: configId,
  notificationConfig: notificationConfig,
};

async function createNotificationConfig() {
  const [response] = await client.createNotificationConfig(
    createNotificationRequest
  );
  console.log('Notification configuration creation successful: %j', response);
}

await createNotificationConfig();

Python

def create_notification_config(
    parent_id, location_id, pubsub_topic, notification_config_id
) -> NotificationConfig:
    """
    This method is used to create the Notification Config.
    Args:
        parent_id: must be in one of the following formats:
            "organizations/{organization_id}"
            "projects/{project_id}"
            "folders/{folder_id}"
        location_id: "global"
        pubsub_topic: "projects/{your-project-id}/topics/{your-topic-id}"
        notification_config_id: "your-config-id"


    Ensure this ServiceAccount has the "pubsub.topics.setIamPolicy" permission on the new topic.
    """
    from google.cloud import securitycenter_v2 as securitycenter_v2

    client = securitycenter_v2.SecurityCenterClient()
    parent_id = parent_id + "/locations/" + location_id
    response = client.create_notification_config(
        request={
            "parent": parent_id,
            "config_id": notification_config_id,
            "notification_config": {
                "description": "Notification for active findings",
                "pubsub_topic": pubsub_topic,
                "streaming_config": {"filter": 'state = "ACTIVE"'},
            },
        }
    )
    print(f"create notification config response:{response}")
    return response

As notificações são agora publicadas no tópico Pub/Sub que especificou.

Para publicar notificações, é criada uma conta de serviço para si no formato de service-org-ORGANIZATION_ID@gcp-sa-scc-notification.iam.gserviceaccount.com. Esta conta de serviço é criada quando cria o seu primeiro NotificationConfig e recebe automaticamente a função securitycenter.notificationServiceAgent na política de IAM para PUBSUB_TOPIC quando cria a configuração de notificação. Esta função de conta de serviço é necessária para o funcionamento das notificações.

Obter um NotificationConfig

Para receber um NotificationConfig, tem de ter uma função de IAM que inclua a autorização securitycenter.notification.get.

gcloud

gcloud scc notifications describe NOTIFICATION_NAME \
  --PARENT_TYPE=PARENT_ID \
  --location=LOCATION

Substitua o seguinte:

  • NOTIFICATION_NAME: o nome da configuração de notificação.
  • PARENT_TYPE o nível da hierarquia de recursos onde a configuração é especificada; use organization, folder ou project.
  • PARENT_ID: o ID numérico do recurso principal.
  • LOCATION: a localização do Security Command Center onde obter o NotificationConfig; se a residência de dados estiver ativada, use eu, sa ou us; caso contrário, use o valor global.

Atualizar um NotificationConfig

Para atualizar um NotificationConfig, tem de ter uma função de IAM que inclua a autorização securitycenter.notification.update.

Quando faz a atualização através de uma máscara de campo, apenas os campos especificados são atualizados. Se não usar uma máscara de campo, todos os campos mutáveis no NotificationConfig são substituídos pelos novos valores. Pode usar uma máscara de campo para atualizar o tópico e a descrição do Pub/Sub.

Para concluir este exemplo, tem de subscrever o novo tópico e a sua conta de serviço de notificações tem de ter a autorização pubsub.topics.setIamPolicy no tópico.

Depois de conceder as autorizações necessárias, atualize a NotificationConfigdescrição, o tópico do Pub/Sub e o filtro com o idioma da sua escolha:

gcloud

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

Substitua o seguinte:

  • NOTIFICATION_NAME: o nome da configuração de notificação.
  • PARENT_TYPE o nível da hierarquia de recursos onde a configuração é especificada; use organization, folder ou project.
  • PARENT_ID: o ID numérico do recurso principal.
  • LOCATION: a localização do centro de comandos de segurança na qual atualizar o NotificationConfig; se a residência de dados estiver ativada, use eu, sa ou us; caso contrário, use o valor global.
  • NOTIFICATION_DESCRIPTION: uma descrição da notificação com um máximo de 1024 carateres.
  • PUBSUB_TOPIC: o tópico do Pub/Sub que vai receber notificações. O formato é projects/PROJECT_ID/topics/TOPIC.
  • FILTER: a expressão que define para selecionar que resultados são enviados para o Pub/Sub. Por exemplo, state="ACTIVE".

Eliminar um NotificationConfig

Para eliminar um NotificationConfig, tem de ter uma função do IAM que inclua a autorização securitycenter.notification.delete.

Quando elimina uma NotificationConfig, a função securitycenter.notificationServiceAgent permanece no tópico do Pub/Sub. Se não estiver a usar o tópico do Pub/Sub em mais nenhum NotificationConfig, remova a função do tópico. Para mais informações, consulte o artigo sobre o controlo de acesso.

Elimine um NotificationConfig com o idioma da sua escolha:

gcloud

gcloud scc notifications delete NOTIFICATION_NAME \
  --PARENT_TYPE=PARENT_ID \
  --location=LOCATION

Substitua o seguinte:

  • NOTIFICATION_NAME: o nome da configuração de notificação.
  • PARENT_TYPE o nível da hierarquia de recursos onde a configuração é especificada; use organization, folder ou project.
  • PARENT_ID: o ID numérico do recurso principal.
  • LOCATION: a localização do Security Command Center na qual eliminar o NotificationConfig; se a residência de dados estiver ativada, use eu, sa ou us; caso contrário, use o valor global.

Listar NotificationConfigs

Para listar NotificationConfigs, tem de ter uma função de IAM que inclua a autorização securitycenter.notification.list.

Todas as listas da API Security Command Center são paginadas. Cada resposta devolve uma página de resultados e um token para devolver a página seguinte. O valor predefinido de pageSize é 10. Pode configurar o tamanho da página para um mínimo de 1 e um máximo de 1000.

Apresente a lista NotificationConfigs no idioma da sua escolha:

gcloud

gcloud scc notifications list PARENT_TYPE/PARENT_ID \
  --location=LOCATION

Substitua o seguinte:

Receção de notificações do Pub/Sub

Esta secção fornece uma mensagem de notificação de exemplo e exemplos que mostram como converter uma mensagem do Pub/Sub num NotificationMessage que contém uma descoberta.

As notificações são publicadas no Pub/Sub no formato JSON. Segue-se um exemplo de uma mensagem de notificação:

{
   "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"
   }
 }

Converta uma mensagem do Pub/Sub num NotificationMessage usando o idioma à sua escolha:

gcloud

A CLI gcloud não suporta a conversão de uma mensagem do Pub/Sub num NotificationMessage. Pode usar a CLI gcloud para obter um NotificationMessage e imprimir o JSON diretamente no seu 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

Substitua o seguinte:

  • PROJECT_ID com o ID do seu projeto.
  • SUBSCRIPTION_ID com o ID da sua subscrição.

Ir

import (
	"bytes"
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
	"cloud.google.com/go/securitycenter/apiv2/securitycenterpb"
	"github.com/golang/protobuf/jsonpb"
)

func receiveMessages(w io.Writer, projectID string, subscriptionName string) error {
	// projectID := "your-project-id"
	// subsriptionName := "your-subscription-name"

	ctx := context.Background()

	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub := client.Subscription(subscriptionName)
	cctx, cancel := context.WithCancel(ctx)
	err = sub.Receive(cctx, func(ctx context.Context, msg *pubsub.Message) {
		var notificationMessage = new(securitycenterpb.NotificationMessage)
		jsonpb.Unmarshal(bytes.NewReader(msg.Data), notificationMessage)

		fmt.Fprintln(w, "Got finding: ", notificationMessage.GetFinding())
		msg.Ack()
		cancel()
	})
	if err != nil {
		return fmt.Errorf("Receive: %w", err)
	}

	return nil
}

O que se segue?