Activer les notifications par e-mail et de chat en temps réel

SendGrid Email

Pour activer les notifications par e-mail, procédez comme suit :

• Créez un compte API SendGrid Email et obtenez une clé API.
• Créez et déployez une fonction Cloud Run qui envoie des e-mails lorsque des notifications sont reçues en provenance de Pub/Sub.

Créer un compte API SendGrid Email

Dans cette section, vous allez créer un compte API SendGrid Email et obtenir une clé API. Si SendGrid est déjà activé, passez à la section Obtenir une clé API Sendgrid Email et assurez-vous que votre clé API existante dispose des autorisations appropriées.

1. Accédez à Google Cloud Console.
   Accéder à Google Cloud Console
   
2. Dans le champ de recherche situé en haut de la page, recherchez API SendGrid Email.

3. Sur la page suivante, sélectionnez le forfait adapté à vos besoins.

   • Le forfait gratuit permet d'envoyer jusqu'à 12 000 e-mails par mois et suffit pour ce guide, mais les grandes entreprises peuvent en nécessiter davantage. Si vous prévoyez un volume plus important de notifications par e-mail, pensez à ajouter des filtres supplémentaires aux notifications pour exclure les résultats non pertinents.
   • Vous serez peut-être invité à sélectionner un projet à associer à SendGrid. Sélectionnez un projet pour continuer. Vous devrez peut-être disposer des autorisations nécessaires pour gérer les achats du compte de facturation associé au projet.

4. Consultez les conditions d'utilisation et, si vous les acceptez, cliquez sur S'abonner.

5. Activez le service SendGrid en cliquant sur Register with SendGrid (Enregistrer auprès de SendGrid).

6. Sur l'écran d'inscription, saisissez un nom d'utilisateur, un mot de passe et une adresse e-mail. Acceptez les conditions d'utilisation, puis cliquez sur Continuer.

7. Dans la boîte de dialogue de confirmation, cliquez sur Return to Google (Retourner sur Google).

Obtenir une clé API SendGrid Email

1. Cliquez sur Gérer les clés API sur le site Web de SendGrid. Un nouvel onglet affiche le site Web de SendGrid.

2. Remplissez le formulaire ou connectez-vous, si vous y êtes invité. Cliquez ensuite sur Premiers pas.

3. Dans le panneau du menu, développez Paramètres, puis cliquez sur Clés API.

4. Sur l'écran suivant, cliquez sur le bouton Créer une clé API.

5. Sous Nom de la clé API, saisissez Notifications par e-mail SCC, sélectionnez Accès complet, puis cliquez sur le bouton Créer et afficher.
   
   

6. La clé API s'affiche. Notez sa valeur. Vous en aurez besoin dans la section suivante.

7. Cliquez sur OK. L'ensemble actuel de clés API s'affiche. Fermez l'onglet, puis revenez dans la console Google Cloud.

Vous allez ensuite déployer une fonction Cloud Run pour envoyer des notifications à une adresse e-mail.

Créer la fonction Cloud Run SendGrid

Dans cette section, vous allez déployer une fonction qui envoie des notifications à votre compte de messagerie.

1. Accédez aux fonctions Cloud Run.
   Accéder aux fonctions Cloud Run
   

2. Assurez-vous d'utiliser le même PROJECT_ID que celui utilisé pour créer le sujet Pub/Sub.

3. Cliquez sur Créer une fonction.

4. Définissez le nom de la fonction sur send-high-and-critical-finding-email-notification et le type de déclencheur sur Pub/Sub.

5. Sélectionnez le sujet Pub/Sub que vous avez créé dans la section Configurer un sujet Pub/Sub.

6. Cliquez sur Save (Enregistrer), puis sur Next (Suivant).

7. Sur la page suivante, définissez l'environnement d'exécution sur Python 3.8. L'exemple de code de cette section est écrit en Python, mais vous pouvez utiliser n'importe quel langage compatible avec les fonctions Cloud Run.

8. Dans la liste des fichiers, cliquez sur requirements.txt et ajoutez ce qui suit dans la zone de texte : sendgrid.
   
   

