Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'Apigee Edge.
Quoi
Extrait les informations d'un message (par exemple, Chemin d'URI, Paramètre de requête, En-tête, Paramètre de formulaire, Variable, Charge utile XML ou Charge utile JSON) et évalue le contenu par rapport à des expressions régulières prédéfinies. Si l'une des expressions régulières spécifiées renvoie la valeur "true", le message est considéré comme une menace et la règle génère une erreur.
Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.
Vidéos
Regardez la vidéo suivante pour en savoir plus sur la règle de protection des expressions régulières.
Vidéo | Description |
---|---|
Se protéger contre les attaques par injection SQL | Protégez-vous contre les attaques d'injection SQL avec la règle de protection des expressions régulières de l'interface utilisateur d'Apigee. |
Exemples
GitHub
L'exemple de protection des expressions régulières disponible sur GitHub montre comment détecter des attaques d'injection SQL potentielles émises via un paramètre de requête pouvant contenir du code malveillant dans un tag <script>
.
En outre, cet exemple illustre une bonne pratique permettant de définir un état d'erreur générique 400 pour empêcher les pirates informatiques d'obtenir des informations utiles à partir de la réponse.
JavaScript inclut une protection contre les attaques.
<RegularExpressionProtection name="JsonPathRegExProtection"> <Source>request</Source> <JSONPayload escapeSlashCharacter="true"> <JSONPath> <Expression>$</Expression> <Pattern><![CDATA[ <\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*> ]]></Pattern> </JSONPath> </JSONPayload> </RegularExpressionProtection>
L'exemple ci-dessus montre comment utiliser la règle RegularExpressionProtection pour évaluer les charges utiles JSON pour JavaScript, notamment les attaques. Plus précisément, le contenu extrait par <JSONPath>
/<Expression>
est évalué par rapport à l'expression régulière dans <JSONPath>
/<Pattern>
.
Si l'expression régulière dans votre élément <JSONPath>
/<Pattern>
inclut des caractères réservés au format XML (", &, ', <, ou >), vous devez l'encapsuler dans une section CDATA (CharacterData) comme indiqué dans l'exemple ci-dessus, ou encodez en XML les caractères réservés, par exemple en remplaçant <
par <
et >
par >
.
En outre, si votre expression régulière inclut des barres obliques (/), vous devez les échapper en définissant l'attribut <JSONPayload>
escapeSlashCharacter
sur true
.
Correspondance non sensible à la casse
Il s'agit d'un cas d'utilisation courant pour effectuer une correspondance non sensible à la casse. Voici un exemple où vous pouvez effectuer cette opération dans une expression régulière à l'aide de la création de (?i)
. Dans cet exemple, DELETE
, delete
et Delete
seront "true".
<Pattern>[\s]*(?i)((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))</Pattern>
Vérification des paramètres du formulaire
<RegularExpressionProtection name="REP-Formparam"> <Source>request</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <FormParam name="firstname"> <Pattern><![CDATA[[-+=$%&]]]></Pattern> </FormParam> <FormParam name="lastname"> <Pattern><![CDATA[[-+=$%&]]]></Pattern> </FormParam> </RegularExpressionProtection>
La configuration de règle RegularExpressionProtection évalue les paramètres du formulaire concernant l'occurrence de caractères spéciaux, dans l'ensemble [-+=$%&]
.
Cette règle n'a d'effet que lorsque l'en-tête "content-type" dans la requête correspond à application/x-www-form-urlencoded
. La configuration de la règle utilise une section CDATA (données des caractères) pour encapsuler les expressions régulières, en raison de la présence du caractère &, qui est spécial en XML.
À propos de la règle de protection des expressions régulières
Apigee vous permet de configurer des expressions régulières pouvant être évaluées par rapport au trafic de l'API au moment de l'exécution, afin d'identifier les menaces de niveau de contenu courantes qui suivent certains schémas.
Une expression régulière (ou expression régulière) est un ensemble de chaînes spécifiant un modèle dans une chaîne. Les expressions régulières permettent d'évaluer le contenu de manière automatisée pour identifier des schémas. Les expressions régulières peuvent être utilisées, par exemple, pour évaluer une adresse e-mail afin de vous assurer qu'elle est correctement structurée. Pour en savoir plus, consultez la page Expressions régulières des tutoriels Java.
L'utilisation la plus courante de RegularExpressionProtection est l'évaluation des charges utiles JSON et XML afin de détecter du contenu malveillant.
Aucune expression régulière ne peut éliminer toutes les attaques basées sur le contenu. Plusieurs mécanismes doivent être combinés pour permettre une défense en profondeur. Cette section décrit des schémas recommandés pour exclure du contenu.
Exemples de formats d'exclusion
Les expressions régulières doivent être encodées au format XML dans le fichier de configuration XML de la règle. Consultez également la section Antimodèle : Utiliser des quantificateurs gourmands en ressources dans la règle RegularExpressionProtection.
Nom | Expression régulière |
---|---|
Injection SQL |
[\s]*((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b)) |
Injection de commande SSI |
<!--#(include|exec|echo|config|printenv)\s+.* Encodage XML : <!--#(include|exec|echo|config|printenv)\s+.* |
Injection de syntaxe abrégée XPath |
(/(@?[\w_?\w:\*]+(\[[^]]+\])*)?)+ |
Injection de syntaxe développée XPath |
/?(ancestor(-or-self)?|descendant(-or-self)?|following(-sibling)) |
Injection JavaScript |
<\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> Encodage XML : <\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> |
Définir l'en-tête "Content-Type" dans une requête avec une charge utile XML ou JSON
La charge utile de la règle de protection des expressions régulières peut inclure les éléments suivants :
- Élément
<XMLPayload>
: spécifie que les informations doivent être extraites d'une charge utile XML et évaluées par rapport à l'expression régulière fournie.Si vous utilisez
<XMLPayload>
dans la règle, l'en-têteContent-Type
de la requête doit être un type de contenu XML, tel queapplication/xml
outext/xml
. - Élément
<JSONPayload>
: indique que les informations doivent être extraites d'une charge utile JSON et évaluées par rapport à l'expression régulière fournie.Si vous utilisez
<JSONPayload>
dans la règle, l'en-têteContent-Type
de la requête doit être un type de contenu JSON tel queapplication/json
.
Généralement, vous concevez une API pour accepter les formats XML ou JSON. Toutefois, il existe un scénario dans lequel l'API a accepté les deux. Vous pouvez ensuite définir une règle de protection des expressions régulières qui utilise à la fois les éléments <XMLPayload>
et <JSONPayload>
.
Un seul élément peut s'appliquer à une requête spécifique en fonction de la valeur de l'en-tête Content-Type
.
Documentation de référence des éléments
La documentation de référence des éléments décrit les éléments et les attributs de la règle RegularExpressionProtection.
<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-Protection-1"> <DisplayName>Regular Expression Protection 1</DisplayName> <Source>response</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <URIPath> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </URIPath> <QueryParam name="a-query-param"> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </QueryParam> <Header name="a-header"> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </Header> <FormParam name="a-form-param"> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </FormParam> <Variable name="request.content"> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </Variable> <XMLPayload> <Namespaces> <Namespace prefix="apigee">http://www.apigee.com</Namespace> </Namespaces> <XPath> <Expression>/apigee:Greeting/apigee:User</Expression> <Type>string</Type> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </XPath> </XMLPayload> <JSONPayload> <JSONPath> <Expression>$.store.book[*].author</Expression> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </JSONPath> </JSONPayload> </RegularExpressionProtection>
Attributs <RegularExpressionProtection>
<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-Protection-1">
Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :
Attribut | Description | Par défaut | Presence |
---|---|---|---|
name |
Nom interne de la règle. La valeur de l'attribut Vous pouvez également utiliser l'élément |
N/A | Obligatoire |
continueOnError |
Définissez sur Définissez sur |
false | Facultatif |
enabled |
Définissez sur Définissez sur |
true | Facultatif |
async |
Cet attribut est obsolète. |
false | Obsolète |
Élément <DisplayName>
Utilisez-le, en plus de l'attribut name
, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.
<DisplayName>Policy Display Name</DisplayName>
Par défaut |
N/A Si vous omettez cet élément, la valeur de l'attribut |
---|---|
Presence | Facultatif |
Type | Chaîne |
Élément <Source>
Indique le message à partir duquel les informations doivent être extraites.
Si l'élément <Source>
est omis, la valeur par défaut est message
. Par exemple, <Source>message</Source>
. Lorsqu'il est défini sur message
, la règle utilise le message de requête comme source lorsqu'il est associé à un flux de requête. De même, la règle utilise le message de réponse lorsqu'il est associé à un flux de réponse.
Si le message source ne peut pas être résolu ou s'il est résolu en un type qui n'est pas un message, la règle renvoie une erreur.
<Source>response</Source>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | Chaîne |
Élément <IgnoreUnresolvedVariables>
Détermine si la stratégie renvoie une erreur lorsqu'elle rencontre une variable impossible à résoudre.
Si elle est définie sur false
(valeur par défaut), la stratégie renvoie une erreur lorsqu'une variable impossible à résoudre est rencontrée. Si elle est définie sur true
, la variable non résolue est traitée comme une chaîne vide (Null).
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
Valeur par défaut : | false |
Présence : | Facultatif |
Type : | Booléen |
Élément <URIPath>
Spécifie que les informations doivent être extraites du chemin de l'URI de la requête et évaluées par rapport aux expressions régulières fournies. Vous devez fournir au moins un élément <Pattern>
spécifiant un modèle d'expression régulière à mettre en correspondance.
<URIPath> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </URIPath>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | N/A |
Élément <QueryParam>
Indique que les informations doivent être extraites du paramètre de requête et évaluées par rapport aux expressions régulières fournies. Vous devez fournir au moins un élément <Pattern>
spécifiant un modèle d'expression régulière à mettre en correspondance.
<QueryParam name="a-query-param"> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </QueryParam>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | N/A |
Attributs
Attribut | Description | Par défaut | Presence |
---|---|---|---|
nom | Nom du paramètre de requête à partir duquel les informations doivent être extraites pour être évaluées par rapport aux expressions régulières fournies. | N/A | Obligatoire |
Élément <Header>
Indique que les informations doivent être extraites des en-têtes de requête et de réponse et évaluées par rapport aux expressions régulières fournies. Vous devez fournir au moins un élément <Pattern>
spécifiant un modèle d'expression régulière à mettre en correspondance.
<Header name="a-header"> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </Header>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | N/A |
Attributs
Attribut | Description | Par défaut | Presence |
---|---|---|---|
nom |
Nom de l'en-tête de requête et de réponse à partir duquel les informations doivent être extraites afin d'être évaluées par rapport aux expressions régulières fournies. |
N/A | Obligatoire |
Élément <FormParam>
Spécifie que les informations doivent être extraites du paramètre de formulaire de requête et évaluées par rapport aux expressions régulières fournies. Vous devez fournir au moins un élément <Pattern>
spécifiant un modèle d'expression régulière à mettre en correspondance.
<FormParam name="a-form-param"> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </FormParam>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | N/A |
Attributs
Attribut | Description | Par défaut | Presence |
---|---|---|---|
nom |
Nom du paramètre de formulaire de requête à partir duquel les informations doivent être extraites pour être évaluées par rapport aux expressions régulières fournies. |
N/A | Obligatoire |
Élément <Variable>
Indique que les informations doivent être extraites de la variable donnée et évaluées par rapport aux expressions régulières fournies.
<Variable name="request.content"> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </Variable>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | N/A |
Attributs
Attribut | Description | Par défaut | Presence |
---|---|---|---|
nom |
Nom de la variable à partir de laquelle les informations doivent être extraites pour être évaluées par rapport aux expressions régulières fournies. |
N/A | Obligatoire |
Élément <XMLPayload>
Spécifie que les informations doivent être extraites d'une charge utile XML et évaluées par rapport aux expressions régulières fournies.
<XMLPayload> <Namespaces> <Namespace prefix="apigee">http://www.apigee.com</Namespace> </Namespaces> <XPath> <Expression>/apigee:Greeting/apigee:User</Expression> <Type>string</Type> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </XPath> </XMLPayload>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | N/A |
Élément <XMLPayload>/<Namespaces>
Spécifie les espaces de noms à utiliser dans l'évaluation XPath.
<XMLPayload> <Namespaces> <Namespace prefix="apigee">http://www.apigee.com</Namespace> </Namespaces> <XPath> <Expression>/apigee:Greeting/apigee:User</Expression> <Type>string</Type> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </XPath> </XMLPayload>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | Chaîne |
Élément <XMLPayload>/<Namespaces>/<Namespace>
Spécifie chaque espace de noms à utiliser dans l'évaluation XPath.<Namespaces> <Namespace prefix="apigee">http://www.apigee.com</Namespace> </Namespaces>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | Chaîne |
Attributs
Attribut | Description | Par défaut | Presence |
---|---|---|---|
préfixe |
Fournit un préfixe permettant de qualifier un espace de noms donné. |
N/A | Obligatoire |
Élément <XMLPayload>/<XPath>
Spécifie le chemin XPath à évaluer.<XPath> <Expression>/apigee:Greeting/apigee:User</Expression> <Type>string</Type> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </XPath>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | N/A |
Élément <XMLPayload>/<XPath>/<Expression>
Spécifie l'expression XPath définie pour la variable. Seules les expressions XPath 1.0 sont acceptées. Par exemple,<Expression>/company/employee[@age>=$request.header.age]</Expression>
extrait les détails des employés dont l'âge est supérieur ou égal à la valeur spécifiée dans request.header.age
.<XPath> <Expression>/apigee:Greeting/apigee:User</Expression> <Type>string</Type> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </XPath>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | Chaîne |
Élément <XMLPayload>/<XPath>/<Type>
Spécifie le type de données de sortie souhaité.
Vous devez généralement utiliser "string" ou "nodeset". Utilisez "string" si vous êtes certain que votre requête xpath renverra au maximum une valeur, ou si vous souhaitez vérifier au maximum une valeur. Si votre requête xpath peut renvoyer plusieurs valeurs, spécifiez "nodeset" pour vérifier toutes les valeurs.
Par exemple, considérons l'expression XPath //*/@*
. La valeur correspond à tous les attributs de tous les éléments. Si vous spécifiez "string" comme type (Type
), Apigee convertit (par coercition) le résultat de cette requête en une seule chaîne qui correspond à la valeur de l'un des attributs de l'un des éléments du document XML, mais l'attribut et l'élément ne sont pas définis. Apigee effectue ensuite une correspondance de modèles par rapport à la valeur de cet attribut seulement. Ce n'est probablement pas ce que vous souhaitez.
Inversement, si vous spécifiez "nodeset" en comme Type
pour cette expression XPath, Apigee effectue une correspondance de modèle avec chacune des valeurs d'attribut de chaque élément du document XML.
<XPath> <Expression>/apigee:Greeting/apigee:User</Expression> <Type>string</Type> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </XPath>
Valeur par défaut : | chaîne |
Présence : | Facultatif |
Type : | Chaîne |
Valeurs correctes : |
L'un des mots clés suivants : |
Élément <XMLPayload>/<XPath>/<Pattern>
Définit le modèle d'expression régulière. Si une expression régulière de votre élément <Pattern>
inclut des caractères réservés au format XML (", &, ', < ou .), vous devez l'encoder en XML avant de l'inclure.
<XPath> <Expression>/apigee:Greeting/apigee:User</Expression> <Type>string</Type> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </XPath>
Valeur par défaut : | N/A |
Présence : | Requis |
Type : | Chaîne |
Élément <JSONPayload>
Spécifie que les informations doivent être extraites d'une charge utile JSON et évaluées en fonction des expressions régulières fournies.
<JSONPayload> <JSONPath> <Expression>$.store.book[*].author</Expression> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </JSONPath> </JSONPayload>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | N/A |
Attributs
Attribut | Description | Par défaut | Presence |
---|---|---|---|
escapeSlashCharacter |
Définissez la valeur sur |
true | Facultatif |
Élément <JSONPayload>/<JSONPath>/<Expression>
Spécifie l'expression JSONPath définie pour la variable.
<JSONPath> <Expression>$.store.book[*].author</Expression> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </JSONPath>
Valeur par défaut : | N/A |
Présence : | Facultatif |
Type : | Chaîne |
Élément <JSONPayload>/<JSONPath>/<Pattern>
Définit le modèle d'expression régulière. Si une expression régulière de votre élément <Pattern>
inclut des caractères réservés au format XML (", &, ', < ou .), vous devez l'encoder en XML avant de l'inclure.
<JSONPath> <Expression>$.store.book[*].author</Expression> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </JSONPath>
Valeur par défaut : | N/A |
Présence : | Requis |
Type : | Chaîne |
Informations de référence sur les erreurs
Cette section décrit les codes et messages d'erreur renvoyés ainsi que les variables de défaillance définis par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Si vous souhaitez capturer une erreur et générer votre propre erreur personnalisée, définissez l'attribut continueOnError="true"
sur l'élément racine de la règle.
Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.
Erreurs d'exécution
Ces erreurs peuvent se produire lors de l'exécution de la règle.
Code d'erreur | Message |
---|---|
ExecutionFailed |
Failed to execute the RegularExpressionProtection StepDefinition {0}. Reason: {1} |
InstantiationFailed |
Failed to instantiate the RegularExpressionProtection StepDefinition {0} |
NonMessageVariable |
Variable {0} does not resolve to a Message |
SourceMessageNotAvailable |
{0} message is not available for RegularExpressionProtection StepDefinition {1} |
ThreatDetected |
Regular Expression Threat Detected in {0}: regex: {1} input: {2} |
VariableResolutionFailed |
Failed to resolve variable {0} |
Erreurs de déploiement
Code d'erreur | Message | Corriger |
---|---|---|
CannotBeConvertedToNodeset |
RegularExpressionProtection {0}: Result of xpath {1} cannot be converted to nodeset.
Context {2} |
build |
DuplicatePrefix |
RegularExpressionProtection {0}: Duplicate prefix {1} |
build |
EmptyJSONPathExpression |
RegularExpressionProtection {0}: Empty JSONPath expression |
build |
EmptyXPathExpression |
RegularExpressionProtection {0}: Empty XPath expression |
build |
InvalidRegularExpression |
RegularExpressionProtection {0}: Invalid Regular Expression {1}, Context {2} |
build |
JSONPathCompilationFailed |
RegularExpressionProtection {0}: Failed to compile jsonpath {1}. Context {2} |
build |
NONEmptyPrefixMappedToEmptyURI |
RegularExpressionProtection {0}: Non-empty prefix {1} cannot be mapped to empty
uri |
build |
NoPatternsToEnforce |
RegularExpressionProtection {0}: No patterns to enforce in {1} |
build |
NothingToEnforce |
RegularExpressionProtection {0}: at least one of URIPath, QueryParam, Header,
FormParam, XMLPayload, JSONPayload is mandatory |
build |
XPathCompilationFailed |
RegularExpressionProtection {0}: Failed to compile xpath {1}. Context {2} |
build |
Variables de panne
Ces variables sont définies lorsque cette règle déclenche une erreur. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.
Variables | Où : | Exemple |
---|---|---|
fault.name="fault_name" |
fault_name est le nom de l'erreur, tel que répertorié dans le tableau ci-dessus. | fault.name Matches "ThreatDetected" |
regularexpressionprotection.policy_name.failed |
policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. | regularexpressionprotection.Regular-Expressions-Protection-1.failed = true |
Schémas
Articles associés
Règle de protection contre les menaces JSON
Règle de protection contre les menaces XML