Configurer les attributs de langage des règles personnalisées

Chaque règle de stratégie de sécurité Google Cloud Armor comporte une priorité, une condition de correspondance et une action. Cloud Armor effectue l'action de la règle de priorité la plus élevée qui correspond à une requête. Les règles dont la priorité est inférieure à celle de la règle correspondante ayant la priorité la plus élevée ne sont pas évaluées, même si elles présentent les mêmes conditions de correspondance.

Chaque règle de stratégie de sécurité accepte deux types de conditions de correspondance :

  • Une condition de correspondance de base contient des listes d'adresses IP ou des listes de plages d'adresses IP. Les conditions de correspondance de base sont définies à l'aide du flag --src-ip-ranges lors de la création d'une règle à l'aide de la Google Cloud CLI.
  • Une condition de correspondance avancée contient une expression comprenant jusqu'à cinq sous-expressions qui peuvent correspondre à divers attributs d'une requête entrante. Les conditions de correspondance avancées sont définies à l'aide du flag --expression lors de la création d'une règle à l'aide de la Google Cloud CLI.

Cette page aborde les conditions de correspondance avancées et le langage des règles personnalisées Cloud Armor que vous utilisez pour écrire des expressions dans les conditions de correspondance avancées des règles de stratégie de sécurité. Le langage des règles personnalisées Cloud Armor est un sous-ensemble de Common Expression Language (CEL). Les expressions écrites dans le langage de règles personnalisées Cloud Armor nécessitent deux composants :

  • L'attribut : les données à inspecter
  • L'opération : comment utiliser les données

Par exemple, l'expression suivante utilise les attributs origin.ip et 198.51.100.0/24 dans l'opération inIpRange. Dans ce cas, l'expression renvoie "true" si origin.ip est compris dans la plage d'adresses IP 198.51.100.0/24.

inIpRange(origin.ip, '198.51.100.0/24')

Même si l'expression de l'exemple précédent ne correspond qu'à l'adresse IP du client, lorsque vous l'utilisez dans une règle de stratégie de sécurité Cloud Armor, la règle est considérée comme une règle avec des conditions de correspondance avancées du point de vue du quota. Pour en savoir plus, consultez Quotas et limites de Cloud Armor.

Opérations

La documentation de référence suivante décrit les opérateurs que vous pouvez utiliser avec des attributs (représentés par x, y et k) pour définir des expressions de règle.

Opérations Expressions Description
Égalité x == y Renvoie "true" si x est égal à y.
Égalité, littéral de chaîne x == "foo" Renvoie "true" si x est égal au littéral de chaîne constante donné.
Égalité, littéral de chaîne brute x == R"fo'o" Renvoie "true" si x est égal au littéral de chaîne brute donné qui n'interprète pas les séquences d'échappement. Les littéraux de chaîne brute sont pratiques pour exprimer des chaînes qui doivent elles-mêmes utiliser des caractères de séquence d'échappement.
Logical NOT (Opérateur logique PAS) !x Renvoie "true" si la valeur booléenne x est fausse ou renvoie "false" si la valeur booléenne x est vraie.
Différent de x != y Renvoie "true" si x n'est pas égal à y.
Concaténation x + y Renvoie la chaîne concaténée xy.
Logical AND (Opérateur logique ET) x && y Renvoie "true" si x et y sont vrais.
Logical OR (Opérateur logique OU) x || y Renvoie "true" si x, y ou les deux sont vrais.
Contient une sous-chaîne x.contains(y) Renvoie "true" si la chaîne x contient la sous-chaîne y.
Commence par la sous-chaîne x.startsWith(y) Renvoie "true" si la chaîne x commence par la sous-chaîne y.
Se termine par une sous-chaîne x.endsWith(y) Renvoie "true" si la chaîne x se termine par la sous-chaîne y.
Correspondance d'expression régulière x.matches(y) Renvoie "true" si la chaîne x correspond partiellement au modèle y RE2 spécifié. Le modèle RE2 est compilé à l'aide de l'option RE2::Latin1 qui désactive les fonctionnalités Unicode.
Adresse IP dans la plage inIpRange(x, y) Renvoie la valeur "true" si l'adresse IP x est comprise dans la plage d'adresses IP y.
Minuscules x.lower() Renvoie la valeur en minuscules de la chaîne x.
Majuscules x.upper() Renvoie la valeur en majuscules de la chaîne x.
Valeur décodée en base64 x.base64Decode() Renvoie la valeur décodée en base64 de x. Le tiret bas (_) et le tiret (-) sont d'abord remplacés par une barre oblique (/) et un signe plus (+) respectivement. Renvoie "" (chaîne vide) si x n'est pas une valeur base64 valide.
Valeur de mappage des clés m['k'] Renvoie la valeur à la clé k dans le mappage chaîne à chaîne m si k est disponible. Sinon, renvoie une erreur. L'approche recommandée consiste à vérifier d'abord la disponibilité à l'aide de "has(m['k'])==true".
Vérifier la disponibilité des clés dans un mappage has(m['k']) Renvoie "true" si la clé k est disponible dans le mappage m.
Convertir en entier int(x) Convertit le résultat de chaîne de x en type int. Il peut ensuite être utilisé pour établir une comparaison d'entiers à l'aide d'opérateurs arithmétiques standards tels que ">" et "<=". Cela ne fonctionne que pour les valeurs qui sont supposées être des entiers.
Longueur size(x) Renvoie la longueur de la chaîne x.
Décoder l'URL x.urlDecode() Renvoie la valeur décodée par l'URL de x. Les séquences de caractères au format %## sont remplacées par des équivalents non-ASCII, et + par une espace. Les encodages non valides sont renvoyés tels quels.
Décoder l'URL (Unicode) x.urlDecodeUni() Renvoie la valeur décodée par l'URL de x. En plus de urlDecode(), cette fonction gère également les séquences de caractères Unicode au format %u###. Les encodages non valides sont renvoyés tels quels.
Convertir utf8 en Unicode x.utf8ToUnicode() Renvoie la représentation Unicode en minuscules d'une valeur x encodée en UTF-8.

