Utiliser des modules personnalisés avec Security Health Analytics

Console Google Cloud

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

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

   Accéder aux paramètres

2. Si vous y êtes invité, sélectionnez l'organisation, le dossier ou le projet dans lequel vous devez créer le module personnalisé.

3. Sur la fiche Security Health Analytics, cliquez sur Gérer les paramètres.

4. Cliquez sur l'onglet Modules.

5. Cliquez sur add_box Créer un module. La page Créer un module pour Security Health Analytics s'ouvre.

6. Dans le panneau Configurer le module, définissez le nom à afficher, les ressources à analyser et la logique de détection :

   1. Dans le champ 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 des résultats produits 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 compatibles, 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ée à la dernière étape. Pour déclencher un résultat, l'expression doit être résolue sur TRUE. Par exemple, l'expression suivante déclenche un résultat si une ressource CryptoKey a une période de rotation définie et que cette période est supérieure à 2 592 000 secondes (30 jours) :

      has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))
      

      Pour en savoir plus, consultez les ressources suivantes :

      • Écrire des expressions CEL
      • Référencer les propriétés des ressources et des règles dans les modules personnalisés
      • Liste des définitions CEL standards

   4. Cliquez sur Suivant. Le panneau Définir les détails du résultat s'ouvre.

7. 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é, sa nature, 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 Classements des résultats par niveau de gravité.

   2. Dans le champ Description du problème, expliquez 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 Étapes suivantes, expliquez les étapes que votre équipe de sécurité peut suivre pour résoudre ou traiter le problème détecté.

      Les étapes s'affichent avec chaque instance de résultat. Indiquez 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 des propriétés de source personnalisées à renvoyer avec chaque instance de résultat. Les informations sont renvoyées sous forme de propriétés sources dans le JSON du résultat et sont affichées dans l'onglet Propriétés sources des détails du résultat dans la consoleGoogle Cloud . Spécifiez les valeurs de texte ou 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é de 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 Valeur de la propriété, spécifiez l'une des valeurs suivantes (1 024 caractères maximum) :
        • Chaîne de texte entre 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 analysée. 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.

8. 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 lors de leur création. Si vous spécifiez Disable (Désactiver), vous pourrez activer le module ultérieurement dans l'onglet Modules de la page des paramètres de Security Health Analytics.

9. Cliquez sur Suivant. Le panneau Module de test s'ouvre.

10. 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 les définitions des ressources de test pour les ressources que votre module personnalisé vérifie.

       Pour savoir comment créer un fichier de données de test, consultez 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 des ressources de test. Le test démarre automatiquement lorsque le fichier est importé.

    3. Sous Aperçu des résultats de test, vérifiez les résultats.

       • Si votre fichier YAML contient 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 pas stockés ni écrits dans Security Command Center.

    Pour en savoir plus, consultez Tester les modules personnalisés.

11. Cliquez sur Créer. Vous êtes redirigé vers la page Modules. Le module que vous avez créé devrait s'afficher avec l'état Activé.

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

CLI gcloud

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 qui inclut des expressions CEL pour la logique de détection et les propriétés de sortie.

Une fois la définition terminée, importez-la dans Security Command Center à l'aide des commandes gcloud CLI.

1. Codez une définition de module personnalisé dans un fichier YAML en suivant les instructions de la section Coder un module personnalisé pour Security Health Analytics.
2. Enregistrez le fichier YAML dans un emplacement accessible à votre instance de gcloud CLI.

3. 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ésultat 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é.

Terraform

Pour créer un module personnalisé pour une organisation :

resource "google_scc_management_organization_security_health_analytics_custom_module" "example" {
  organization = "123456789"
  display_name = "basic_custom_module"
  location = "global"
  enablement_state = "ENABLED"
  custom_config {
    predicate {
      expression = "resource.rotationPeriod > duration(\"2592000s\")"
    }
    resource_selector {
      resource_types = [
        "cloudkms.googleapis.com/CryptoKey",
      ]
    }
    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
    recommendation = "Set the rotation period to at most 30 days."
    severity = "MEDIUM"
  }
}

Créez un module personnalisé pour un dossier :

resource "google_folder" "folder" {
  parent       = "organizations/123456789"
  display_name = "folder-name"
  deletion_protection = false
}

resource "google_scc_management_folder_security_health_analytics_custom_module" "example" {
  folder = google_folder.folder.folder_id
  location = "global"
  display_name = "basic_custom_module"
  enablement_state = "ENABLED"
  custom_config {
    predicate {
      expression = "resource.rotationPeriod > duration(\"2592000s\")"
    }
    resource_selector {
      resource_types = [
        "cloudkms.googleapis.com/CryptoKey",
      ]
    }
    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
    recommendation = "Set the rotation period to at most 30 days."
    severity = "MEDIUM"
  }
}

