Règle de protection contre les expressions régulières

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.

Exemples

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

<Pattern>[\s]*(?i)((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))</Pattern>

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

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

[\s]*((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))

<!--#(include|exec|echo|config|printenv)\s+.*

<!--#(include|exec|echo|config|printenv)\s+.*

(/(@?[\w_?\w:\*]+(\[[^]]+\])*)?)+

/?(ancestor(-or-self)?|descendant(-or-self)?|following(-sibling))

<\s*script\b[^>]*>[^<]+<\s*/\s*script\s*>

<\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ête Content-Type de la requête doit être un type de contenu XML, tel que application/xml ou text/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ête Content-Type de la requête doit être un type de contenu JSON tel que application/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 :

É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>

É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>

É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>

É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>

É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>

Attributs

É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>

Attributs

É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>

Attributs

É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>

Attributs

É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>

É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>

Élément <XMLPayload>/<Namespaces>/<Namespace>

<Namespaces>
   <Namespace prefix="apigee">http://www.apigee.com</Namespace>
</Namespaces>

Attributs

Élément <XMLPayload>/<XPath>

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>

Élément <XMLPayload>/<XPath>/<Expression>

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>

É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>

É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>

É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>

Attributs

É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>

É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>

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.

Erreurs de déploiement

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.

Schémas

Articles associés

Règle de protection contre les menaces JSON

Règle de protection contre les menaces XML