Utiliser des modules personnalisés avec Security Health Analytics

Cette page explique comment créer, afficher, mettre à jour et supprimer des modules personnalisés pour Security Health Analytics à l'aide de la console Google Cloud ou de Google Cloud CLI.

Pour en savoir plus, consultez la page Présentation des modules personnalisés pour l'analyse de l'état de sécurité.

Avant de commencer

Pour pouvoir utiliser des modules personnalisés, les prérequis suivants sont requis:

Vous devez disposer du niveau Premium de Security Command Center. Pour en savoir plus sur les niveaux de Security Command Center, consultez la page Présentation de l'activation de Security Command Center.
L'analyse de l'état de la sécurité doit être activée. Pour en savoir plus sur l'activation de Security Health Analytics, consultez Activer ou désactiver un service intégré.
Votre compte utilisateur doit disposer d'un ou de plusieurs rôles IAM (Identity and Access Management) contenant les autorisations requises. Pour en savoir plus, consultez la section Autorisations IAM requises.
Si vous avez l'intention d'écrire vos propres modules personnalisés et de les importer dans Security Command Center à l'aide de commandes gcloud, vous avez besoin de la Google Cloud CLI. Pour en savoir plus sur l'installation de la gcloud CLI, consultez la section Installer la gcloud CLI.
Si l'API Security Command Center n'est pas déjà activée, vous devez l'activer avant de pouvoir utiliser des modules personnalisés pour Security Health Analytics. Vous pouvez activer l'API Security Command Center sur la page Bibliothèque d'API de la console Google Cloud.
Pour comprendre les limites d'utilisation de Security Health Analytics, consultez la section Quotas de modules personnalisés.

Autorisations IAM requises

Pour utiliser des modules personnalisés, vous devez disposer des autorisations IAM (Identity and Access Management) suivantes:

Autorisation	Rôle
securitycenter.securityhealthanalyticscustommodules.create securitycenter.securityhealthanalyticscustommodules.update securitycenter.securityhealthanalyticscustommodules.delete	roles/securitycenter.settingsEditor roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.get securitycenter.securityhealthanalyticscustommodules.list	roles/securitycenter.settingsViewer roles/securitycenter.adminViewer roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.test	roles/securitycenter.securityHealthAnalyticsCustomModulesTester roles/securitycenter.adminViewer roles/securitycenter.adminEditor roles/securitycenter.admin

Pour en savoir plus sur les autorisations et les rôles IAM, et sur la manière de les attribuer, consultez la page Attribuer un rôle IAM à l'aide de la console Google Cloud.

Créer un module personnalisé

Cette section explique comment créer des modules personnalisés à l'aide de la console Google Cloud ou de gcloud CLI.

Pour tester votre module personnalisé en tant qu'étape du processus de création, vous devez préparer les définitions de ressources de test dans un fichier YAML. Pour obtenir des instructions, consultez la section Créer des ressources de test dans un fichier YAML.

Pour créer un module personnalisé, sélectionnez la méthode que vous souhaitez utiliser dans les onglets suivants:

console Google Cloud

Pour créer un module personnalisé dans la console Google Cloud, procédez comme suit:

Accédez à la page Paramètres de Security Command Center dans la console Google Cloud.

Accéder aux paramètres
Si vous y êtes invité, sélectionnez l'organisation, le dossier ou le projet dans lequel vous devez créer le module personnalisé.
Sur la fiche Analyse de l'état de sécurité, cliquez sur Gérer les paramètres.
Cliquez sur l'onglet Modules.
Cliquez sur Créer un module. La page Créer un module pour l'analyse de l'état de sécurité s'ouvre.
Dans le panneau Configure module (Configurer le module), définissez le nom à afficher, les ressources à analyser et la logique de détection:
1. Dans le champ Module name (Nom du module), spécifiez un nom pour le module. Le nom doit comporter entre 1 et 128 caractères, commencer par une lettre minuscule et ne contenir que des caractères alphanumériques et des traits de soulignement. Ce nom devient la catégorie de résultats générée par ce détecteur. Une fois le module créé, vous ne pouvez plus modifier son nom.
2. Sous Ajouter un type de ressource, spécifiez un à cinq types de ressources à analyser. Vous ne pouvez pas spécifier un type de ressource plusieurs fois.
  
  Pour obtenir la liste des types de ressources acceptés, consultez la page Types de ressources acceptés.