Créez un module personnalisé pour un projet :

resource "google_scc_management_project_security_health_analytics_custom_module" "example" {
  location = "global"
  display_name = "basic_custom_module"
  enablement_state = "ENABLED"
  custom_config {
    predicate {
      expression = "resource.rotationPeriod > duration(\"2592000s\")"
    }
    resource_selector {
      resource_types = [
        "cloudkms.googleapis.com/CryptoKey",
      ]
    }
    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
    recommendation = "Set the rotation period to at most 30 days."
    severity = "MEDIUM"
  }
}

Console Google Cloud

Pour modifier un module personnalisé existant dans la console Google Cloud  :

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

   Accéder aux paramètres

2. Dans le sélecteur de projet, sélectionnez l'organisation, le dossier ou le projet dans lequel le module personnalisé a été créé à l'origine. Vous ne pouvez pas modifier un module personnalisé ailleurs.

3. Sur la fiche Security Health Analytics, cliquez sur Gérer les paramètres.

4. Sélectionnez l'onglet Modules. Tous les modules de détection Security Health Analytics s'affichent.

5. 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.

6. À droite de la ligne de votre module personnalisé, cliquez sur l'icône du menu "Action" more_vert.

7. Dans le menu d'actions, cliquez sur l'icône Modifier (edit). La page Afficher le module s'ouvre et affiche l'onglet Configurer le module.

8. Modifiez les champs du module personnalisé de chaque onglet sur la page Afficher le module selon vos besoins.

9. Facultatif : Avant d'enregistrer vos modifications, nous vous recommandons de les tester.

   Pour tester un module personnalisé, procédez comme suit :

   1. Créez un fichier YAML contenant les définitions des ressources de test pour les ressources que votre module personnalisé vérifie.

      Pour savoir comment créer un fichier de données de test, consultez 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 des ressources de test. Le test démarre automatiquement lorsque le fichier est importé.

   3. Sous Aperçu des résultats de test, vérifiez les résultats.

      • Si votre fichier YAML contient 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 pas stockés ni écrits dans Security Command Center.

   Pour en savoir plus, consultez Tester les modules personnalisés.

10. Cliquez sur Enregistrer au bas de la page. Vos modifications sont appliquées au module personnalisé.

CLI gcloud

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

1. Modifiez la définition du module personnalisé. Pour savoir comment coder une définition de module personnalisé, consultez Coder un module personnalisé pour Security Health Analytics.

2. Enregistrez le fichier YAML modifié dans un emplacement accessible à gcloud CLI.

3. 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 complet de la ressource 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é.

Console Google Cloud

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

1. Accédez à la page Security Health Analytics dans les paramètres de Security Command Center.

   Accéder aux paramètres

2. Cliquez sur l'onglet Modules. Le panneau Modules s'ouvre.

3. Si nécessaire, utilisez le champ de filtre en haut de la liste des modules pour trouver le module personnalisé que vous devez modifier.

4. Pour afficher les détails de la définition du module personnalisé, cliquez sur l'icône du menu "Action", more_vert, à droite de la ligne du module personnalisé.

5. Dans le menu d'actions, cliquez sur l'icône Modifier edit. La page Afficher le module s'ouvre et affiche l'onglet Configurer le module.

6. Cliquez sur les onglets de la page Afficher le module pour afficher tous les champs de la définition du module personnalisé.

CLI gcloud

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 complet de la ressource 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éé.

Console Google Cloud

1. Accédez à la page Security Health Analytics dans les paramètres de Security Command Center.

   Accéder aux paramètres

2. Cliquez sur l'onglet Modules. Le panneau Modules s'ouvre.

3. Cliquez dans le champ de filtre en haut de la liste des modules pour afficher la liste des types de filtres.

4. Sélectionnez Type, puis saisissez Custom. La liste des modules est mise à jour pour n'afficher que les modules personnalisés.

CLI gcloud

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éé.

Console Google Cloud

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

   Accéder aux paramètres

2. Si vous y êtes invité, sélectionnez votre organisation, votre dossier ou votre projet.

3. Sur la fiche Security Health Analytics, cliquez sur Gérer les paramètres.

4. Sélectionnez l'onglet Modules. Tous les modules de détection Security Health Analytics s'affichent.

5. 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.

6. À droite de la ligne de votre module personnalisé, cliquez sur l'icône du menu "Action" more_vert.

7. Dans le menu d'actions, cliquez sur Supprimer. La boîte de dialogue Supprimer le module personnalisé s'ouvre.

8. Dans la boîte de dialogue, cliquez sur Supprimer.

CLI gcloud

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 complet de la ressource 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éé.

Console

CLI gcloud

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

1. Ouvrez une fenêtre de terminal.

2. 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 aux sources de sécurité.

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

3. 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
   

4. 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\""