Crea y administra configuraciones de notificaciones

En esta página, se describe cómo usar la función de notificaciones de la API de Security Command Center, incluidos los siguientes ejemplos:

  • Crear una NotificationConfig
  • Obtén una NotificationConfig
  • Actualiza una NotificationConfig
  • Borra una NotificationConfig
  • Enumera NotificationConfig
  • Recibe notificaciones de Pub/Sub

Como alternativa, puedes configurar exportaciones continuas para Pub/Sub en Security Command Center.

Antes de comenzar

Para usar los ejemplos de esta página, debes completar la guía para configurar las notificaciones de hallazgo.

Para ejecutar los siguientes ejemplos, necesitas una función de Identity and Access Management (IAM) con los permisos adecuados:

  • Crear NotificationConfig: Editor de configuraciones de notificación del centro de seguridad (roles/securitycenter.notificationConfigEditor)
  • Obtener y enumerar NotificationConfig: Visualizador de configuraciones de notificación del centro de seguridad (roles/securitycenter.notificationConfigViewer) o Editor de configuraciones de notificación del centro de seguridad (roles/securitycenter.notificationConfigEditor)
  • Actualizar y borrar NotificationConfig: Editor de configuraciones de notificación del centro de seguridad (roles/securitycenter.notificationConfigEditor)

Para otorgar los roles adecuados a una entidad que accede a una notificationConfig, debes tener uno de los siguientes roles de IAM:

  • Administrador de la organización (roles/resourcemanager.organizationAdmin)
  • Administrador de IAM de carpeta (roles/resourcemanager.folderIamAdmin)
  • Administrador del proyecto de IAM (roles/resourcemanager.projectIamAdmin)

Los roles de IAM para Security Command Center se pueden otorgar a nivel de organización, carpeta o proyecto. Tu capacidad para ver, editar, crear o actualizar hallazgos, recursos y fuentes de seguridad depende del nivel al que se te otorga acceso. Para obtener más información sobre los roles de Security Command Center, consulta Control de acceso.

Residencia de datos y notificaciones

Si la residencia de datos está habilitada para Security Command Center, las configuraciones que definen las exportaciones continuas a Pub/Sub (notificationConfig recursos) están sujetas al control de residencia de datos y se almacenan en tu ubicación de Security Command Center.

Para exportar resultados en una ubicación de Security Command Center a Pub/Sub, debes configurar la exportación continua en la misma ubicación de Security Command Center que los resultados.

Dado que los filtros que se usan en las exportaciones continuas pueden contener datos sujetos a controles de residencia, asegúrate de especificar la ubicación correcta antes de crearlos. Security Command Center no restringe la ubicación en la que creas exportaciones.

Las exportaciones continuas solo se almacenan en la ubicación en la que se crean y no se pueden ver ni editar en otras ubicaciones.

Después de crear una exportación continua, no puedes cambiar su ubicación. Para cambiar la ubicación, debes borrar la exportación continua y volver a crearla en la ubicación nueva.

Para obtener información sobre cómo usar Security Command Center cuando la residencia de datos está habilitada, consulta Extremos regionales de Security Command Center.

Crea un NotificationConfig

Para crear un NotificationConfig, debes tener lo siguiente:

  • Un tema de Pub/Sub existente al que desees enviar notificaciones.
  • Roles de IAM obligatorios para la principal que crea la notificationConfig.

Para obtener más información, consulta el paso Configura un tema de Pub/Sub de la guía Configura las notificaciones de búsqueda.

Antes de crear una NotificationConfig, ten en cuenta que cada organización puede tener una cantidad limitada de archivos NotificationConfig. Para obtener más información, consulta Cuotas y límites.

El NotificationConfig incluye un campo filter que limita las notificaciones a eventos útiles. Este campo acepta todos los filtros disponibles en el método findings.list de la API de Security Command Center.

Cuando creas un NotificationConfig, especificas un elemento superior para el NotificationConfig de la Google Cloud jerarquía de recursos, ya sea una organización, una carpeta o un proyecto. Si necesitas recuperar, actualizar o borrar la NotificationConfig más adelante, debes incluir el ID numérico de la organización, la carpeta o el proyecto superior cuando hagas referencia a ella.

En la Google Cloud consola, algunos NotificationConfig recursos pueden tener una etiqueta Heredado, que indica que se crearon con la versión 1 de la API de Security Command Center. Puedes administrar estos NotificationConfig recursos con la Google Cloud consola, la gcloud CLI, la versión 1 de la API de Security Command Center o las bibliotecas cliente de la versión 1 para Security Command Center.

Para administrar estos NotificationConfig recursos con la gcloud CLI, no debes especificar una ubicación cuando ejecutes el comando de la gcloud CLI.

Para crear la NotificationConfig con el lenguaje o la plataforma que elijas, haz lo siguiente:

gcloud

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

Reemplaza lo siguiente:

  • NOTIFICATION_NAME: Es el nombre de la notificación. Debe tener entre 1 y 128 caracteres, y contener solo caracteres alfanuméricos, guiones bajos o guiones.
  • PARENT: Es el alcance en la jerarquía de recursos al que se aplica la notificación, organization, folder o project.
  • PARENT_ID: Es el ID de la organización, la carpeta o el proyecto superior, especificado en el formato organizations/123, folders/456 o projects/789.
  • LOCATION: Es la ubicación de Security Command Center en la que se creará una NotificationConfig. Si la residencia de datos está habilitada, usa eu, sa, o us. De lo contrario, usa el valor global.
  • NOTIFICATION_DESCRIPTION: Es una descripción de la notificación de no más de 1,024 caracteres.
  • PUBSUB_TOPIC: Es el tema de Pub/Sub que recibirá notificaciones. Su formato es projects/PROJECT_ID/topics/TOPIC.
  • FILTER: Es la expresión que defines para seleccionar qué resultados se envían a Pub/Sub. Por ejemplo, state=\"ACTIVE\".