3. Dans l'éditeur d'expressions, écrivez des expressions CEL pour exécuter des vérifications booléennes sur une ou plusieurs propriétés de la ressource que vous avez spécifiées à la dernière étape. Pour déclencher un résultat, l'expression doit renvoyer TRUE. Par exemple, l'expression suivante déclenche un résultat si une période de rotation est définie pour une ressource CryptoKey et que celle-ci dure plus de 2 592 000 secondes (30 jours):
```
has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))
```
  Pour en savoir plus, consultez les ressources suivantes :
4. Cliquez sur Suivant. Le panneau Définir les détails du résultat s'ouvre.
Dans le panneau Définir les détails du résultat, décrivez le problème détecté par le module personnalisé, y compris sa gravité, son origine, la façon de le résoudre et toutes les données que vous souhaitez inclure dans les résultats en tant que propriétés sources personnalisées:
1. Dans le champ Gravité, spécifiez la gravité du problème. Vous pouvez spécifier Low, Medium, High ou Critical. Medium est la valeur par défaut.
  
  Pour en savoir plus sur les niveaux de gravité, consultez la section Classification des résultats en fonction du niveau de gravité.
2. Dans le champ Finding description (Description du résultat), décrivez le problème détecté par le module personnalisé. Cette explication apparaît dans chaque instance de résultat pour aider les équipes de sécurité à comprendre et à résoudre le problème détecté.
3. Dans le champ Trouver les étapes suivantes, expliquez les étapes que votre équipe de sécurité peut suivre pour résoudre le problème détecté.
  
  Les étapes s'affichent avec chaque instance de résultat. Incluez les étapes spécifiques que l'équipe de sécurité peut suivre pour résoudre le problème le plus rapidement possible.
4. Facultatif: Dans le champ Propriétés de résultat personnalisées, spécifiez jusqu'à 10 paires nom/valeur pour définir les propriétés sources personnalisées à renvoyer avec chaque instance de résultat. Les informations sont renvoyées en tant que propriétés sources dans le fichier JSON du résultat et sont affichées dans l'onglet Propriétés sources des détails du résultat dans la console Google Cloud. Spécifiez le texte ou les valeurs de propriété sous forme de paires clé/valeur:
  - Dans le champ Nom de la propriété, spécifiez un nom pour la propriété source personnalisée. Le nom doit respecter les règles suivantes :
    - Le nom doit commencer par une lettre minuscule.
    - Le nom ne doit contenir que des caractères alphanumériques ou des traits de soulignement.
    - Le nom doit comporter entre 1 et 128 caractères.
    - Chaque nom doit être unique parmi les autres propriétés sources.
  - Dans le champ Property value (Valeur de la propriété), spécifiez l'une des valeurs suivantes, ne dépassant pas 1 024 caractères :
    - Chaîne de texte délimitée par des guillemets. Les guillemets sont inclus dans la limite de 1 024 caractères. Par exemple, "This string provides additional useful information.".
    - Toute propriété de la ressource en cours d'analyse. Par exemple, si vous vérifiez la ressource CryptoKey, vous pouvez spécifier resource.rotationPeriod. La valeur de la propriété rotationPeriod est renvoyée.
