Criterio XMLThreatProtection

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

Risolvi le vulnerabilità XML e riduci al minimo gli attacchi alla tua API. (Facoltativo) Rileva gli attacchi di payload XML in base ai limiti configurati. Esegui lo screening contro le minacce XML utilizzando i seguenti approcci:

• Valuta il contenuto del messaggio alla ricerca di parole chiave o pattern specifici da escludere
• Rilevare messaggi danneggiati o non validi prima che vengano analizzati

Nota: questo criterio viene eseguito solo se il Content-Type dell'intestazione della richiesta o della risposta è impostato su application/xml.

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Guarda un breve video sulla protezione dalle minacce

Video: guarda un breve video sulle norme di protezione dalle minacce della serie Video di 4 minuti per gli sviluppatori (4MV4D).

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi del criterio 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>

Attributi <XMLThreatProtection>

<XMLThreatProtection async="false" continueOnError="false" enabled="true" name="XML-Threat-Protection-1"> 

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	String

Elemento <NameLimits>

Specifica i limiti di caratteri da controllare e applicare in base alle norme.

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

Predefinito:	N/D
Presenza:	Facoltativo
Tipo:	N/D

Elemento <NameLimits>/<Element>

Specifica un limite al numero massimo di caratteri consentiti in qualsiasi nome di elemento nel documento XML.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <Element> nello snippet della norma riportato di seguito convalida che i nomi degli elementi (book, title, author e year)) non superino i 10 caratteri.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <NameLimits>/<Attribute>

Specifica un limite al numero massimo di caratteri consentiti in qualsiasi nome di attributo nel documento XML.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <Attribute> nello snippet della norma riportato di seguito convaliderà che il nome dell'attributo category non superi i 10 caratteri.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <NameLimits>/<NamespacePrefix>

Specifica un limite al numero massimo di caratteri consentiti nel prefisso dello spazio dei nomi nel documento XML.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <NamespacePrefix> nello snippet del criterio riportato di seguito convalida che il prefisso dello spazio dei nomi ns1 non superi i 10 caratteri.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <NameLimits>/<ProcessingInstructionTarget>

Specifica un limite al numero massimo di caratteri consentiti nella destinazione di qualsiasi istruzione di elaborazione nel documento XML.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <ProcessingInstructionTarget> nel snippet del criterio riportato di seguito convalida che la destinazione dell'istruzione di elaborazione xml-stylesheet non superi i 10 caratteri.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <Source>

Messaggio da analizzare per rilevare attacchi di payload XML. Questo valore è in genere impostato su request, poiché in genere devi convalidare le richieste in entrata dalle app client. Se impostato su message, questo elemento valuterà automaticamente il messaggio di richiesta quando è collegato al flusso di richiesta e il messaggio di risposta quando è collegato al flusso di risposta.

<Source>request</Source>

Predefinito:	richiesta
Presenza:	Facoltativo
Tipo:	Stringa. Scegli tra request, response o message.

Elemento <StructuralLimits>

Specifica i limiti strutturali da controllare e applicare in modo forzato dai criteri.

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

Predefinito:	N/D
Presenza:	Facoltativo
Tipo:	N/D

Elemento <StructuralLimits>/<NodeDepth>

Specifica la profondità massima del nodo consentita nell'XML.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <StructuralLimits>/<AttributeCountPerElement>

Specifica il numero massimo di attributi consentiti per qualsiasi elemento.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <AttributeCountPerElement> nello snippet di policy riportato di seguito convalida che gli elementi book, title, author e year non abbiano più di 2 attributi ciascuno. Tieni presente che gli attributi utilizzati per definire gli spazi dei nomi non vengono conteggiati.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <StructuralLimits>/<NameSpaceCountPerElement>

Specifica il numero massimo di definizioni di spazi dei nomi consentite per qualsiasi elemento.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <NamespaceCountPerElement> nel snippet della policy riportato di seguito convaliderà che gli elementi e1 e e2 non abbiano più di 2 definizioni di spazi dei nomi ciascuno. In questo caso, <e1> ha 0 definizioni di spazi dei nomi e <e2> ha 2 definizioni di spazi dei nomi: xmlns="http://apigee.com" e 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>

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

<StructuralLimits>/<ChildCount> elemento

Specifica il numero massimo di elementi secondari consentiti per qualsiasi elemento.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Attributi

