Créer et gérer des configurations de notification

Cette page explique comment utiliser la fonctionnalité de notifications de l'API Security Command Center, y compris les exemples suivants:

• Créer un objet NotificationConfig
• Obtenir un objet NotificationConfig
• Mettre à jour un objet NotificationConfig
• Supprimer un objet NotificationConfig
• Répertorier NotificationConfig
• Recevoir des notifications Pub/Sub

Les clients Security Command Center Premium peuvent également configurer des exportations continues pour Pub/Sub dans Security Command Center.

Avant de commencer

Pour utiliser les exemples de cette page, vous devez suivre le guide Configurer les notifications de résultats.

Pour exécuter les exemples suivants, vous avez besoin d'un rôle de gestion de l'authentification et des accès (IAM) avec les autorisations appropriées :

• Créer NotificationConfig: Éditeur de configuration des notifications du centre de sécurité (roles/securitycenter.notificationConfigEditor)
• Obtenir et répertorier NotificationConfig: Lecteur de configurations de notifications du centre de sécurité (roles/securitycenter.notificationConfigViewer) ou Éditeur de configurations de notifications du centre de sécurité (roles/securitycenter.notificationConfigEditor)
• Mettre à jour et supprimer NotificationConfig: Éditeur de configuration des notifications du centre de sécurité (roles/securitycenter.notificationConfigEditor)

Pour accorder des rôles appropriés à un principal qui accède à un notificationConfig, vous devez disposer de l'un des rôles IAM suivants:

• Administrateur de l'organisation (roles/resourcemanager.organizationAdmin)
• Administrateur IAM de dossiers (roles/resourcemanager.folderIamAdmin)
• Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin)

Les rôles IAM pour Security Command Center peuvent être attribués au niveau de l'organisation, du dossier ou du projet. Votre capacité à afficher, modifier, créer ou mettre à jour les résultats, les éléments et les sources de sécurité dépend du niveau pour lequel vous disposez d'un accès. Pour en savoir plus sur les rôles Security Command Center, consultez la page Contrôle des accès.

Résidence des données et notifications

Preview — Data residency

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Si la résidence des données est activée pour Security Command Center, les configurations qui définissent les exportations continues vers Pub/Sub (ressources notificationConfig) sont soumises au contrôle de la résidence des données et sont stockées dans votre emplacement Security Command Center.

Pour exporter les résultats d'un emplacement Security Command Center vers Pub/Sub, vous devez configurer l'exportation continue dans le même emplacement Security Command Center que les résultats.

Étant donné que les filtres utilisés dans les exportations continues peuvent contenir des données soumises à des contrôles de résidence, assurez-vous de spécifier l'emplacement approprié avant de les créer. Security Command Center ne limite pas l'emplacement dans lequel vous créez des exportations.

Les exportations continues ne sont stockées que dans l'emplacement où elles sont créées et ne peuvent pas être consultées ni modifiées dans d'autres emplacements.

Une fois que vous avez créé une exportation continue, vous ne pouvez plus modifier son emplacement. Pour modifier l'emplacement, vous devez supprimer l'exportation continue et la recréer dans le nouvel emplacement.

Pour récupérer une exportation continue à l'aide d'appels d'API, vous devez spécifier l'emplacement dans le nom complet de la ressource de notificationConfig. Exemple :

GET https://securitycenter.googleapis.com/v2/organizations/123/locations/eu/notificationConfigs/my-pubsub-export-01

De même, pour récupérer une exportation continue à l'aide de gcloud CLI, vous devez spécifier l'emplacement à l'aide de l'option --location. Exemple :

gcloud scc notifications describe myContinuousExport --organization=123 \
    --location=us

Créer un objet NotificationConfig

Pour créer un objet NotificationConfig, vous devez avoir :

• Un sujet Pub/Sub existant auquel vous souhaitez envoyer des notifications
• Rôles IAM requis pour le principal qui crée le notificationConfig.

Pour en savoir plus, consultez l'étape Configurer un sujet Pub/Sub dans le guide Configurer des notifications de résultats.

Avant de créer un NotificationConfig, notez que chaque organisation peut avoir un nombre limité de fichiers NotificationConfig. Pour en savoir plus, consultez la page Quotas et limites.