5. Cliquez sur Suivant. Le panneau Activer le module s'ouvre.
Facultatif: Utilisez le menu déroulant du panneau Activer le module pour indiquer si le module personnalisé est activé ou désactivé lors de sa création. Par défaut, les modules personnalisés sont activés à la création. Si vous spécifiez Désactiver, vous pouvez activer le module ultérieurement dans l'onglet Modules de la page des paramètres de Security Health Analytics.
Cliquez sur Suivant. Le panneau Test module (Module de test) s'ouvre.
Facultatif: Avant de créer votre module personnalisé, nous vous recommandons de le tester.

Pour tester un module personnalisé, procédez comme suit:
1. Créez un fichier YAML contenant des définitions de ressources de test pour les ressources vérifiées par votre module personnalisé.
  
  Pour en savoir plus sur la création d'un fichier de données de test, consultez la section Créer des ressources de test dans un fichier YAML.
2. Sous Importer le fichier YAML, cliquez sur Parcourir pour importer le fichier YAML contenant les définitions de ressources de test. Le test démarre automatiquement lorsque le fichier est importé.
3. Sous Aperçu des résultats des tests, vérifiez les résultats.
  - Si votre fichier YAML comporte des erreurs de syntaxe ou d'autres erreurs, un message d'erreur flottant s'affiche en bas de la page du navigateur.
  - Si le test réussit, il renvoie les informations suivantes:
    - Nom à afficher du module personnalisé.
    - Nom arbitraire que vous avez spécifié dans la propriété resource du fichier de données de test.
    - Organisation, dossier ou projet dans lequel le module personnalisé a été ou sera créé.
Les résultats des tests ne sont ni stockés, ni écrits dans Security Command Center.

Pour en savoir plus, consultez la section Tester des modules personnalisés.
Cliquez sur Créer. Vous êtes redirigé vers la page Modules. Le module que vous avez créé doit s'afficher avec l'état Enabled (Activé).

Les nouveaux modules personnalisés ne sont pas immédiatement disponibles pour que Security Health Analytics puisse les utiliser dans les analyses. Pour en savoir plus, consultez la section Latence de détection.

gcloud CLI

Pour créer un module personnalisé à l'aide des commandes gcloud, vous devez d'abord coder la définition du module personnalisé dans un fichier YAML incluant des expressions CEL pour la logique de détection et les propriétés de sortie.

Une fois la définition terminée, vous devez l'importer dans Security Command Center à l'aide des commandes de gcloud CLI.

Codez une définition de module personnalisé dans un fichier YAML selon les instructions de la section Coder un module personnalisé pour l'analyse de l'état de sécurité.
Enregistrez le fichier YAML dans un emplacement accessible à votre instance de gcloud CLI.
Importez la définition personnalisée dans Security Command Center:
```
gcloud scc custom-modules sha create \
    PARENT_FLAG=PARENT_ID \
    --display-name="MODULE_DISPLAY_NAME" \
    --enablement-state="ENABLEMENT_STATE" \
    --custom-config-from-file=MODULE_FILE_NAME.yaml
```
Remplacez les éléments suivants :
- PARENT_FLAG: niveau auquel vous créez le module personnalisé (--organization, --folder ou --project).
- PARENT_ID: ID de l'organisation, du dossier ou du projet dans lequel vous créez le module personnalisé.
- ENABLEMENT_STATE: enabled ou disabled.
- MODULE_DISPLAY_NAME: nom de la catégorie de résultats que vous souhaitez afficher lorsque le module personnalisé renvoie un résultat. Le nom doit comporter entre 1 et 128 caractères, commencer par une lettre minuscule et ne contenir que des caractères alphanumériques et des traits de soulignement.
- MODULE_FILE_NAME: chemin d'accès et nom du fichier YAML contenant la définition du module personnalisé.

Latence de détection

Après avoir créé ou mis à jour la définition d'un module personnalisé, il peut s'écouler plusieurs heures avant que le module personnalisé nouveau ou mis à jour ne soit disponible pour les analyses.

La création ou la modification d'un module personnalisé ne déclenche pas d'analyse. Une fois qu'un module personnalisé est disponible, Security Health Analytics ne commence à l'utiliser que lorsque la première analyse par lot ou qu'une modification de la configuration de la ressource cible déclenche une analyse en temps réel.

