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.

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha	Estado de HTTP	Causa	Corrigir
steps.xmlthreatprotection.ExecutionFailed	500	A política de XMLThreatProtection pode gerar muitos tipos diferentes de erros de ExecutionFailed. A maioria destes erros ocorre quando é excedido um limite específico definido na política. Estes tipos de erros incluem: comprimento do nome do elemento, contagem de filhos, profundidade do nó, contagem de atributos, comprimento do nome do atributo, e muitos outros. Pode ver a lista completa no tópico Resolução de problemas de erros de tempo de execução da política XMLThreatProtection.
steps.xmlthreatprotection.InvalidXMLPayload	500	Este erro ocorre se a carga útil da mensagem de entrada especificada pelo elemento <Source> da política XMLThreatProtection não for um documento XML válido.
steps.xmlthreatprotection.SourceUnavailable	500	Este erro ocorre se a variável message especificada no elemento <Source> for: Fora do âmbito (não disponível no fluxo específico onde a política está a ser executada) Não é um dos valores válidos request, response, ou message
steps.xmlthreatprotection.NonMessageVariable	500	Este erro ocorre se o elemento <Source> estiver definido para uma variável que não seja do tipo message.

Erros de implementação

Nenhum.

Variáveis de falha

Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme indicado na tabela Erros de tempo de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "SourceUnavailable"
xmlattack.policy_name.failed	policy_name é o nome especificado pelo utilizador da política que gerou a falha.	xmlattack.XPT-SecureRequest.failed = true

Exemplo de resposta de erro

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque pode mudar.

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

Exemplo de regra de falha

<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