9. Cliquez sur main.py et remplacez le contenu par l'extrait de code suivant.

   import base64
   import json
   from sendgrid import SendGridAPIClient
   from sendgrid.helpers.mail import Mail
   
   def send_email_notification(event, context):
       """Triggered from a message on a Pub/Sub topic.
       Args:
            event (dict): Event payload.
            context (google.cloud.functions.Context): Metadata for the event.
       """
       pubsub_message = base64.b64decode(event['data']).decode('utf-8')
       message_json = json.loads(pubsub_message)
       message = Mail(
           from_email='noreply@yourdomain.com',
           to_emails='$EMAIL_ADDRESS',
           subject='New High or Critical Severity Finding Detected',
           html_content='A new high or critical severity finding was
           detected: ' + ''.join(message_json['finding']['category']))
       try:
           sg = SendGridAPIClient('$SENDGRID_EMAIL_API_KEY')
           response = sg.send(message)
           print(response.status_code)
           print(response.body)
           print(response.headers)
       except Exception as e:
           print(e)
   
       print(pubsub_message)
   

10. Remplacez les éléments suivants :

    • Remplacez noreply@yourdomain.com par l'adresse e-mail de provenance souhaitée.
    • Remplacez $EMAIL_ADDRESS par l'adresse e-mail de destination souhaitée. Remarque : Cette variable peut contenir un tableau d'adresses e-mail (['user1@yourdomain.com', 'user2@yourdomain.com']) ou vous pouvez écrire du code personnalisé pour définir une variable dynamique sur, par exemple, une liste alternée des personnes de garde.
    • Remplacez $SENDGRID_EMAIL_API_KEY par la clé API que vous possédez déjà ou par celle que vous avez créée dans la section précédente.

11. Accédez au champ Point d'entrée et saisissez le nom de la fonction dans l'extrait de code (send_email_notification, dans cet exemple).

12. Cliquez sur Déployer. Vous êtes redirigé vers la liste des fonctions Cloud Run dans laquelle vous devriez voir votre nouvelle fonction. Lorsqu'une coche verte s'affiche à côté du nom de la fonction, cela signifie qu'elle a bien été déployée. Le processus peut prendre quelques minutes.

Slack

Pour envoyer des notifications à un canal Slack, procédez comme suit :

• Créez une application Slack disposant de droits suffisants pour publier des messages sur un canal Slack public.
• Créez et déployez une fonction Cloud Run qui publie des messages de chat sur Slack lorsque des notifications proviennent de Pub/Sub.

Créer une application Slack

Dans cette section, vous allez créer une application Slack pour recevoir des notifications.

1. Accédez à la liste des applications de l'API Slack. La page s'ouvre dans un autre onglet.

2. Se connecter ou créer un compte.

3. Sélectionnez Créer une application.

4. Définissez le nom de l'application sur SCC Finding Notifier.

5. Sélectionnez l'espace de travail Slack de développement dans lequel vous souhaitez que le bot Slack publie des messages, puis cliquez sur Créer une application.

6. Dans le panneau de navigation, sélectionnez OAuth et autorisations.
   
   

7. Accédez à la section Champs d'application. Les champs d'application appartiennent à deux catégories :

   • Champs d'application des jetons de bot
   • Champs d'application des jetons d'utilisateur

8. Dans cet exercice, vous n'avez pas besoin d'ajouter un champ d'application de jeton d'utilisateur. Sous "Champs d'application des jetons de bot", cliquez sur Ajouter un champ d'application OAuth et saisissez les informations suivantes :

   • chat:write
   • chat:write.public
     
     

9. Faites défiler la page OAuth et autorisations jusqu'en haut, puis cliquez sur Installer l'application dans l'espace de travail.

10. Dans la boîte de dialogue de confirmation, cliquez sur Autoriser.

11. Copiez le jeton d'accès OAuth de l'utilisateur bot pour l'utiliser dans Cloud Functions.

Vous allez ensuite déployer une fonction Cloud Run pour envoyer des notifications à un groupe Slack.

Créer la fonction Cloud Run Slack

Dans cette section, vous allez déployer une fonction permettant d'envoyer des notifications à votre compte Slack.

1. Accédez aux fonctions Cloud Run.
   Accéder aux fonctions Cloud Run
   

2. Vérifiez que vous utilisez le même PROJECT_ID que celui dans lequel le sujet Pub/Sub a été créé.

3. Cliquez sur Créer une fonction.

4. Définissez le nom de la fonction sur slack-chat-high-and-critical-findings et le type de déclencheur sur Pub/Sub.

5. Sélectionnez le sujet Pub/Sub que vous avez créé dans la section Configurer un sujet Pub/Sub.

6. Cliquez sur Save (Enregistrer), puis sur Next (Suivant).

7. Sur la page suivante, définissez l'environnement d'exécution sur Python 3.8. L'exemple de code de cette section est écrit en Python, mais vous pouvez utiliser n'importe quel langage compatible avec les fonctions Cloud Run.

8. Accédez à la liste des fichiers. Cliquez sur requirements.txt et ajoutez l'élément suivant : requests.

9. Cliquez sur main.py et remplacez son contenu par l'extrait de code suivant.

   import base64
   import json
   import requests
   
   TOKEN = "BOT_ACCESS_TOKEN"
   
   def send_slack_chat_notification(event, context):
       pubsub_message = base64.b64decode(event['data']).decode('utf-8')
       message_json = json.loads(pubsub_message)
       finding = message_json['finding']
   
       requests.post("https://slack.com/api/chat.postMessage", data={
           "token": TOKEN,
           "channel": "#general",
           "text": f"A high severity finding {finding['category']} was detected!"
       })
   

10. Remplacez BOT_ACCESS_TOKEN par le jeton d'accès OAuth de l'utilisateur bot que vous avez créé avec l'application Slack.

11. Accédez au champ Point d'entrée et saisissez le nom de la fonction dans l'extrait de code (send_slack_chat_notification, dans cet exemple).

12. Cliquez sur Déployer. Vous êtes redirigé vers la liste des fonctions Cloud Run dans laquelle vous devriez voir votre nouvelle fonction. Lorsqu'une coche verte s'affiche à côté du nom de la fonction, cela signifie qu'elle a bien été déployée. Le processus peut prendre quelques minutes. Les messages s'affichent dans le canal Slack #general.

WebEx

Pour envoyer des notifications à votre compte WebEx Teams, procédez comme suit :

• Créez un compte de service autorisé à récupérer des éléments depuis Security Command Center.
• Créez un bot WebEx doté des droits suffisants pour publier des messages sur votre espace de travail.
• Créer et déployer une fonction Cloud Run qui s'abonne à Pub/Sub et publie des messages de chat sur WebEx lorsque des notifications sont reçues en provenance du sujet Pub/Sub.

Créer un compte de service

Par défaut, les fonctions Cloud Run ne peuvent pas récupérer les éléments de Security Command Center. Dans cette section, vous provisionnez un compte de service permettant aux fonctions Cloud Run de récupérer les éléments associés aux résultats.

1. Nommez votre compte de service et spécifiez-le en tant que variable d'environnement.

   export SERVICE_ACCOUNT=ACCOUNT_NAME
   

2. Créez le compte de service pour votre projet.

   gcloud iam service-accounts create $SERVICE_ACCOUNT \
    --display-name "Service Account for SCC Finding Notifier WebEx Cloud Function" \
    --project $PROJECT_ID
   

3. Accordez au compte de service le rôle securitycenter.assetsViewer au niveau de l'organisation.

    gcloud organizations add-iam-policy-binding $ORG_ID \
      --member="serviceAccount:$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com" \
      --role='roles/securitycenter.assetsViewer'
   

Créer un bot WebEx

Dans cette section, vous allez créer un bot WebEx qui publie des messages sur votre espace de travail.

1. Connectez-vous à votre compte WebEx Teams, puis accédez à la page Nouveau bot.

2. Définissez Nom du bot sur SCC Finding Notifier.

3. Sélectionnez un nom d'utilisateur bot descriptif, mais unique (your-name-scc-finding-notifier-demo).

4. Sous Icône, sélectionnez Valeur par défaut 1.

5. Définissez la description sur "Un bot qui avertit l'équipe lorsqu'un nouveau résultat de gravité élevée ou critique est publié sur Security Command Center".

6. Cliquez sur Ajouter le bot.

7. Sur la page de confirmation, copiez le jeton d'accès du bot et enregistrez-le pour l'utiliser dans la fonction Cloud Run.

Ajouter le bot WebEx à l'espace de travail

Dans cette section, vous allez ajouter le bot WebEx à un espace de travail.

1. Sur l'espace WebEx où vous souhaitez que le bot publie des notifications, développez le panneau d'activité.

2. Sélectionnez Ajouter des contacts.

3. Saisissez SCC Finding Notifier dans le champ de texte, puis sélectionnez le bot que vous avez créé dans le menu déroulant.

4. Cliquez sur le bouton Ajouter, puis fermez le panneau.

5. Obtenez l'ID de salle de l'espace de travail de la fonction Cloud Run. Sur un ordinateur de bureau, accédez à https://developer.webex.com/docs/api/v1/rooms/list-rooms et connectez-vous si nécessaire. Cette page utilise l'API WebEx pour répertorier les salles auxquelles vous appartenez.

6. Accédez au panneau de recherche.

7. Sélectionnez l'onglet Essayer en haut du panneau.

8. Conservez toutes les valeurs par défaut de toutes les options, puis cliquez sur Exécuter.

9. Dans l'onglet Réponse, vous recevez une réponse au format JSON contenant une liste de items ou de salles. Recherchez le nom (title) de la salle dans laquelle vous souhaitez afficher les notifications, puis enregistrez la valeur id associée.

Vous allez ensuite déployer une fonction Cloud Run pour envoyer des notifications à votre espace de travail WebEx.

Créer la fonction Cloud Run WebEx

Dans cette section, vous allez déployer une fonction permettant d'envoyer des notifications à votre compte WebEx.

1. Accédez aux fonctions Cloud Run.
   Accéder aux fonctions Cloud Run
   

2. Sélectionnez le PROJECT_ID dans lequel le sujet Pub/Sub a été créé.

3. Cliquez sur Créer une fonction.

4. Définissez le nom de la fonction sur webex-teams-high-and-critical-findings et le type de déclencheur sur Pub/Sub.

5. Sélectionnez le sujet Pub/Sub que vous avez créé dans la section Configurer un sujet Pub/Sub.

6. Développez le champ Variables, mise en réseau et paramètres avancés.

7. Sous Compte de service, filtrez et sélectionnez le compte de service webex-cloud-function-sa que vous avez créé.

8. Cliquez sur Save (Enregistrer), puis sur Next (Suivant).

9. Sur la page suivante, définissez l'environnement d'exécution sur Python 3.8. L'exemple de code de cette section est écrit en Python, mais vous pouvez utiliser n'importe quel langage compatible avec les fonctions Cloud Run.

10. Accédez à la liste des fichiers. Cliquez sur requirements.txt et ajoutez l'élément suivant :

    • requests==2.25.1
    • google-cloud-securitycenter==1.1.0

11. Cliquez sur main.py et remplacez le contenu par l'extrait de code suivant.

    #!/usr/bin/env python3
    import base64
    import json
    
    import requests
    from google.cloud import securitycenter_v1
    
    WEBEX_TOKEN = "WEBEX_TOKEN"
    ROOM_ID = "ROOM_ID"
    
    TEMPLATE = """
    **Severity:** {severity}\n
    **Asset:** {asset}\n
    **SCC Category:** {category}\n
    **Project:** {project}\n
    **First observed:** {create_time}\n
    **Last observed:** {event_time}\n
    **Link to finding:** {finding_link}
    """
    
    PREFIX = "https://console.cloud.google.com/security/command-center/findings"
    
    def get_finding_detail_page_link(finding_name):
        """Constructs a direct link to the finding detail page."""
        org_id = finding_name.split("/")[1]
        return f"{PREFIX}?organizationId={org_id}&resourceId={finding_name}"
    
    def get_asset(parent, resource_name):
        """Retrieves the asset corresponding to `resource_name` from SCC."""
        client = securitycenter_v1.SecurityCenterClient()
        resp = client.list_assets(
            securitycenter_v1.ListAssetsRequest(
                parent=parent,
                filter=f'securityCenterProperties.resourceName="{resource_name}"',
            )
        )
        page = next(resp.pages)
        if page.total_size == 0:
            return None
        asset = page.list_assets_results[0].asset
        return json.loads(securitycenter_v1.Asset.to_json(asset))
    
    def send_webex_teams_notification(event, context):
        """Send the notification to WebEx Teams."""
        pubsub_message = base64.b64decode(event["data"]).decode("utf-8")
        message_json = json.loads(pubsub_message)
        finding = message_json["finding"]
    
        parent = "/".join(finding["parent"].split("/")[0:2])
        asset = get_asset(parent, finding["resourceName"])
    
        requests.post(
            "https://webexapis.com/v1/messages",
            json={
                "roomId": ROOM_ID,
                "markdown": TEMPLATE.format(
                    severity=finding["severity"],
                    asset=asset["securityCenterProperties"]["resourceDisplayName"],
                    category=finding["category"],
                    project=asset["resourceProperties"]["project"],
                    create_time=finding["createTime"],
                    event_time=finding["eventTime"],
                    finding_link=get_finding_detail_page_link(finding["name"]),
                ),
            },
            headers={"Authorization": f"Bearer {WEBEX_TOKEN}"},
        )
    

12. Remplacez les éléments suivants :

    • WEBEX_TOKEN par le jeton d'accès du bot de la section Créer un bot WebEx.
    • ROOM_ID par l'ID de salle de la section Ajouter le bot WebEx à l'espace de travail.

13. Accédez au champ Point d'entrée et saisissez le nom de la fonction dans l'extrait de code (send_webex_teams_notification, dans cet exemple).

14. Cliquez sur Déployer. Vous êtes redirigé vers la liste des fonctions Cloud Run dans laquelle vous devriez voir votre nouvelle fonction. Lorsqu'une coche verte s'affiche à côté du nom de la fonction, cela signifie qu'elle a bien été déployée. Le processus peut prendre quelques minutes.