Pour en savoir plus sur les types d'analyses Security Health Analytics, consultez Types d'analyses Security Health Analytics.

Mettre à jour un module personnalisé

Vous pouvez mettre à jour la plupart des propriétés des modules personnalisés de Security Health Analytics.

Les propriétés suivantes d'un module personnalisé ne peuvent pas être modifiées:

Nom à afficher.
ID du module personnalisé.
Nom complet de la ressource du module personnalisé.

Lorsque vous mettez à jour un module personnalisé, les résultats qu'il a émis précédemment ne sont pas mis à jour en même temps. Si les modifications apportées au module entraînent des modifications des résultats émis, ceux-ci ne refléteront les modifications qu'après la prochaine analyse par lot ou en temps réel de Security Health Analytics.

Pour modifier un module personnalisé, vous pouvez utiliser la console Google Cloud ou gcloud CLI. Cliquez sur l'un des onglets suivants pour obtenir des instructions.

console Google Cloud

Pour mettre à jour un module personnalisé existant dans la console Google Cloud, procédez comme suit:

Accédez à la page Paramètres de Security Command Center dans la console Google Cloud.

Accéder aux paramètres
Dans le sélecteur de projet, sélectionnez l'organisation, le dossier ou le projet dans lequel le module personnalisé a été créé. Vous ne pouvez modifier un module personnalisé nulle part ailleurs.
Sur la fiche Analyse de l'état de sécurité, cliquez sur Gérer les paramètres.
Sélectionnez l'onglet Modules. Tous les modules de détection de Security Health Analytics s'affichent.
Utilisez le champ de filtre en haut de la liste des modules ou faites défiler la page pour trouver le module personnalisé que vous devez modifier.
À droite de la ligne de votre module personnalisé, cliquez sur l'icône Menu d'actions .
Dans le menu d'actions, cliquez sur l'icône Modifier (). La page Afficher le module s'ouvre et affiche l'onglet Configurer le module.
Modifiez les champs de module personnalisé de chaque onglet sur la page View module (Afficher le module) selon vos besoins.
Facultatif: Avant d'enregistrer vos mises à jour, nous vous recommandons de les tester.

Pour tester un module personnalisé, procédez comme suit:
1. Créez un fichier YAML contenant des définitions de ressources de test pour les ressources vérifiées par votre module personnalisé.
  
  Pour en savoir plus sur la création d'un fichier de données de test, consultez la section Créer des ressources de test dans un fichier YAML.
2. Sous Importer le fichier YAML, cliquez sur Parcourir pour importer le fichier YAML contenant les définitions de ressources de test. Le test démarre automatiquement lorsque le fichier est importé.
3. Sous Aperçu des résultats des tests, vérifiez les résultats.
  - Si votre fichier YAML comporte des erreurs de syntaxe ou d'autres erreurs, un message d'erreur flottant s'affiche en bas de la page du navigateur.
  - Si le test réussit, il renvoie les informations suivantes:
    - Nom à afficher du module personnalisé.
    - Nom arbitraire que vous avez spécifié dans la propriété resource du fichier de données de test.
    - Organisation, dossier ou projet dans lequel le module personnalisé a été ou sera créé.
Les résultats des tests ne sont ni stockés, ni écrits dans Security Command Center.

Pour en savoir plus, consultez la section Tester des modules personnalisés.
Cliquez sur Enregistrer au bas de la page. Vos modifications sont appliquées au module personnalisé.

gcloud CLI

Pour mettre à jour un module personnalisé à l'aide de la gcloud CLI, vous devez d'abord modifier la définition YAML de ce module personnalisé, puis utiliser les commandes gcloud pour mettre à jour le module personnalisé dans Security Health Analytics.