L'objet NotificationConfig inclut un champ filter qui limite les notifications aux événements utiles. Ce champ accepte tous les filtres disponibles dans la méthode findings.list de l'API Security Command Center.

Lorsque vous créez un NotificationConfig, vous spécifiez un parent pour le NotificationConfig à partir de la hiérarchie des ressources Google Cloud, qu'il s'agisse d'une organisation, d'un dossier ou d'un projet. Si vous devez récupérer, mettre à jour ou supprimer l'NotificationConfig ultérieurement, vous devez inclure l'ID numérique de l'organisation, du dossier ou du projet parent lorsque vous y faites référence.

Dans la console Google Cloud, certaines ressources NotificationConfig peuvent afficher un libellé Ancienne, ce qui indique qu'elles ont été créées avec l'API Security Command Center v1. Vous pouvez gérer ces ressources NotificationConfig avec la console Google Cloud, la gcloud CLI, l'API Security Command Center v1 ou les bibliothèques clientes v1 pour Security Command Center.

Pour gérer ces ressources NotificationConfig avec la CLI gcloud, vous ne devez pas spécifier d'emplacement lorsque vous exécutez la commande gcloud CLI.

Pour créer l'NotificationConfig à l'aide du langage ou de la plate-forme de votre choix:

gcloud

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

Remplacez les éléments suivants :

• NOTIFICATION_NAME: nom de la notification. Il doit comporter entre 1 et 128 caractères, et ne peut contenir que des caractères alphanumériques, des traits de soulignement ou des traits d'union.
• PARENT: champ d'application dans la hiérarchie des ressources auquel la notification s'applique, organization, folder ou project.
• PARENT_ID: ID de l'organisation, du dossier ou du projet parent, au format organizations/123, folders/456 ou projects/789.
• LOCATION : si la résidence des données est activée, l'emplacement Security Command Center dans lequel créer un NotificationConfig. Si la résidence des données n'est pas activée, utilisez la valeur global.
• NOTIFICATION_DESCRIPTION: description de la notification (1 024 caractères maximum).
• PUBSUB_TOPIC: sujet Pub/Sub qui recevra les notifications. Son format est projects/PROJECT_ID/topics/TOPIC.
• FILTER: expression que vous définissez pour sélectionner les résultats à envoyer à Pub/Sub. Exemple : 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

Les notifications sont maintenant publiées sur le thème Pub/Sub que vous avez spécifié.

Pour publier des notifications, un compte de service de la forme [e-mail] est créé pour vous. Ce compte de service est créé lorsque vous créez votre premier objet NotificationConfig et se voit automatiquement attribuer le rôle securitycenter.notificationServiceAgent sur la stratégie IAM pour PUBSUB_TOPIC lors de la création de la configuration de notification. Ce rôle de compte de service est requis pour que les notifications fonctionnent.

Obtenir un objet NotificationConfig

Pour obtenir un objet NotificationConfig, vous devez disposer d'un rôle IAM qui inclut l'autorisation securitycenter.notification.get.

gcloud

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

Remplacez les éléments suivants :

• NOTIFICATION_NAME: nom de la configuration des notifications.
• PARENT_TYPE : niveau de la hiérarchie des ressources où la configuration est spécifiée. Utilisez organization, folder ou project.
• PARENT_ID: ID numérique de la ressource parente.
• LOCATION : si la résidence des données est activée, l'emplacement Security Command Center dans lequel obtenir NotificationConfig. Si la résidence des données n'est pas activée, utilisez la valeur global.

Mettre à jour un objet

Pour mettre à jour un objet NotificationConfig, vous devez disposer d'un rôle IAM qui inclut l'autorisation securitycenter.notification.update.

Lorsque vous effectuez une mise à jour à l'aide d'un masque de champ, seuls les champs que vous spécifiez sont mis à jour. Si vous n'utilisez pas de masque de champ, tous les champs modifiables de l'objet NotificationConfig sont remplacés par les nouvelles valeurs. Vous pouvez mettre à jour le sujet et la description Pub/Sub à l'aide d'un masque de champ.