Attributo	Predefinito	Presenza
includeComment	true	Facoltativo
includeElement	true	Facoltativo
includeProcessingInstructions	true	Facoltativo
includeText	true	Facoltativo

Elemento <ValueLimits>

Specifica i limiti di caratteri per i valori da controllare e applicare in modo forzato dalla policy.

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

Predefinito:	N/D
Presenza:	Facoltativo
Tipo:	N/D

Elemento <ValueLimits>/<Text>

Specifica un limite di caratteri per tutti i nodi di testo presenti nel documento XML.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <Text> nello snippet della policy riportato di seguito convaliderà che i valori di testo degli elementi Learning XML, Erik T. Ray, e 2003 non superino i 15 caratteri ciascuno.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <ValueLimits>/<Attribute>

Specifica un limite di caratteri per tutti i valori degli attributi presenti nel documento XML.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <Attribute> nello snippet del criterio riportato di seguito convalida che il valore dell'attributo WEB non superi i 10 caratteri.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <ValueLimits>/<NamespaceURI>

Specifica un limite di caratteri per gli URI dello spazio dei nomi presenti nel documento XML.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <NamespaceURI> nello snippet del criterio riportato di seguito convalida che il valore dell'URI dello spazio dei nomi http://ns1.com non superi i 10 caratteri.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <ValueLimits>/<Comment>

Specifica un limite di caratteri per i commenti presenti nel documento XML.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <Comment> nello snippet di policy riportato di seguito convaliderà che il testo del commento This is a comment non superi i 10 caratteri.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Elemento <ValueLimits>/<ProcessingInstructionData>

Specifica un limite di caratteri per qualsiasi testo di istruzioni di elaborazione presente nel documento XML.

Ad esempio, considera il seguente XML:

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

Quando analizzi l'XML riportato sopra, il valore dell'elemento <ProcessingInstructionData> nel frammento di policy riportato di seguito convaliderà che il testo dell'istruzione di elaborazione type="text/xsl" href="style.xsl" non superi i 10 caratteri.

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

Predefinito:	Se non specifichi un limite, il sistema applica un valore predefinito di -1, che il sistema considera come nessun limite.
Presenza:	Facoltativo
Tipo:	Numero intero

Messaggi di errore

Nota: questo criterio viene eseguito solo se l'Content-Type dell'intestazione della richiesta o della risposta è impostato su application/xml.

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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	Fix
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.

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>

Schemi

Esempio: consulta gli esempi del nostro repository GitHub per gli schemi più recenti.

Note sull'utilizzo

Qualsiasi server che riceve dati online è soggetto ad attacchi, intenzionali o meno. Alcuni attacchi sfruttano la flessibilità di XML creando documenti non validi che hanno il potenziale di compromettere i sistemi di backend. I documenti XML danneggiati o estremamente complessi possono far sì che i server allocchino più memoria di quella disponibile, occupando risorse di CPU e memoria, causando l'arresto anomalo dei parser e disattivando in generale l'elaborazione dei messaggi e creando attacchi DoS a livello di applicazione.

Configurazione degli errori di protezione dalle minacce

Informazioni importanti se stai creando FaultRules per questo criterio: per impostazione predefinita, Apigee genera un codice di stato HTTP 500 Internal Server Error e un codice di errore ExecutionFailed se un messaggio non supera un criterio di protezione dalle minacce JSON o XML. Puoi modificare questo comportamento di errore con una nuova proprietà a livello di organizzazione. Quando imposti la proprietà dell'organizzazione features.isPolicyHttpStatusEnabled su true, si verifica il seguente comportamento:

• Richiesta: con una policy di protezione dalle minacce allegata a qualsiasi flusso di richieste, i messaggi non validi restituiscono un codice di stato 400 Bad Request, insieme a un codice di errore della policy corrispondente (anziché solo ExecutionFailed).
• Risposta: con un criterio di protezione dalle minacce allegato a qualsiasi flusso di risposta, i messaggi non validi restituiscono comunque un codice di stato 500 Internal Server Error e viene generato uno dei codici di errore del criterio corrispondenti (anziché solo ExecutionFailed).

I clienti cloud devono contattare l'assistenza clienti Google Cloud per impostare la proprietà dell'organizzazione.

Avviso:quando esegui un'operazione PUT per aggiornare le proprietà dell'organizzazione, assicurati di includere tutte le proprietà esistenti nella chiamata per evitare di eliminarle.

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

Argomenti correlati

Policy di protezione dalle minacce JSON

Norme di protezione delle espressioni regolari