Modifiez la définition du module personnalisé. Pour en savoir plus sur le codage de la définition d'un module personnalisé, consultez la section Coder un module personnalisé pour l'analyse de l'état de sécurité.
Enregistrez le fichier YAML modifié dans un emplacement accessible à la gcloud CLI.
Mettez à jour le module personnalisé dans Security Health Analytics en exécutant la commande suivante:
```
gcloud scc custom-modules sha update MODULE_ID \
   PARENT_FLAG=PARENT_ID \
   --enablement-state="ENABLED" \
   --custom-config-from-file=MODULE_FILE_NAME.yaml
```
Remplacez les éléments suivants :
- MODULE_ID: ID ou nom de ressource complet du module personnalisé.
- PARENT_FLAG: niveau auquel le module personnalisé a été créé (--organization, --folder ou --project).
- PARENT_ID: ID de l'organisation, du dossier ou du projet dans lequel le module personnalisé a été créé.
- MODULE_FILE_NAME: chemin d'accès et nom du fichier YAML contenant la définition du module personnalisé.

Afficher un module personnalisé

Sélectionnez un onglet pour savoir comment afficher la définition d'un module personnalisé.

console Google Cloud

Pour afficher les modules personnalisés dans la console Google Cloud, procédez comme suit:

Accédez à la page Analyse de l'état de sécurité dans les paramètres de Security Command Center.

