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 comprise 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 false ou renvoie false si la valeur booléenne x est true.
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 tous deux true.
Logical OR (Opérateur logique OU) x || y Renvoie true si x, y ou les deux sont true.
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 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.
Existe m.exists(k, expr) Renvoie true si au moins une entrée de mappage m satisfait expr, où k représente la clé de chaque entrée de mappage.
Existe au moins un m.exists_one(k, expr) Renvoie true si une seule entrée dans le mappage m satisfait expr, où k représente la clé de chaque entrée de mappage.
Tous m.all(k, expr) Renvoie true si toutes les entrées du mappage m satisfont expr, où k représente la clé de chaque entrée de mappage.
Filtre m.filter(k, expr) Renvoie une carte contenant uniquement les entrées de mappage de la carte m où l'entrée de mappage satisfait expr, où k représente la clé de chaque entrée de mappage.
Carte m.map(k, expr) Renvoie une liste contenant le résultat de l'évaluation de expr pour chaque clé du mappage m, où k représente la clé de chaque entrée de mappage.

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 comporte plusieurs valeurs, la valeur correspondante dans ce mappage est une chaîne unique contenant toutes les valeurs, séparées par des virgules. Les clés de ce mappage sont toutes en minuscules. Les équilibreurs de charge d'application externes inspectent tous les en-têtes acceptés, et les mêmes limites s'appliquent.

Utilisez has() pour vérifier la disponibilité, comme has(request.headers['header-key']) && request.headers['header-key'] != 'header-value'.

Vous pouvez parcourir la carte pour vérifier les clés et les valeurs. Toutefois, vous ne pouvez utiliser les opérateurs d'itération de carte (exists(), exists_one(), all(), filter() et map()) sur request.headers qu'en combinaison avec request.body ou request.params dans la même expression, par exemple request.body && request.headers.exists(k, k.lower().startsWith('header-prefix')).
request.body string Représente le corps de la requête sous forme de chaîne brute. Il peut représenter des données de n'importe quel Content-Type. Il stocke le contenu sous forme de chaîne sans analyse automatique.
request.params carte Carte de paires clé/valeur ajoutées à l'URL ou incluses dans le corps des requêtes.
URI request: name1=value1&name2=value2
JSON request body with Content-Type: application/json:
{ "username": "johndoe", "email": "johndoe@example.com" }
GraphQL POST request body with Content-Type: application/graphql:
{ Username: "exampleUser", query: "/* other fields */" }
Form POST request body with