Pour suivre cet exemple, vous devez être abonné au nouveau sujet et votre compte de service de notifications doit disposer de l'autorisation pubsub.topics.setIamPolicy sur le sujet.

Une fois que vous avez accordé les autorisations nécessaires, mettez à jour la description NotificationConfig et le sujet Pub/Sub et filtrez dans la langue de votre choix:

gcloud

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

Remplacez les éléments suivants :

• NOTIFICATION_NAME: nom de la configuration des notifications.
• PARENT_TYPE : niveau de la hiérarchie des ressources où la configuration est spécifiée. Utilisez organization, folder ou project.
• PARENT_ID: ID numérique de la ressource parente.
• LOCATION : si la résidence des données est activée, l'emplacement Security Command Center dans lequel mettre à jour NotificationConfig. Si la résidence des données n'est pas activée, utilisez la valeur global.
• NOTIFICATION_DESCRIPTION: description de la notification (1 024 caractères maximum).
• PUBSUB_TOPIC: sujet Pub/Sub qui recevra les notifications. Son format est projects/PROJECT_ID/topics/TOPIC.
• FILTER: expression que vous définissez pour sélectionner les résultats à envoyer à Pub/Sub. Exemple : state="ACTIVE".

Supprimer un objet NotificationConfig

Pour supprimer un objet NotificationConfig, vous devez disposer d'un rôle IAM qui inclut l'autorisation securitycenter.notification.delete.

Lorsque vous supprimez un objet NotificationConfig, le rôle securitycenter.notificationServiceAgent reste dans le sujet Pub/Sub. Si vous n'utilisez pas le thème Pub/Sub dans un autre objet NotificationConfig, supprimez le rôle du thème. Pour plus d'informations, consultez la section Contrôle des accès.

Supprimez un objet NotificationConfig en utilisant la langue de votre choix :

gcloud

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

Remplacez les éléments suivants :

• NOTIFICATION_NAME: nom de la configuration des notifications.
• PARENT_TYPE : niveau de la hiérarchie des ressources où la configuration est spécifiée. Utilisez organization, folder ou project.
• PARENT_ID: ID numérique de la ressource parente.
• LOCATION : si la résidence des données est activée, l'emplacement Security Command Center dans lequel supprimer le NotificationConfig. Si la résidence des données n'est pas activée, utilisez la valeur global.

Répertorier les objets NotificationConfig

Pour répertorier des objets NotificationConfigs, vous devez disposer d'un rôle IAM incluant l'autorisation securitycenter.notification.list.

Toutes les listes de l'API Security Command Center sont paginées. Chaque réponse renvoie une page de résultats et un jeton pour renvoyer la page suivante. La valeur pageSize par défaut est 10. Vous pouvez configurer la taille des pages sur un minimum de 1, et un maximum de 1 000.

Répertoriez les objets NotificationConfigs dans la langue de votre choix :

gcloud

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

Remplacez les éléments suivants :

• PARENT_TYPE : niveau de la hiérarchie des ressources où la configuration est spécifiée. Utilisez organizations, folders ou projects.
• PARENT_ID: ID numérique de la ressource parente.
• LOCATION : si la résidence des données est activée, l'emplacement Security Command Center dans lequel lister les ressources NotificationConfig. Si la résidence des données n'est pas activée, utilisez la valeur global.

Recevoir des notifications Pub/Sub

Cette section fournit un exemple de message de notification et des exemples qui montrent comment convertir un message Pub/Sub en un message NotificationMessage contenant un résultat.

Les notifications sont publiées dans Pub/Sub au format JSON. Voici un exemple de message de notification :

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

Convertissez un message Pub/Sub en un message NotificationMessage dans la langue de votre choix :

gcloud

gcloud CLI ne permet pas de convertir un message Pub/Sub en un message NotificationMessage. Vous pouvez utiliser gcloud CLI pour obtenir un NotificationMessage et imprimer le JSON directement dans votre 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

Remplacez les éléments suivants :

• PROJECT_ID par votre ID de projet
• SUBSCRIPTION_ID par votre ID d'abonnement

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
}

Étape suivante

• Découvrez le filtrage des notifications.