Accéder aux paramètres
Cliquez sur l'onglet Modules. Le panneau Modules s'ouvre.
Si nécessaire, utilisez le champ de filtre en haut de la liste des modules pour rechercher le module personnalisé à modifier.
Pour afficher les détails de la définition du module personnalisé, cliquez sur l'icône Menu d'actions , à droite de la ligne du module personnalisé.
Dans le menu d'actions, cliquez sur l'icône Modifier . La page View module (Afficher le module) s'ouvre et affiche l'onglet Configure module (Configurer le module).
Cliquez sur les onglets de la page View module (Module d'affichage) pour afficher tous les champs de la définition du module personnalisé.

gcloud CLI

Pour afficher les détails d'un module personnalisé, saisissez la commande suivante:

gcloud scc custom-modules sha get MODULE_ID \
      PARENT_FLAG=PARENT_ID

Remplacez les éléments suivants :

MODULE_ID: ID ou nom de ressource complet du module personnalisé.
PARENT_FLAG: niveau auquel le module personnalisé a été créé (--organization, --folder ou --project).
PARENT_ID: ID de l'organisation, du dossier ou du projet dans lequel le module personnalisé a été créé.

Lister les modules personnalisés

Sélectionnez un onglet pour savoir comment afficher une liste de modules personnalisés.

console Google Cloud

Accédez à la page Analyse de l'état de sécurité dans les paramètres de Security Command Center.

Accéder aux paramètres
Cliquez sur l'onglet Modules. Le panneau Modules s'ouvre.
Cliquez dans le champ de filtre en haut de la liste des modules pour afficher la liste des types de filtres.
Sélectionnez Type et saisissez Custom. La liste des modules est mise à jour pour n'afficher que les modules personnalisés.

gcloud CLI

Pour afficher la liste des modules personnalisés, saisissez la commande suivante:

gcloud scc custom-modules sha list \
    PARENT_FLAG=PARENT_ID

Remplacez les éléments suivants :

PARENT_FLAG: niveau auquel le module personnalisé a été créé (--organization, --folder ou --project).
PARENT_ID: ID de l'organisation, du dossier ou du projet dans lequel le module personnalisé a été créé.

Supprimer un module personnalisé

Vous pouvez supprimer un module personnalisé de l'organisation, du dossier ou du projet dans lequel il a été créé, ou d'une organisation ou d'un dossier parent. Vous ne pouvez pas supprimer un module personnalisé d'un dossier ou d'un projet qui en hérite.

Pour savoir comment supprimer un module personnalisé, sélectionnez l'un des onglets suivants.

console Google Cloud

Accédez à la page Paramètres de Security Command Center dans la console Google Cloud.

Accéder aux paramètres
Si vous y êtes invité, sélectionnez votre organisation, votre dossier ou votre projet.
Sur la fiche Analyse de l'état de sécurité, cliquez sur Gérer les paramètres.
Sélectionnez l'onglet Modules. Tous les modules de détection de Security Health Analytics s'affichent.
Utilisez le champ de filtre en haut de la liste des modules ou faites défiler la page pour trouver le module personnalisé que vous devez modifier.
À droite de la ligne de votre module personnalisé, cliquez sur l'icône Menu d'actions .
Dans le menu d'actions, cliquez sur Supprimer. La boîte de dialogue Supprimer le module personnalisé s'ouvre.
Dans la boîte de dialogue, cliquez sur Supprimer.

gcloud CLI

Pour supprimer un module personnalisé, saisissez la commande suivante:

gcloud scc custom-modules sha delete MODULE_ID \
    PARENT_FLAG=PARENT_ID

Remplacez les éléments suivants :

MODULE_ID: ID ou nom de ressource complet du module personnalisé.
PARENT_FLAG: niveau auquel le module personnalisé a été créé (--organization, --folder ou --project).
PARENT_ID: ID de l'organisation, du dossier ou du projet dans lequel le module personnalisé a été créé.

Les résultats des modules personnalisés supprimés sont marqués comme inactifs par Security Health Analytics dans la prochaine analyse par lot.

Examiner les résultats

Vous pouvez afficher les résultats générés par les modules personnalisés dans la console Google Cloud ou dans l'API Security Command Center.

console Google Cloud

Vous pouvez afficher les résultats générés par vos modules personnalisés avec les autres résultats de Security Command Center dans la console Google Cloud.

Pour afficher les résultats, procédez comme suit:

Accédez à la page Résultats de la console Google Cloud.

Accéder
Si vous y êtes invité, sélectionnez votre organisation.
Dans le panneau Filtres rapides, faites défiler la page vers le bas jusqu'à la section Nom à afficher de la source, puis cliquez sur Personnalisé de l'analyse de l'état de sécurité. Le panneau Résultats de la requête de résultats est actualisé pour n'afficher que les résultats des modules personnalisés de Security Health Analytics.

Si vous ne voyez pas l'option Security Health Analytics Custom (Analyse de l'état de sécurité personnalisée), aucun module personnalisé n'a renvoyé de résultat.
Pour afficher les détails d'un résultat spécifique, dans la colonne Category (Catégorie) du panneau Findings query results (Résultats de la requête de résultats), cliquez sur le nom de la catégorie du résultat. Le panneau des détails du résultat se développe pour afficher un résumé des détails du résultat.
Si des propriétés sources personnalisées ont été définies pour le module personnalisé, vous pouvez les afficher en cliquant sur l'onglet Propriétés sources.
Pour afficher la définition JSON complète du résultat, cliquez sur l'onglet JSON.

gcloud CLI

Pour afficher les résultats, procédez comme suit:

Ouvrez une fenêtre de terminal.

Pour obtenir l'ID source de Security Health Analytics, exécutez la commande suivante:

gcloud scc sources describe organizations/ORGANIZATION_ID \
--source-display-name='Security Health Analytics Custom'

La sortie affichée doit ressembler à la suivante. Dans l'exemple, SOURCE_ID est un ID attribué par le serveur pour les sources de sécurité.

description: ...
displayName: Security Health Analytics Custom
name: organizations/ORGANIZATION_ID/sources/SOURCE_ID

Pour lister tous les résultats générés par vos modules personnalisés, exécutez la commande suivante :
```
gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID
```

Pour lister les résultats d'un module personnalisé spécifique, exécutez la commande suivante :

gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID --filter="category=\"MODULE_NAME\""

Étapes suivantes

Vous pouvez gérer les résultats générés par des modules personnalisés, comme tous les résultats, dans Security Command Center. Pour obtenir des instructions, consultez les informations suivantes: