Política XMLThreatProtection

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

O quê

Resolva vulnerabilidades XML e minimize os ataques à sua API. Opcionalmente, detete ataques de payload XML com base nos limites configurados. Proteja-se contra ameaças XML através das seguintes abordagens:

• Avalie o conteúdo das mensagens para excluir palavras-chave ou padrões específicos
• Detetar mensagens danificadas ou com formato incorreto antes de serem analisadas

Nota: esta política é executada apenas se o Content-Type do cabeçalho do pedido ou da resposta estiver definido como application/xml.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Veja um breve vídeo sobre a proteção contra ameaças

Vídeo: veja um breve vídeo sobre as políticas de proteção contra ameaças da série Four-minute Videos for Developers (4MV4D).

Referência do elemento

A referência do elemento descreve os elementos e os atributos da política 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>

Atributos <XMLThreatProtection>

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

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
async	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

<DisplayName>Policy Display Name</DisplayName>

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elemento <NameLimits>

Especifica os limites de carateres a serem verificados e aplicados pela política.

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

Predefinição:	N/A
Presença:	Opcional
Tipo:	N/A

Elemento <NameLimits>/<Element>

Especifica um limite para o número máximo de carateres permitidos em qualquer nome de elemento no documento XML.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <Element> no fragmento de código da política abaixo valida se os nomes dos elementos (book, title, author e year)) não excedem 10 carateres.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <NameLimits>/<Attribute>

Especifica um limite para o número máximo de carateres permitidos em qualquer nome de atributo no documento XML.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <Attribute> no fragmento de política abaixo valida que o nome do atributo category não excede 10 carateres.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <NameLimits>/<NamespacePrefix>

Especifica um limite para o número máximo de carateres permitidos no prefixo do espaço de nomes no documento XML.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <NamespacePrefix> no fragmento de código da política abaixo valida que o prefixo do espaço de nomes ns1 não excede 10 carateres.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <NameLimits>/<ProcessingInstructionTarget>

Especifica um limite para o número máximo de carateres permitidos no destino de quaisquer instruções de processamento no documento XML.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <ProcessingInstructionTarget> no fragmento da política abaixo valida que o destino da instrução de processamento xml-stylesheet não excede 10 carateres.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <Source>

Mensagem a ser analisada quanto a ataques de payload XML. Normalmente, esta opção está definida como request, uma vez que, normalmente, tem de validar os pedidos recebidos de apps de cliente. Quando definido como message, este elemento avalia automaticamente a mensagem de pedido quando anexada ao fluxo de pedido e a mensagem de resposta quando anexada ao fluxo de resposta.

<Source>request</Source>

Predefinição:	pedido
Presença:	Opcional
Tipo:	String. Selecione request, response ou message.

Elemento <StructuralLimits>

Especifica os limites estruturais a serem verificados e aplicados pela política.

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

Predefinição:	N/A
Presença:	Opcional
Tipo:	N/A

Elemento <StructuralLimits>/<NodeDepth>

Especifica a profundidade máxima do nó permitida no XML.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <StructuralLimits>/<AttributeCountPerElement>

Especifica o número máximo de atributos permitidos para qualquer elemento.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <AttributeCountPerElement> no fragmento de política abaixo valida que os elementos book, title, author e year não têm mais de 2 atributos cada. Tenha em atenção que os atributos usados para definir espaços de nomes não são contabilizados.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <StructuralLimits>/<NameSpaceCountPerElement>

Especifica o número máximo de definições de espaço de nomes permitidas para qualquer elemento.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <NamespaceCountPerElement> no fragmento de política abaixo valida que os elementos e1 e e2 não têm mais de 2 definições de espaço de nomes cada. Neste caso, <e1> tem 0 definições de espaço de nomes e <e2> tem 2 definições de espaço de nomes: 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>

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <StructuralLimits>/<ChildCount>

Especifica o número máximo de elementos secundários permitidos para qualquer elemento.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Atributos

Atributo	Predefinição	Presença
includeComment	verdadeiro	Opcional
includeElement	verdadeiro	Opcional
includeProcessingInstructions	verdadeiro	Opcional
includeText	verdadeiro	Opcional

