Règle XMLThreatProtection

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Quoi

Corrigez les failles XML et minimisez les attaques contre votre API. Vous pouvez également détecter les attaques basées sur la charge utile XML en fonction des limites configurées. Filtrez les menaces XML à l'aide des approches suivantes :

• Évaluer le contenu des messages en fonction de mots clés ou de modèles spécifiques à exclure
• Détecter les messages corrompus ou présentant un format incorrect avant leur analyse

Remarque : Cette règle ne s'exécute que si le champ Content-Type de l'en-tête de la requête ou de la réponse est défini sur application/xml.

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.

Regarder une courte vidéo sur la protection contre les menaces

Vidéo : Regardez une courte vidéo sur les règles de protection contre les menaces figurant dans la série de vidéos de quatre minutes dédiée aux développeurs (4MV4D).

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

<XMLThreatProtection async="false" continueOnError="false" enabled="true" name="XML-Threat-Protection-1">
   <DisplayName>XML Threat Protection 1</DisplayName>
   <NameLimits>
      <Element>10</Element>
      <Attribute>10</Attribute>
      <NamespacePrefix>10</NamespacePrefix>
      <ProcessingInstructionTarget>10</ProcessingInstructionTarget>
   </NameLimits>
   <Source>request</Source>
   <StructureLimits>
      <NodeDepth>5</NodeDepth>
      <AttributeCountPerElement>2</AttributeCountPerElement>
      <NamespaceCountPerElement>3</NamespaceCountPerElement>
      <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
   </StructureLimits>
   <ValueLimits>
      <Text>15</Text>
      <Attribute>10</Attribute>
      <NamespaceURI>10</NamespaceURI>
      <Comment>10</Comment>
      <ProcessingInstructionData>10</ProcessingInstructionData>
   </ValueLimits> 
</XMLThreatProtection>

Attributs <XMLThreatProtection>

<XMLThreatProtection async="false" continueOnError="false" enabled="true" name="XML-Threat-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 name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.	N/A	Obligatoire
continueOnError	Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également : Les règles d'erreur sont déclenchées UNIQUEMENT en état d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel	false	Facultatif
enabled	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.	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 name de la règle est utilisée.
Presence	Facultatif
Type	Chaîne

Élément <NameLimits>

Spécifie le nombre maximal de caractères à vérifier et à appliquer par la règle.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>

Valeur par défaut :	N/A
Présence :	Facultatif
Type :	N/A

Élément <NameLimits>/<Element>

Spécifie le nombre maximal de caractères autorisés dans un nom d'élément dans le document XML.

Prenons l'exemple du document XML suivant :

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <Element> dans l'extrait de règle ci-dessous vérifie que les noms d'élément (book, title, author et year)) ne dépassent pas 10 caractères.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <NameLimits>/<Attribute>

Spécifie le nombre maximal de caractères autorisés dans un nom d'attribut dans le document XML.

Prenons l'exemple du document XML suivant :

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <Attribute> dans l'extrait de règle ci-dessous vérifie que le nom d'attribut category ne dépasse pas 10 caractères.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <NameLimits>/<NamespacePrefix>

Spécifie le nombre maximal de caractères autorisé dans le préfixe d'espace de noms dans le document XML.

Prenons l'exemple du document XML suivant :

<ns1:myelem xmlns:ns1="http://ns1.com"/>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <NamespacePrefix> dans l'extrait de règle ci-dessous vérifie que le préfixe d'espace de noms ns1 ne dépasse pas 10 caractères.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <NameLimits>/<ProcessingInstructionTarget>

Spécifie le nombre maximal de caractères autorisés dans la cible d'instructions de traitement dans le document XML.

Prenons l'exemple du document XML suivant :

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <ProcessingInstructionTarget> dans l'extrait de règle ci-dessous vérifie que la cible d'instructions de traitement xml-stylesheet ne dépasse pas 10 caractères.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <Source>

Message dans lequel rechercher les attaques de charges utiles XML. Ce paramètre est habituellement défini sur request, car vous devez généralement valider les requêtes entrantes provenant des applications clientes. Lorsque ce paramètre est défini sur message, cet élément évalue automatiquement le message de requête lorsqu'il est associé au flux de la requête et le message de réponse lorsqu'il est associé au flux de réponse.

<Source>request</Source>

Valeur par défaut :	requête
Présence :	Facultatif
Type :	Chaîne. Sélectionnez request, response ou message.

Élément <StructuralLimits>