Attributs

Les attributs représentent des informations provenant d'une requête entrante, telles que l'adresse IP du client ou le chemin de l'URL demandé.

Champ Type Description du champ
origin.ip string Adresse IP du client qui a lancé la requête.
origin.user_ip string Adresse IP du client d'origine, incluse dans HTTP-HEADER par un proxy en amont. Avant d'utiliser cet attribut, vous devez configurer l'option userIpRequestHeaders[] dans le champ advancedOptionsConfig de la stratégie de sécurité pour qu'elle corresponde à une source telle que True-Client-IP, X-Forwarded-For ou X-Real-IP. Pour en savoir plus, consultez Présentation des adresses IP des utilisateurs.

Si vous ne configurez pas l'option userIpRequestHeaders[], si l'en-tête configuré contient des valeurs d'adresse IP non valides ou si l'en-tête configuré n'est pas présent, origin.user_ip est défini par défaut sur origin.ip. Pour en savoir plus, consultez la documentation de référence sur la ressource securityPolicy.
origin.tls_ja4_fingerprint chaîne Empreinte TLS/SSL JA4 si le client se connecte à l'aide de HTTPS, HTTP/2 ou HTTP/3. Si elle n'est pas disponible, une chaîne vide est renvoyée.
origin.tls_ja3_fingerprint chaîne Empreinte TLS/SSL JA3 si le client se connecte à l'aide de HTTPS, HTTP/2 ou HTTP/3. Si elle n'est pas disponible, une chaîne vide est renvoyée.
request.headers mappage Mappage chaîne à chaîne des en-têtes de requête HTTP. Si un en-tête contient plusieurs valeurs, la valeur figurant dans ce mappage est une chaîne de toutes les valeurs de l'en-tête, séparées par des virgules. Les clés de ce mappage sont toutes en minuscules. Tous les en-têtes acceptés par les équilibreurs de charge d'application externes sont inspectés, et les mêmes limites s'appliquent.

L'approche recommandée consiste à vérifier d'abord la disponibilité à l'aide de has(), comme has(request.headers['header-key']) && request.headers['header-key'] != 'header-value'.
request.method string Méthode de requête HTTP.
request.path string Chemin d'URL HTTP demandé. Lorsque vous écrivez des règles qui correspondent à request.path, nous vous recommandons de normaliser le chemin d'accès pour faciliter la syntaxe de correspondance en cas d'encodage d'URL, de variations de casse ou de barres obliques inverses. Pour obtenir plus d'informations et des exemples, consultez Traversal and normalization of paths (Traversal et normalisation des chemins d'accès).
request.scheme string Schéma d'URL HTTP, tel que http ou https. Les valeurs de cet attribut sont toutes en minuscules.
request.query chaîne Requête d'URL HTTP au format name1=value&name2=value2, telle qu'elle apparaît sur la première ligne de la requête HTTP. Aucun décodage n'est effectué
origin.region_code string Code pays Unicode associé à l'adresse IP du client, tel que US. Si vous créez une règle ou une expression qui utilise des codes de pays ou de région ISO 3166-1 alpha 2, Cloud Armor traite chaque code indépendamment. Les règles et expressions Cloud Armor utilisent explicitement ces codes de région pour autoriser ou refuser les requêtes.
origin.asn entier Numéro ASN (Autonomous System Number) associé à l'adresse IP du client Le numéro ASN unique est déterminé en fonction de l'opérateur réseau qui accepte les préfixes d'adresse IP contenant l'adresse IP du client.