Elemento <ValueLimits>

Especifica os limites de carateres para os valores a serem verificados e aplicados pela política.

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

Predefinição:	N/A
Presença:	Opcional
Tipo:	N/A

Elemento <ValueLimits>/<Text>

Especifica um limite de carateres para quaisquer nós de texto presentes no documento XML.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <Text> no fragmento de código da política abaixo valida que os valores de texto dos elementos Learning XML, Erik T. Ray, e 2003 não excedem 15 carateres cada.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <ValueLimits>/<Attribute>

Especifica um limite de carateres para quaisquer valores de atributos presentes no documento XML.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <Attribute> no fragmento da política abaixo valida que o valor do atributo WEB não excede 10 carateres.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <ValueLimits>/<NamespaceURI>

Especifica um limite de carateres para todos os URIs de espaço de nomes presentes no documento XML.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <NamespaceURI> no fragmento de código da política abaixo vai validar se o valor do URI do espaço de nomes http://ns1.com não excede 10 carateres.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <ValueLimits>/<Comment>

Especifica um limite de carateres para quaisquer comentários presentes no documento XML.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <Comment> no fragmento de código da política abaixo valida que o texto do comentário This is a comment não excede 10 carateres.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Elemento <ValueLimits>/<ProcessingInstructionData>

Especifica um limite de carateres para qualquer texto de instrução de processamento presente no documento XML.

Por exemplo, considere o seguinte XML:

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

Ao analisar o XML acima, o valor do elemento <ProcessingInstructionData> no fragmento de política abaixo vai validar se o texto da instrução de processamento type="text/xsl" href="style.xsl" não excede 10 carateres.

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

Predefinição:	Se não especificar um limite, o sistema aplica um valor predefinido de -1, que o sistema considera como nenhum limite.
Presença:	Opcional
Tipo:	Número inteiro

Referência de erro

Nota: esta política é executada apenas se o Content-Type do cabeçalho do pedido ou da resposta estiver definido como 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>

Esquemas

Exemplo: consulte os exemplos do nosso repositório do GitHub para ver os esquemas mais recentes.

Notas de utilização

Qualquer servidor que receba dados online está sujeito a ataques, sejam maliciosos ou não intencionais. Alguns ataques tiram partido da flexibilidade do XML através da criação de documentos inválidos que têm o potencial de comprometer os sistemas de back-end. Os documentos XML danificados ou extremamente complexos podem fazer com que os servidores aloquem mais memória do que a disponível, consumindo recursos de CPU e memória, bloqueando analisadores e, geralmente, desativando o processamento de mensagens e criando ataques de negação de serviço ao nível da aplicação.

Configuração de erro da proteção contra ameaças

Informações importantes se estiver a criar FaultRules para esta política: por predefinição, o Apigee gera um código de estado HTTP 500 Internal Server Error e um código de erro ExecutionFailed se uma mensagem não passar por uma política de proteção contra ameaças JSON ou XML. Pode alterar esse comportamento de erro com uma nova propriedade ao nível da organização. Quando define a propriedade org como verdadeira, ocorre o seguinte comportamento:features.isPolicyHttpStatusEnabled

• Pedido: com uma política de proteção contra ameaças anexada a qualquer fluxo de pedidos, as mensagens inválidas devolvem um código de estado 400 Pedido errado, juntamente com um código de erro de política correspondente (em vez de apenas ExecutionFailed).
• Resposta: com uma política de proteção contra ameaças anexada a qualquer fluxo de resposta, as mensagens inválidas continuam a devolver um código de estado 500 Internal Server Error, e é gerado um dos códigos de erro da política correspondentes (em vez de apenas ExecutionFailed).

Os clientes do Google Cloud têm de contactar o apoio técnico do Google Cloud para definir a propriedade da organização.

Aviso: quando fizer um PUT para atualizar as propriedades da organização, certifique-se de que inclui todas as propriedades existentes na chamada para evitar a respetiva eliminação.

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

Tópicos relacionados

Política de proteção contra ameaças JSON

Política de proteção de expressões regulares