Spécifie les limites structurelles à vérifier et à appliquer par la règle.

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>

Valeur par défaut :	N/A
Présence :	Facultatif
Type :	N/A

Élément <StructuralLimits>/<NodeDepth>

Spécifie la profondeur de nœud maximale autorisée dans le document XML.

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <StructuralLimits>/<AttributeCountPerElement>

Indique le nombre maximal d'attributs autorisés pour un élément.

Prenons l'exemple du document XML suivant :

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <AttributeCountPerElement> dans l'extrait de règle ci-dessous vérifie que les éléments book, title, author et year ne possèdent pas plus de 2 attributs chacun. Notez que les attributs utilisés pour définir les espaces de noms ne sont pas comptabilisés.

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <StructuralLimits>/<NameSpaceCountPerElement>

Spécifie le nombre maximal de définitions d'espaces de noms autorisées pour un élément.

Prenons l'exemple du document XML suivant :

<e1 attr1="val1" attr2="val2">
    <e2 xmlns="http://apigee.com" xmlns:yahoo="http://yahoo.com" one="1" yahoo:two="2"/>
</e1>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <NamespaceCountPerElement> dans l'extrait de règle ci-dessous vérifie que les éléments e1 et e2 ne possèdent pas plus de 2 définitions d'espaces de noms chacun. Dans ce cas, <e1> ne contient aucune définition d'espace de noms, et <e2> possède deux définitions d'espace de noms : xmlns="http://apigee.com" et xmlns:yahoo="http://yahoo.com".

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <StructuralLimits>/<ChildCount>

Spécifie le nombre maximal d'éléments enfants autorisés pour un élément.

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Attributs

Attribut	Par défaut	Presence
includeComment	true	Facultatif
includeElement	true	Facultatif
includeProcessingInstructions	true	Facultatif
includeText	true	Facultatif

Élément <ValueLimits>

Spécifie le nombre maximal de caractères pour les valeurs à vérifier et à appliquer par la règle.

<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>

Valeur par défaut :	N/A
Présence :	Facultatif
Type :	N/A

Élément <ValueLimits>/<Text>

Indique le nombre maximal de caractères pour les nœuds de texte présents dans le document XML.

Prenons l'exemple du document XML suivant :

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <Text> dans l'extrait de règle ci-dessous vérifie que les valeurs d'élément de texte Learning XML, Erik T. Ray, et 2003 ne dépassent pas 15 caractères chacune.

<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <ValueLimits>/<Attribute>

Spécifie le nombre maximal de caractères pour les valeurs d'attributs présentes dans le document XML.

Prenons l'exemple du document XML suivant :

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <Attribute> dans l'extrait de règle ci-dessous vérifie que la valeur d'attribut WEB ne dépasse pas 10 caractères.

<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <ValueLimits>/<NamespaceURI>

Spécifie le nombre maximal de caractères pour les URI d'espace de noms présents dans le document XML.

Prenons l'exemple du document XML suivant :

<ns1:myelem xmlns:ns1="http://ns1.com"/>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <NamespaceURI> dans l'extrait de règle ci-dessous vérifie que la valeur d'URI d'espace de noms http://ns1.com ne dépasse pas 10 caractères.

<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <ValueLimits>/<Comment>

Définit le nombre maximal de caractères pour les commentaires du document XML.

Prenons l'exemple du document XML suivant :

<book category="WEB">
   <!-- This is a comment -->
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <Comment> dans l'extrait de règle ci-dessous vérifie que le texte de commentaire This is a comment ne dépasse pas 10 caractères.

<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <ValueLimits>/<ProcessingInstructionData>

Spécifie le nombre maximal de caractères pour le texte d'instruction de traitement présent dans le document XML.

Prenons l'exemple du document XML suivant :

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

Lors de l'analyse du document XML ci-dessus, la valeur de l'élément <ProcessingInstructionData> dans l'extrait de règle ci-dessous vérifie que le texte d'instruction de traitement type="text/xsl" href="style.xsl" ne dépasse pas 10 caractères.

<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>

Valeur par défaut :	Si vous ne spécifiez pas de limite, le système applique une valeur par défaut de -1, qui signifie qu'il n'y a aucune limite.
Présence :	Facultatif
Type :	Entier

Informations de référence sur les erreurs

