Cette page explique comment coder une définition de module personnalisé à l'aide de la classe CEL (Common Expression Language) et YAML.
Utilisez la Google Cloud CLI pour importer vos définitions de modules personnalisés dans Security Health Analytics.
Dans le fichier YAML, une définition de module personnalisé consiste en un ensemble structuré de propriétés que vous utilisez pour définir les éléments suivants d'une Module personnalisé Security Health Analytics:
- Ressources à analyser.
- Logique de détection à utiliser.
- Les informations à fournir à vos équipes de sécurité pour qu'elles puissent rapidement comprendre, trier et résoudre le problème détecté.
Propriétés obligatoires et facultatives spécifiques qui constituent une définition YAML sont abordés dans la section Procédure de codage.
Éviter de créer des détecteurs redondants
Pour contrôler le volume des résultats, évitez de créer et d'exécuter des modules contenant les fonctionnalités redondantes.
Par exemple, si vous créez un module personnalisé qui vérifie les clés de chiffrement
ne sont pas alternées au bout de 30 jours, envisagez de désactiver
le détecteur Security Health Analytics KMS_KEY_NOT_ROTATED
, car
sa vérification, qui utilise une valeur de 90 jours, serait superflue.
Pour en savoir plus sur la désactivation des détecteurs, consultez Activez et désactivez les détecteurs.
Étapes de codage
Vous codez la définition d'un module personnalisé pour Security Health Analytics sous la forme d'une série de propriétés YAML, dont certaines contiennent Expressions CEL.
Pour coder un module de définition personnalisée, procédez comme suit:
Créez un fichier texte avec l'extension de nom de fichier
yaml
.Dans le fichier texte, créez une propriété
resource_selector
et spécifiez un à cinq types de ressources à analyser pour le module personnalisé. A Le type de ressource ne peut pas être spécifié plusieurs fois dans un module personnalisé définition. Exemple :resource_selector: resource_types: ‐ cloudkms.googleapis.com/CryptoKey
Les types de ressources que vous spécifiez doivent être compatibles avec Security Command Center. Pour obtenir la liste des types de ressources pris en charge, consultez Types de ressources compatibles
Créez une propriété
predicate
et spécifiez une ou plusieurs expressions CEL. qui vérifient les propriétés des types de ressources à analyser. Toutes les propriétés les expressions que vous référencez dans les expressions CEL doivent exister Définition de chaque type de ressource dans l'API Google Cloud que vous spécifiez sousresource_selector
. Pour déclencher un résultat, l'expression doit correspondre àTRUE
. Par exemple, dans l'expression, seulesrotationPeriod
valeurs supérieures à2592000s
déclenchent un résultat.predicate: expression: resource.rotationPeriod > duration("2592000s")
Si vous avez besoin d'aide pour écrire des expressions CEL, consultez les ressources suivantes:
- Types de ressources compatibles Cliquez sur chaque ressource pour afficher les propriétés que vous pouvez utiliser dans votre les expressions CEL.
- Écrire des expressions CEL
- Référencer des propriétés de ressources et de règles dans des modules personnalisés
Créez une propriété
description
qui explique la faille ou d'une erreur de configuration détectée par le module personnalisé. Cette explication apparaît dans chaque instance de résultat afin d’aider les enquêteurs à comprendre le problème détecté. Le texte doit être placé entre guillemets. Exemple :description: "The rotation period of the identified cryptokey resource exceeds 30 days, the maximum rotation period that our security guidelines allow."
Créez une propriété
recommendation
qui explique comment corriger le a détecté un problème. La gcloud CLI nécessite un caractère d'échappement avant certains caractères, comme les guillemets. Les éléments suivants : exemple montre comment utiliser la barre oblique inverse pour échapper chaque ensemble de guillemets marques:recommendation: "To fix this issue go to https://console.cloud.google.com/security/kms. Click the key-ring that contains the key. Click the key. Click \"Edit rotation period\". Then set the rotation period to at most 30 days."
Si vous créez ou mettez à jour un module personnalisé à l'aide de la méthode dans la console Google Cloud, les caractères d'échappement ne sont pas obligatoires.
Créez une propriété
severity
et spécifiez la gravité par défaut pour le et les résultats créés par ce module. Valeurs couramment utilisées pour le paramètreseverity
:LOW
,MEDIUM
,HIGH
etCRITICAL
. Par exemple,severity: MEDIUM
Vous pouvez également créer une propriété
custom_output
et spécifier des informations supplémentaires à renvoyer avec chaque résultat. Spécifier les informations pour renvoyer sous forme d'une ou de plusieurs paires nom/valeur. Vous pouvez renvoyer la valeur d'une propriété de la ressource analysée ou une chaîne littérale. Les établissements doivent être spécifiés en tant queresource.PROPERTY_NAME
Les chaînes littérales doivent être entre guillemets. L'exemple suivant montre uncustom_output
qui renvoie à la fois une valeur de propriété, la valeur derotationPeriod
dans la ressourceCryptoKey
analysée, ainsi qu'une chaîne de texte,"Excessive rotation period for CryptoKey"
:custom_output: properties: - name: duration value_expression: expression: resource.rotationPeriod - name: note value_expression: expression: "Excessive rotation period for CryptoKey"
Enregistrez le fichier dans un emplacement auquel votre gcloud CLI peut accéder.
Importez la définition dans Security Health Analytics à l'aide de la commande suivante:
gcloud scc custom-modules sha create \ --organization=organizations/ORGANIZATION_ID \ --display-name="MODULE_DISPLAY_NAME" \ --enablement-state="ENABLED" \ --custom-config-from-file=DEFINITION_FILE_NAME.yaml
Remplacez les valeurs suivantes :
ORGANIZATION_ID
par l'ID du parent ; organisation du module personnalisé ou remplacez le--organization
avec--folders
ou--project
, et spécifiez l'ID le dossier ou le projet parent.MODULE_DISPLAY_NAME
par un nom à afficher. comme catégorie de résultats lorsque le module personnalisé renvoie des résultats. Le nom doit comporter entre 1 et 128 caractères et doit commencer par une lettre minuscule lettre et ne contenir que des caractères alphanumériques ou des traits de soulignement.DEFINITION_FILE_NAME
par le chemin d'accès et le nom de fichier de le fichier YAML contenant la définition du module personnalisé.
Pour en savoir plus sur l'utilisation du service Security Health Analytics personnalisé modules, consultez Utiliser des modules personnalisés pour Security Health Analytics
Analyser les latences pour les nouveaux modules personnalisés
La création d'un module personnalisé ne déclenche pas de nouvelle analyse.
Security Health Analytics n'utilise pas de nouveau module personnalisé des éléments suivants:
- Première analyse par lot après la création du module personnalisé. En fonction de lorsque vous créez un module personnalisé dans votre planification d'analyse par lot, vous pouvez vous devrez patienter jusqu'à 24 heures avant que Security Health Analytics commence à utiliser ce module personnalisé.
- La modification d'une ressource cible déclenche une analyse en temps réel.
Exemple de définition de module personnalisé
L'exemple suivant montre une définition de module personnalisé terminée
déclenche un résultat si la valeur de la propriété rotationPeriod
d'un
La ressource cloudkms.googleapis.com/CryptoKey
est supérieure à 2 592 000
secondes (30 jours). L'exemple renvoie deux valeurs facultatives dans la
Section custom_output
: la valeur de resource.rotationPeriod
et une note
sous forme de chaîne de texte.
Dans l'exemple, notez les éléments suivants:
- Le type d'asset ou de ressource à vérifier est listé dans
resource_selector
sousresource_types
. - La vérification que le module effectue sur les ressources, sa logique de détection
est défini dans la section
predicate
, précédée deexpression
. - Deux propriétés sources personnalisées,
duration
etviolation
, sont définies. dans la sectioncustom_output
. - L'explication du problème détecté est précisée dans le
description
. - Les conseils pour résoudre le problème détecté sont les suivants :
spécifié dans la propriété
recommendation
. Comme les guillemets apparaissent dans les instructions, un caractère d'échappement avec une barre oblique inverse est requis avant chaque guillemets.
severity: HIGH
description: "Regular key rotation helps provide protection against
compromised keys, and limits the number of encrypted messages available
to cryptanalysis for a specific key version."
recommendation: "To fix this issue go to
https://console.cloud.google.com/security/kms. Click the key-ring that
contains the key. Click the key. Click \"Edit rotation period\". Then
set the rotation period to at most 30 days."
resource_selector:
resource_types:
- cloudkms.googleapis.com/CryptoKey
predicate:
expression: resource.rotationPeriod > duration("2592000s")
custom_output:
properties:
- name: duration
value_expression:
expression: resource.rotationPeriod
- name: violation
value_expression:
expression:
"Excessive rotation period for CryptoKey"
Référencer des propriétés de ressources et de règles dans des modules personnalisés
Quelle que soit la méthode employée pour créer un module personnalisé, la méthode dans la console Google Cloud ou en écrivant la définition vous-même, nous devons être en mesure de rechercher les propriétés que vous pouvez évaluer ce module personnalisé. Vous devez également savoir comment référencer ces propriétés la définition d'un module personnalisé.
Trouver les propriétés d'une ressource ou d'une stratégie
Les propriétés d'une ressource Google Cloud sont définies dans l'API. de la ressource. Pour accéder à cette définition, cliquez sur nom de ressource dans Types de ressources compatibles
Vous pouvez trouver les propriétés d'une stratégie documentation de référence de l'API. Pour connaître les propriétés d'une règle, voir Règle.
Référencer une propriété de ressource dans une définition de module personnalisé
Lorsque vous créez un module personnalisé, toutes les références directes à la propriété
d'une ressource analysée doit commencer par resource
, suivi de tout parent
et enfin la propriété cible. Les propriétés sont séparées
par un point, en utilisant une notation par points de style JSON.
Voici des exemples de propriétés de ressources et de la façon dont elles peuvent être récupérées:
resourceName
: stocke le nom complet d'une ressource dans l'inventaire des éléments cloud, par Exemple ://cloudresourcemanager.googleapis.com/projects/296605646631
.resource.rotationPeriod
: oùrotationPeriod
est une propriété deresource
.resource.metadata.name
: oùname
est une sous-propriété demetadata
. qui est une sous-propriété deresource
.
Référencer les propriétés des stratégies IAM
Vous pouvez créer des expressions CEL qui évaluent la stratégie IAM d'une ressource en référençant ses propriétés de stratégie IAM. Les seules propriétés disponibles sont les liaisons et les rôles dans les liaisons.
Lorsque vous référencez des propriétés de stratégie IAM, policy
est
votre propriété de premier niveau.
Vous trouverez ci-dessous des exemples de propriétés des stratégies IAM peuvent être récupérées:
policy.bindings
, oùbindings
est une propriété depolicy
.policy.version
, oùversion
est une propriété depolicy
.
Pour obtenir plus d'exemples, consultez la section Exemples d'expressions CEL.
Pour plus d'informations sur les propriétés d'une règle, voir Règle.
Écrire des expressions CEL
Lorsque vous créez un module personnalisé, vous utilisez des expressions CEL pour évaluer
les propriétés de la ressource analysée. Vous pouvez également utiliser
Les expressions CEL pour définir des paires name
-value
personnalisées qui renvoient des valeurs supplémentaires
des informations avec
vos résultats.
Que vous créiez un module personnalisé dans la console Google Cloud ou écrire vous-même la définition de votre module personnalisé dans un fichier YAML, les expressions CEL que vous définissez sont identiques.
Expressions CEL pour la logique de détection
Vous codez la logique de détection d'un module personnalisé à l'aide du CEL. avec des opérateurs CEL standards pour évaluer les propriétés les ressources analysées.
Vos expressions peuvent être de simples vérifications d'une seule valeur ou des expressions plus complexes.
des expressions composées qui vérifient plusieurs valeurs ou conditions. Dans tous les cas,
L'expression doit correspondre à une valeur booléenne true
pour déclencher un résultat.
Si vous créez un module personnalisé dans la console Google Cloud, vous écrivez ces expressions Dans l'Éditeur d'expressions de la page Configurer le module.
Si vous codez un module personnalisé dans un fichier YAML, vous ajoutez ces expressions
sous la propriété predicate
.
Que vous utilisiez la console Google Cloud ou un fichier YAML les expressions CEL qui évaluent les propriétés d'une ressource doivent être conformes au les règles suivantes:
- Les propriétés que vous spécifiez dans une expression CEL doivent être des propriétés de la ressource analysée, comme défini dans la définition de l'API de la ressource de mots clés.
Si un module personnalisé évalue plusieurs types de ressources, les propriétés que vous spécifiez dans les expressions CEL doivent être communes à chaque type de ressource évalué par le module personnalisé.
Par exemple, si vous définissez un module personnalisé appelé
invalid_cryptokey
qui vérifie deux types de ressources:cloudkms.googleapis.com/CryptoKey
etcloudkms.googleapis.com/CryptoKeyVersion
, vous pouvez écrire ce qui suit : car les ressourcesCryptoKey
etCryptoKeyVersion
incluent la propriéténame
:predicate: resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")
Toutefois, vous ne pouvez pas spécifier l'expression suivante dans le le module personnalisé
invalid_cryptokey
, car les fonctionsimportTime
et Les propriétésrotationPeriod
évaluées par l'expression ne sont pas partagées par les deux types de ressources:predicate: resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")
Toutes les énumérations d'une expression CEL doivent être représentées comme suit : de chaînes. Voici un exemple d'expression valide pour le paramètre Type de ressource
cloudkms.googleapis.com/CryptoKeyVersion
:resource.state = "PENDING_GENERATION"
Résultat des expressions CEL que vous définissez dans la propriété
predicate
doit être une valeur booléenne. Un résultat n'est déclenché que si le résultat esttrue
.
Pour en savoir plus sur le langage CEL, consultez les pages suivantes:
Exemples d'expressions CEL
Le tableau suivant répertorie quelques expressions CEL qui peuvent être utilisées pour pour évaluer les propriétés des ressources. Vous pouvez les utiliser dans la console Google Cloud et dans les définitions de modules personnalisés YAML.
Type de ressource | Explication | Expression CEL |
---|---|---|
Toute ressource avec une stratégie IAM | Vérification des stratégies IAM pour identifier les membres externes au domaine | !policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com'))) |
cloudkms.googleapis.com/CryptoKey |
Vérification de la période de rotation des clés Cloud KMS | has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h') |
Plusieurs types de ressources avec une seule stratégie | Vérifiez si le nom de la ressource commence par dev ou devAccess
en fonction du type de ressource |
(resource.type == 'compute.googleapis.com/Disk' &&
resource.name.startsWith('projects/PROJECT_ID/regions/
REGION/disks/devAccess')) || (resource.type ==
'compute.googleapis.com/Instance ' &&
resource.name.startsWith('projects/PROJECT_ID/zones/REGION/instances/dev-')) |
compute.googleapis.com/Network |
Règle d'appairage du cloud privé virtuel à mettre en correspondance avec les pairs du réseau | resource.selfLink.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default') || resource.peerings.exists(p, p.network.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/shared$')) |
cloudfunctions.googleapis.com/CloudFunction |
Autoriser uniquement le trafic entrant interne pour la fonction Cloud | has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY') |
compute.googleapis.com/Instance |
Le nom de la ressource correspond au modèle | resource.name.matches('^gcp-vm-(linux|windows)-v\\d+$') |
serviceusage.googleapis.com/Service |
Autoriser uniquement l'activation des API liées au stockage | resource.state == 'ENABLED' && !( resource.name.matches('storage-api.googleapis.com') || resource.name.matches('bigquery-json.googleapis.com') || resource.name.matches('bigquery.googleapis.com') || resource.name.matches('sql-component.googleapis.com') || resource.name.matches('spanner.googleapis.com'))
|
sqladmin.googleapis.com/Instance
|
Seules les adresses IP publiques figurant sur la liste d'autorisation sont autorisées | (resource.instanceType == 'CLOUD_SQL_INSTANCE' && resource.backendType == 'SECOND_GEN' && resource.settings.ipConfiguration.ipv4Enabled ) && !(resource.ipAddresses.all(ip, ip.type != 'PRIMARY' || ip.ipAddress.matches('IP_ADDRESS'))))
|
dataproc.googleapis.com/Cluster |
Vérifier si les ID de projet d'un cluster Dataproc contiennent les tests de sous-chaînes | has(resource.projectId) && resource.projectId.contains('testing') || resource.projectId.contains('development') |
Expressions CEL pour les propriétés de résultat personnalisées
Éventuellement, pour renvoyer des informations supplémentaires avec chaque résultat qui peut être utilisées pour la recherche de requêtes, vous pouvez définir jusqu'à 10 propriétés personnalisées à renvoyer avec les résultats générés par vos modules personnalisés.
Les propriétés personnalisées apparaissent dans les propriétés sources du résultat dans la son JSON et dans l'onglet Propriétés sources des détails du résultat dans console Google Cloud.
Vous définissez les propriétés personnalisées sous forme de paires name
-value
.
Si vous créez un module personnalisé dans la console Google Cloud,
vous définissez les paires name
-value
dans les propriétés de résultat personnalisées.
de la page Définir les détails du résultat.
Si vous codez un module personnalisé dans un fichier YAML, vous devez répertorier name
-value
les paires sous la forme properties
sous la propriété custom_output
.
Que vous utilisiez la console Google Cloud ou un fichier YAML les règles suivantes s'appliquent:
- Spécifiez
name
en tant que chaîne de texte sans guillemets. Spécifiez
value
comme suit:Pour renvoyer la valeur d'une propriété, spécifiez la propriété comme suit : format:
RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
Dans l'exemple :
RESOURCE_TYPE
peut êtreresource
oupolicy
PROPERTY
: une ou plusieurs propriétés parentes de qui contient la valeur à renvoyer.PROPERTY_TO_RETURN
est la propriété qui contient la valeur à renvoyer.Pour renvoyer une chaîne de texte, placez-la entre guillemets.
L'exemple suivant montre deux paires name
-value
correctement définies sous
custom_output
dans un fichier YAML:
custom_output: properties: - name: duration value_expression: expression: resource.name - name: property_with_text value_expression: expression: "Note content"
Étape suivante
Pour tester, envoyer, afficher et mettre à jour des modules personnalisés, consultez les pages suivantes:
- Pour tester des modules personnalisés, consultez Tester des modules personnalisés pour Security Health Analytics.
- Pour importer, afficher et mettre à jour des modules personnalisés, consultez Créer et gérer des modules personnalisés pour Security Health Analytics.