Cette page a été traduite par l'API Cloud Translation.

Règle XMLThreatProtection

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

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 :

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.

Valider les messages par rapport à un schéma XML (.xsd)
É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

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	Présence
`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.	ND	Valeur
`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.	faux	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.	vrai	Facultatif
`async`	Cet attribut est obsolète.	faux	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

Par défaut	ND Si vous omettez cet élément, la valeur de l'attribut `name` de la règle est utilisée.
Présence	Facultatif
Type	Chaîne

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.

Présence 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 :	ND
Présence :	Facultatif
Type :	ND

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

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 :	ND
Présence :	Facultatif
Type :	ND

É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 code XML ci-dessus, la valeur de l'élément <AttributeCountPerElement> dans l'extrait de règle ci-dessous confirmera que les éléments book, title, author et year ne comportent 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	Présence
includeComment	vrai	Facultatif
includeElement	vrai	Facultatif
includeProcessingInstructions	vrai	Facultatif
includeText	vrai	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 :	ND
Présence :	Facultatif
Type :	ND

É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 code XML ci-dessus, la valeur de l'élément <Text> dans la stratégie l'extrait ci-dessous vérifiera que les valeurs de texte des éléments 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 code XML ci-dessus, la valeur de l'élément <Attribute> dans la stratégie l'extrait de code ci-dessous permet de vérifier que la valeur de l'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 code XML ci-dessus, la valeur de l'élément <NamespaceURI> dans la section l'extrait de règle ci-dessous vérifiera que la valeur d'URI de l'espace de noms http://ns1.com ne pas dépasser 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 code XML ci-dessus, la valeur de l'élément <Comment> dans la stratégie l'extrait ci-dessous vérifiera que le texte du 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 code XML ci-dessus, l'élément <ProcessingInstructionData> dans l'extrait de règle ci-dessous permettra de vérifier que le texte de l'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 l'en-tête de la requête ou de la réponse est défini sur application/xml..

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.xmlthreatprotection.ExecutionFailed`	500	The XMLThreatProtection policy can throw many different types of ExecutionFailed errors. Most of these errors occur when a specific threshold set in the policy is exceeded. These types of errors include: element name length, child count, node depth, attribute count, attribute name length, and many others. You can see the complete list in the XMLThreatProtection policy runtime error troubleshooting topic.
`steps.xmlthreatprotection.InvalidXMLPayload`	500	This error occurs if the input message payload specified by the XMLThreatProtection policy's `<Source>` element is not a valid XML Document.
`steps.xmlthreatprotection.SourceUnavailable`	500	This error occurs if the message variable specified in the `<Source>` element is either: Out of scope (not available in the specific flow where the policy is being executed) Is not one of the valid values `request`, `response`, or `message`
`steps.xmlthreatprotection.NonMessageVariable`	500	This error occurs if the `<Source>` element is set to a variable which is not of type message.

Notes:

The error name ExecutionFailed is the default error name and will be returned regardless of the type of error detected; however, this default can be changed by setting an organization-level property. When this property is set, the error name will reflect the actual error. For example, "TextExceeded" or "AttrValueExceeded". See Usage Notes for details.
The 500 HTTP status is the default; however, the HTTP Status can be changed to 400 for request flow faults by setting an organization-level property. See Usage Notes for details.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "SourceUnavailable"`
`xmlattack.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`xmlattack.XPT-SecureRequest.failed = true`

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

<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

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 par défaut, Edge génère un code d'état d'erreur interne du serveur HTTP 500 et une erreur ExecutionFailed si un message n'arrive pas au-delà d'une stratégie 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 de serveur interne 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 l'assistance Apigee Edge pour définir la la propriété d'organisation.

Articles associés

Règle de protection contre les menaces JSON

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