Remarque : Cette règle ne s'exécute que si le champ Content-Type de la requête ou de l'en-tête de réponse est défini sur application/xml..

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies 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. 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	État HTTP	Cause	Corriger
steps.xmlthreatprotection.ExecutionFailed	500	La règle XMLThreatProtection peut générer de nombreux types d'erreurs ExecutionFailed. La plupart de ces erreurs se produisent lorsqu'un seuil spécifique défini dans la règle est dépassé. Ces types d'erreurs incluent les éléments suivants : longueur de nom d'élément, nombre d'enfants, profondeur de nœud, nombre d'attributs, longueur de nom d'attribut, et bien d'autres. Vous pouvez consulter la liste complète dans la section XMLThreatProtection policy runtime error troubleshooting.
steps.xmlthreatprotection.InvalidXMLPayload	500	Cette erreur se produit si la charge utile du message d'entrée spécifié par l'élément XMLThreatProtection de la règle <Source> n'est pas un document XML valide.
steps.xmlthreatprotection.SourceUnavailable	500	Cette erreur se produit si la variable message spécifiée dans l'élément <Source> : est hors de portée (non disponible dans le flux spécifique où la règle est exécutée) n'est pas une des valeurs valides request, response ou message.
steps.xmlthreatprotection.NonMessageVariable	500	Cette erreur se produit si l'élément <Source> est défini sur une variable qui n'est pas de type message.

Erreurs de déploiement

Aucune.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables	Lieu	Exemple
fault.name="fault_name"	fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur.	fault.name Matches "SourceUnavailable"
xmlattack.policy_name.failed	policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	xmlattack.XPT-SecureRequest.failed = true

Exemple de réponse d'erreur

Remarque : Pour le traitement des erreurs, la meilleure pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

{
  "fault": {
    "faultstring": "XMLThreatProtection[XPT-SecureRequest]: Execution failed. reason: XMLThreatProtection[XTP-SecureRequest]: Exceeded object entry name length at line 2",
    "detail": {
      "errorcode": "steps.xmlthreatprotection.ExecutionFailed"
    }
  }
}

Exemple de règle de défaillance

<FaultRule name="XML Threat Protection Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ExecutionFailed") </Condition>
    </Step>
    <Condition>(xmlattack.XPT-SecureRequest.failed = true) </Condition>
</FaultRule>

Schémas

Exemple : consultez les exemples de dépôt GitHub pour visualiser les schémas les plus récents.

Remarques sur l'utilisation

Tout serveur qui reçoit des données en ligne est sujet à des attaques, qu'elles soient malveillantes ou non intentionnelles. Certaines attaques profitent de la flexibilité du langage XML en créant des documents non valides susceptibles de compromettre les systèmes backend. Les documents XML corrompus ou très complexes peuvent amener les serveurs à allouer plus de mémoire que la quantité disponible, ce qui épuise les ressources de processeur et de mémoire, ralentit les analyseurs de plantage et, généralement, désactive le traitement des messages et génère des attaques par déni de service au niveau des applications.

Configuration des erreurs de protection contre les menaces

Informations importantes si vous créez des règles FaultRules pour cette stratégie : Par défaut, Apigee génère un code d'état HTTP 500 indiquant une erreur interne du serveur et un code d'erreur ExecutionFailed si un message ne respecte pas une règle de protection contre les menaces JSON ou XML. Vous pouvez modifier ce comportement en utilisant une nouvelle propriété au niveau de l'organisation. Lorsque vous définissez la propriété d'organisation features.isPolicyHttpStatusEnabled sur "true", le comportement suivant se produit :

• Requête : avec une règle de protection contre les menaces associée à un flux de requêtes, les messages non valides renvoient un code d'état de requête incorrecte 400, ainsi qu'un code d'erreur de règle correspondant (plutôt que ExecutionFailed simplement).
• Réponse : avec une règle de protection contre les menaces associée à un flux de réponses, les messages non valides renvoient toujours un code d'état d'erreur interne du serveur 500, et l'un des codes d'erreur de règle correspondants est généré (plutôt que ExecutionFailed simplement).

Les clients Cloud doivent contacter Google Cloud Customer Care pour définir la propriété d'organisation.

Avertissement  Lorsque vous effectuez une opération PUT pour mettre à jour les propriétés de l'organisation, veillez à inclure toutes les propriétés existantes dans l'appel pour éviter de les supprimer.

curl -u email:password -X POST -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Environments/>
    <Properties>
        <Property name="features.isPolicyHttpStatusEnabled">true</Property>
        ...
    </Properties>
</Organization>"

Articles associés

Règle de protection contre les menaces JSON

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