Política XMLThreatProtection

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Conteúdo

Solucione vulnerabilidades XML e minimize os ataques na API. Opcionalmente, detecte ataques de payload XML com base nos limites configurados. Proteja-se contra ameaças XML usando as seguintes abordagens:

• Avalie o conteúdo da mensagem com palavras-chave ou padrões específicos a serem excluídos.
• Detecte mensagens corrompidas ou malformadas antes de analisá-las.

Observação: essa política será executada somente se o Content-Type do cabeçalho de solicitação ou resposta estiver definido como application/xml.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Assista um vídeo curto sobre proteção contra ameaças

Vídeo: assista a um breve vídeo sobre políticas de proteção contra ameaças da série Vídeos de quatro minutos para desenvolvedores (4MV4D).

Referência de elemento

A referência de elemento descreve os elementos e 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 de <XMLThreatProtection>

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

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo	Descrição	Padrão	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir 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 será aplicada mesmo se ela permanecer anexada a um fluxo.	true	Opcional
async	Esse atributo está obsoleto.	falso	Obsoleto

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elemento <NameLimits>

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

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

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

Elemento <NameLimits>/<Element>

Especifica o limite do número máximo de caracteres 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 snippet da política abaixo validará os nomes dos elementos (book , title, author e year)) não exceder 10 caracteres.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <NameLimits>/<Attribute>

Especifica o limite do número máximo de caracteres 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 snippet de política abaixo validará que o nome do atributo category não excede 10 caracteres.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <NameLimits>/<NamespacePrefix>

Especifica um limite para o número máximo de caracteres permitido no prefixo do namespace 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 snippet de política abaixo validará que o prefixo de namespace ns1 não excede 10 caracteres.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <NameLimits>/<ProcessingInstructionTarget>

Especifica um limite para o número máximo de caracteres permitido para qualquer instrução 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 snippet de política abaixo validará que o destino da instrução de processamento xml-stylesheet não excede 10 caracteres.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <Source>

Mensagem a ser filtrada para ataques de payload XML. Geralmente, isso é definido como request, porque normalmente será necessário validar as solicitações de entrada dos aplicativos cliente. Quando definido como message, esse elemento avalia automaticamente a mensagem de solicitação quando ele está anexado ao fluxo de solicitação e a mensagem de resposta quando anexado ao fluxo.

<Source>request</Source>

Padrão:	request
Presença:	Opcional
Tipo:	String. Selecione entre 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>

Padrã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>

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	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 snippet de política abaixo validará se os elementos book, title, author e year fazem ter mais de 2 atributos cada. Observe que os atributos usados para definir os namespaces não são contados.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <StructuralLimits>/<NameSpaceCountPerElement>

Especifica o número máximo de definições de namespace 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 snippet de política abaixo validará se os elementos e1 e e2 não têm mais de 2 definições de namespace cada. Nesse caso, <e1> tem 0 definições de namespace e <e2> tem duas definições de namespace: 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>

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <StructuralLimits>/<ChildCount>

Especifica o número máximo de elementos filhos 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>

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Atributos

Atributo	Padrão	Presença
includeComment	true	Opcional
includeElement	true	Opcional
includeProcessingInstructions	true	Opcional
includeText	true	Opcional

Elemento <ValueLimits>

Especifica os limites de caracteres 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>

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

Elemento <ValueLimits>/<Text>

Especifica um limite de caracteres para qualquer nó de texto presente 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 snippet de política abaixo validará que os valores de texto do elemento Learning XML, Erik T. Ray, e 2003 não excedem 15 caracteres cada.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <ValueLimits>/<Attribute>

Especifica um limite de caracteres para quaisquer valores de atributo 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 snippet de política abaixo valida que o valor do atributo WEB não excede 10 caracteres.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <ValueLimits>/<NamespaceURI>

Especifica um limite de caracteres para os URIs de namespace 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 snippet de política abaixo validará que o valor de URI do namespace http://ns1.com não excede 10 caracteres.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <ValueLimits>/<Comment>

Especifica um limite de caracteres para os 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 snippet de política abaixo validará que o texto do comentário This is a comment não excede 10 caracteres.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Elemento <ValueLimits>/<ProcessingInstructionData>

Especifica um limite de caracteres 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 snippet de política abaixo validará que o texto da instrução de processamento type="text/xsl" href="style.xsl" não excede 10 caracteres.

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

Padrão:	Se você não especificar um limite, o sistema aplicará um valor padrão de -1, que o sistema equivale a não limitar.
Presença:	Opcional
Tipo:	Inteiro

Referência de erros

Observação: essa política será executada somente se o Content-Type do cabeçalho de solicitação ou resposta estiver definido como application/xml.

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

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

Código de falha	Status HTTP	Causa	Correção
steps.xmlthreatprotection.ExecutionFailed	500	A política XMLThreatProtection pode gerar vários tipos diferentes de erros ExecutionFailed. A maioria desses erros ocorre quando um limite específico definido na política é excedido. Esses 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. Veja a lista completa no tópico Solução de problemas da política XMLThreatProtection.
steps.xmlthreatprotection.InvalidXMLPayload	500	Esse erro ocorre se o payload da mensagem de entrada especificado pelo elemento XMLThreatProtection da política <Source> não for um documento XML válido.
steps.xmlthreatprotection.SourceUnavailable	500	Esse erro ocorrerá se a variável message especificada no elemento <Source> for: Fora do escopo (não disponível no fluxo específico em que a política está sendo executada) Não for um dos valores válidos request, response ou message
steps.xmlthreatprotection.NonMessageVariable	500	Esse erro ocorrerá se o elemento <Source> estiver definido como uma variável que não é do tipo message.

Erros na implantação

Nenhum.

Variáveis de falha

Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme listado na tabela Erros de ambiente 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 usuário da política que causou a falha.	xmlattack.XPT-SecureRequest.failed = true

Exemplo de resposta de erro

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele 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

Amostra: veja nossas amostras de repositório do GitHub para os esquemas mais recentes.

Observações sobre uso

Qualquer servidor que recebe dados on-line está sujeito a ataque, seja malicioso ou não. Alguns ataques aproveitam a flexibilidade do XML ao criar documentos inválidos que podem comprometer sistemas de back-end. Documentos XML corrompidos ou extremamente complexos podem fazer com que os servidores aloquem mais memória do que disponível, adicionando recursos de CPU e memória, falhas de análise e, geralmente, desativando o processamento de mensagens e criando ataques de negação de serviço no nível dos aplicativos.

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

Informações importantes se você estiver criando FaultRules para essa política: por padrão, a Apigee gera um código de status HTTP 500, "Erro de servidor interno" e um código de erro "ExecutionFailed", caso uma mensagem não a tenha passar por uma política de proteção contra ameaças JSON ou XML. É possível alterar esse comportamento de erro com uma nova propriedade no nível da organização. Ao definir a propriedade organizacional features.isPolicyHttpStatusEnabled como "true", o seguinte comportamento ocorre:

• Solicitação: com uma política de proteção contra ameaças anexada a qualquer fluxo de solicitação, mensagens inválidas retornam um código de status 400 400 Solicitação de solicitação 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 respostas, mensagens inválidas ainda retornam o código de status "500 Internal Server Error", e um dos códigos de erro de política correspondentes é gerado (em vez de do que apenas ExecutionFailed).

Os clientes do Cloud precisam entrar em contato com o Suporte da Apigee para definir a propriedade da organização.

Aviso: ao fazer uma solicitação PUT para atualizar as propriedades da organização, inclua todas as propriedades existentes na chamada para impedir a exclusão delas.

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

Temas relacionados

Política JSONThreatProtection

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