Terraform

Crea una NotificationConfig para una organización:

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

Crea una NotificationConfig para una carpeta:

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

Crea una NotificationConfig para un proyecto:

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

Go

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

Las notificaciones ahora se publican en el tema de Pub/Sub que especificaste.

Para publicar notificaciones, se crea una cuenta de servicio para ti con el formato service-org-ORGANIZATION_ID@gcp-sa-scc-notification.iam.gserviceaccount.com. Esta cuenta de servicio se crea cuando creas tu primer NotificationConfig y se te otorga de forma automática el rol securitycenter.notificationServiceAgent en la política de IAM para PUBSUB_TOPIC cuando se crea la configuración de notificación. Esta función de cuenta de servicio es obligatoria para que las notificaciones funcionen.

Obtén una NotificationConfig

Para obtener una NotificationConfig, debes tener una función de IAM que incluya el permiso securitycenter.notification.get.

gcloud

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

Reemplaza lo siguiente:

  • NOTIFICATION_NAME: Es el nombre de la configuración de notificación.
  • PARENT_TYPE Es el nivel de la jerarquía de recursos en el que se especifica la configuración. Usa organization, folder o project.
  • PARENT_ID: Es el ID numérico del recurso superior.
  • LOCATION: Es la ubicación de Security Command Center en la que se obtendrá NotificationConfig. Si la residencia de datos está habilitada, usa eu, sa, o us. De lo contrario, usa el valor global.

Actualiza una NotificationConfig

Para actualizar una NotificationConfig, debes tener una función de IAM que incluya el permiso securitycenter.notification.update.

Cuando actualizas con una máscara de campo, solo se actualizan los campos que especificas. Si no usas una máscara de campo, todos los campos mutables de NotificationConfig se reemplazan por los valores nuevos. Puedes usar una máscara de campo para actualizar el tema y la descripción de Pub/Sub.

Para completar este ejemplo, debes suscribirte al tema nuevo y tu cuenta de servicio de notificaciones debe tener el permiso pubsub.topics.setIamPolicy en el tema.

Después de otorgar los permisos necesarios, actualiza la descripción, el tema de Pub/Sub y el filtro de NotificationConfig con el lenguaje que prefieras:

gcloud

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

Reemplaza lo siguiente:

  • NOTIFICATION_NAME: Es el nombre de la configuración de notificación.
  • PARENT_TYPE Es el nivel de la jerarquía de recursos en el que se especifica la configuración. Usa organization, folder o project.
  • PARENT_ID: Es el ID numérico del recurso superior.
  • LOCATION: Es la ubicación de Security Command Center en la que se actualizará NotificationConfig. Si la residencia de datos está habilitada, usa eu, sa, o us. De lo contrario, usa el valor global.
  • NOTIFICATION_DESCRIPTION: Es una descripción de la notificación de no más de 1,024 caracteres.
  • PUBSUB_TOPIC: Es el tema de Pub/Sub que recibirá notificaciones. Su formato es projects/PROJECT_ID/topics/TOPIC.
  • FILTER: Es la expresión que defines para seleccionar qué resultados se envían a Pub/Sub. Por ejemplo, state="ACTIVE".

Borra una NotificationConfig

Para borrar una NotificationConfig, debes tener una función de IAM que incluya el permiso securitycenter.notification.delete.

Cuando borras una NotificationConfig, la función securitycenter.notificationServiceAgent permanece en el tema de Pub/Sub. Si no usas el tema de Pub/Sub en ningún otro NotificationConfig, quita la función del tema. Para obtener más información, consulta control de acceso.

Borra un NotificationConfig con el lenguaje que elijas:

gcloud

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

Reemplaza lo siguiente:

  • NOTIFICATION_NAME: Es el nombre de la configuración de notificación.
  • PARENT_TYPE Es el nivel de la jerarquía de recursos en el que se especifica la configuración. Usa organization, folder o project.
  • PARENT_ID: Es el ID numérico del recurso superior.
  • LOCATION: Es la ubicación de Security Command Center en la que se borrará NotificationConfig. Si la residencia de datos está habilitada, usa eu, sa, o us. De lo contrario, usa el valor global.

Enumera NotificationConfigs

Para enumerar NotificationConfigs, debes tener una función de IAM que incluya el permiso securitycenter.notification.list.

Se paginan todas las listas de la API de Security Command Center. Cada respuesta muestra una página de resultados y un token para mostrar la página siguiente. El valor predeterminado pageSize es 10. Puedes configurar el tamaño de la página a un mínimo de 1 y un máximo de 1,000.

Enumera NotificationConfigs con el lenguaje que elijas:

gcloud

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

Reemplaza lo siguiente:

Recibe notificaciones de Pub/Sub

En esta sección, se proporciona un mensaje de notificación de muestra y ejemplos que muestran cómo convertir un mensaje de Pub/Sub en una NotificationMessage que contiene un hallazgo.

Las notificaciones se publican en Pub/Sub en formato JSON. A continuación, se incluye un ejemplo de un mensaje de notificación:

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

Convierte un mensaje de Pub/Sub en un NotificationMessage con el lenguaje que elijas:

gcloud

Gcloud CLI no admite la conversión de un mensaje de Pub/Sub a NotificationMessage. Puedes usar gcloud CLI para obtener un NotificationMessage y, luego, imprimir el JSON directamente en tu 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

Reemplaza lo siguiente:

  • PROJECT_ID por el ID del proyecto
  • SUBSCRIPTION_ID por tu ID de suscripción.

Go

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
}

¿Qué sigue?