Política RegularExpressionProtection

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

Veja a documentação do Apigee Edge.

Ícone de política

O quê

Extrai informações de uma mensagem (por exemplo, caminho do URI, parâmetro de consulta, cabeçalho, parâmetro de formulário, variável, payload XML ou payload JSON) e avalia esse conteúdo em função de expressões regulares predefinidas. Se alguma das expressões regulares especificadas for avaliada como verdadeira, a mensagem é considerada uma ameaça e a política gera uma falha.

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.

Vídeos

Veja o vídeo seguinte para saber mais sobre a Política de Proteção de Expressões Regulares.

Vídeo Descrição
Proteger-se contra ataques de injeção SQL Proteja-se contra ataques de injeção SQL através da política de proteção de expressões regulares na IU do Apigee.

Amostras

GitHub

O exemplo de regex-protection no GitHub ilustra como interceptar potenciais ataques de injeção SQL emitidos através de um parâmetro de consulta que pode conter código malicioso numa etiqueta <script>. O exemplo também ilustra uma prática recomendada de definir um estado de erro genérico 400 para impedir que os hackers obtenham informações úteis da resposta.

Proteção contra ataques de inclusão de JavaScript

<RegularExpressionProtection name="JsonPathRegExProtection">
    <Source>request</Source>
    <JSONPayload escapeSlashCharacter="true">
       <JSONPath>
          <Expression>$</Expression>
          <Pattern><![CDATA[ <\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*> ]]></Pattern>
       </JSONPath>
    </JSONPayload>
 </RegularExpressionProtection>

O exemplo acima ilustra como usar a política RegularExpressionProtection para avaliar payloads JSON quanto a ataques de inclusão de JavaScript. Especificamente, o conteúdo extraído por <JSONPath>/<Expression> é avaliado relativamente à expressão regular em <JSONPath>/<Pattern>.

Se a expressão regular no seu elemento <JSONPath>/<Pattern> incluir carateres reservados em XML (", &, ', < ou >), tem de incluí-la numa secção CDATA (dados de carateres), conforme mostrado no exemplo acima, ou codificar em XML os carateres reservados: por exemplo, substituindo < por &lt; e > por &gt;.

Além disso, se a sua expressão regular incluir barras (/), tem de as escapar definindo o atributo <JSONPayload> escapeSlashCharacter como true.

Correspondência que não é sensível a maiúsculas e minúsculas

É um exemplo de utilização comum fazer a correspondência não sensível a maiúsculas e minúsculas. Segue-se um exemplo de como pode fazer isso numa expressão regular usando a construção (?i). Neste exemplo, por exemplo, DELETE, delete e Delete são avaliados como verdadeiros.

<Pattern>[\s]*(?i)((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))</Pattern>

Verificações de parâmetros de formulário

<RegularExpressionProtection name="REP-Formparam">
  <Source>request</Source>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <FormParam name="firstname">
    <Pattern><![CDATA[[-+=$%&]]]></Pattern>
  </FormParam>
  <FormParam name="lastname">
    <Pattern><![CDATA[[-+=$%&]]]></Pattern>
  </FormParam>
</RegularExpressionProtection>

Esta configuração da política RegularExpressionProtection avalia os parâmetros do formulário quanto à ocorrência de carateres especiais no conjunto [-+=$%&]. Esta política só tem efeito quando o cabeçalho content-type no pedido é application/x-www-form-urlencoded. A configuração da política usa uma secção CDATA (dados de carateres) para envolver as expressões regulares, devido à presença do carater &, que é especial em XML.


Acerca da Política de Proteção de Expressões Regulares

O Apigee permite-lhe configurar expressões regulares que podem ser avaliadas em relação ao tráfego da API no momento da execução para identificar ameaças comuns ao nível do conteúdo que seguem determinados padrões.

Uma expressão regular, ou regex, é um conjunto de strings que especificam um padrão numa string. As expressões regulares permitem que o conteúdo seja avaliado programaticamente quanto a padrões. As expressões regulares podem ser usadas, por exemplo, para avaliar um endereço de email para garantir que está estruturado corretamente. Para mais informações, consulte o artigo Expressões regulares nos tutoriais de Java.

A utilização mais comum da RegularExpressionProtection é a avaliação de payloads JSON e XML para conteúdo malicioso.

Nenhuma expressão regular pode eliminar todos os ataques baseados em conteúdo, e devem ser combinados vários mecanismos para ativar a defesa em profundidade. Esta secção descreve alguns padrões recomendados para excluir conteúdo.

Exemplos de padrões de exclusão

As expressões regulares têm de ser codificadas em XML no ficheiro de configuração XML da política. Consulte também o Antipattern: Use greedy quantifiers in the RegularExpressionProtection policy.

Nome Expressão regular
Injeção SQL
[\s]*((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))
Injeção de inclusão do lado do servidor
<!--#(include|exec|echo|config|printenv)\s+.*

Codificado em XML:

&lt;!--#(include|exec|echo|config|printenv)\s+.*
Injeção de sintaxe abreviada XPath
(/(@?[\w_?\w:\*]+(\[[^]]+\])*)?)+
Injeção de sintaxe expandida do XPath
/?(ancestor(-or-self)?|descendant(-or-self)?|following(-sibling))
Injeção de JavaScript
<\s*script\b[^>]*>[^<]+<\s*/\s*script\s*>

Codificado em XML:

&lt;\s*script\b[^&gt;]*&gt;[^&lt;]+&lt;\s*/\s*script\s*&gt;

Defina o cabeçalho Content-Type num pedido com um payload XML ou JSON

A carga útil da política de proteção de expressões regulares pode incluir os seguintes elementos:

  • <XMLPayload>: especifica que as informações têm de ser extraídas de uma carga útil XML e avaliadas em função da expressão regular fornecida.

    Se usar <XMLPayload> na política, o cabeçalho Content-Type do pedido tem de ser um tipo de conteúdo XML, como application/xml ou text/xml.

  • Elemento <JSONPayload>: especifica que as informações têm de ser extraídas de um payload JSON e avaliadas em função da expressão regular fornecida.

    Se usar <JSONPayload> na política, o cabeçalho Content-Type do pedido tem de ser um tipo de conteúdo JSON, como application/json.

Normalmente, cria uma API para aceitar XML ou JSON. No entanto, pode haver um cenário em que a API aceitou ambos. Em seguida, pode definir uma política de proteção de expressões regulares que use os elementos <XMLPayload> e <JSONPayload>. Apenas um elemento seria aplicado a um pedido específico com base no valor do cabeçalho Content-Type.

Referência do elemento

A referência do elemento descreve os elementos e os atributos da política RegularExpressionProtection.

<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-Protection-1">
   <DisplayName>Regular Expression Protection 1</DisplayName>
   <Source>response</Source>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <URIPath>
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </URIPath>
   <QueryParam name="a-query-param">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </QueryParam>
   <Header name="a-header">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </Header>
   <FormParam name="a-form-param">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </FormParam>
   <Variable name="request.content">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </Variable>
   <XMLPayload>
     <Namespaces>
       <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     </Namespaces>
     <XPath>
       <Expression>/apigee:Greeting/apigee:User</Expression>
       <Type>string</Type>
       <Pattern>REGEX PATTERN</Pattern>
       <Pattern>REGEX PATTERN</Pattern>
     </XPath>
   </XMLPayload>
   <JSONPayload>
     <JSONPath>
       <Expression>$.store.book[*].author</Expression>
       <Pattern>REGEX PATTERN</Pattern>
       <Pattern>REGEX PATTERN</Pattern>
     </JSONPath>
    </JSONPayload>
</RegularExpressionProtection>

<RegularExpressionProtection> attributes

<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-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:

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

Indica a mensagem a partir da qual as informações têm de ser extraídas.

Se o elemento <Source> for omitido, o valor é predefinido como message. Por exemplo, <Source>message</Source>. Quando definida como message, a política usa a mensagem de pedido como origem quando anexada a um fluxo de pedido. Da mesma forma, a política usa a mensagem de resposta quando está anexada a um fluxo de resposta.

Se a mensagem de origem não puder ser resolvida ou se for resolvida para um tipo que não seja de mensagem, a política devolve um erro.

<Source>response</Source>
Predefinição: N/A
Presença: Opcional
Tipo: String

Elemento <IgnoreUnresolvedVariables>

Determina se a política devolve um erro quando encontra uma variável que não é resolvível.

Se estiver definida como false (predefinição), a política devolve um erro quando é encontrada uma variável não resolvível. Se estiver definido como true, a variável não resolvida é tratada como uma string vazia (nula).

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
Predefinição: falso
Presença: Opcional
Tipo: Booleano

Elemento <URIPath>

Especifica que as informações têm de ser extraídas do caminho do URI do pedido e avaliadas em função das expressões regulares fornecidas. Tem de fornecer, pelo menos, um elemento <Pattern> que especifique um padrão de expressão regular para corresponder.

<URIPath>
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</URIPath>
Predefinição: N/A
Presença: Opcional
Tipo: N/A

Elemento <QueryParam>

Especifica que as informações têm de ser extraídas do parâmetro de consulta do pedido e validadas em função das expressões regulares fornecidas. Tem de fornecer, pelo menos, um elemento <Pattern> que especifique um padrão de expressão regular para corresponder.

<QueryParam name="a-query-param">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</QueryParam>
Predefinição: N/A
Presença: Opcional
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença
nome Nome do parâmetro de consulta do pedido a partir do qual é necessário extrair informações para avaliação em relação às expressões regulares fornecidas. N/A Obrigatória

Elemento <Header>

Especifica que as informações têm de ser extraídas dos cabeçalhos de solicitação e resposta e avaliadas em função das expressões regulares fornecidas. Tem de fornecer, pelo menos, um elemento <Pattern> que especifique um padrão de expressão regular para corresponder.

<Header name="a-header">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</Header>
Predefinição: N/A
Presença: Opcional
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença
nome

Nome do cabeçalho de pedido e resposta do qual é necessário extrair informações para avaliação em função das expressões regulares fornecidas.

N/A Obrigatória

Elemento <FormParam>

Especifica que as informações têm de ser extraídas do parâmetro do formulário de pedido e avaliadas em função das expressões regulares fornecidas. Tem de fornecer, pelo menos, um elemento <Pattern> que especifique um padrão de expressão regular para corresponder.

<FormParam name="a-form-param">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</FormParam>
Predefinição: N/A
Presença: Opcional
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença
nome

Nome do parâmetro do formulário de pedido a partir do qual as informações têm de ser extraídas para avaliação em função das expressões regulares fornecidas.

N/A Obrigatória

Elemento <Variable>

Especifica que as informações têm de ser extraídas da variável fornecida e avaliadas em função das expressões regulares fornecidas.

<Variable name="request.content">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</Variable>
Predefinição: N/A
Presença: Opcional
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença
nome

Nome da variável a partir da qual as informações têm de ser extraídas para avaliação com base nas expressões regulares fornecidas.

N/A Obrigatória

Elemento <XMLPayload>

Especifica que as informações têm de ser extraídas de uma carga útil XML e avaliadas em função das expressões regulares fornecidas.

<XMLPayload>
   <Namespaces>
      <Namespace prefix="apigee">http://www.apigee.com</Namespace>
   </Namespaces>
   <XPath>
      <Expression>/apigee:Greeting/apigee:User</Expression>
      <Type>string</Type>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </XPath>
</XMLPayload>
Predefinição: N/A
Presença: Opcional
Tipo: N/A

Elemento <XMLPayload>/<Namespaces>

Especifica os espaços de nomes a usar na avaliação XPath.

<XMLPayload>
   <Namespaces>
      <Namespace prefix="apigee">http://www.apigee.com</Namespace>
   </Namespaces>
   <XPath>
      <Expression>/apigee:Greeting/apigee:User</Expression>
      <Type>string</Type>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </XPath>
</XMLPayload>
Predefinição: N/A
Presença: Opcional
Tipo: String

Elemento <XMLPayload>/<Namespaces>/<Namespace>

Especifica cada espaço de nomes a usar na avaliação do XPath.
<Namespaces>
   <Namespace prefix="apigee">http://www.apigee.com</Namespace>
</Namespaces>
Predefinição: N/A
Presença: Opcional
Tipo: String

Atributos

Atributo Descrição Predefinição Presença
prefixo

Fornece um prefixo para ajudar a qualificar um determinado espaço de nomes.

N/A Obrigatória

Elemento <XMLPayload>/<XPath>

Especifica o XPath a ser avaliado.
<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
Predefinição: N/A
Presença: Opcional
Tipo: N/A

<XMLPayload>/<XPath>/<Expression> element

Especifica a expressão XPath definida para a variável. Apenas são suportadas expressões XPath 1.0. Por exemplo, <Expression>/company/employee[@age>=$request.header.age]</Expression> extrai detalhes dos funcionários cuja idade é igual ou superior ao valor especificado em request.header.age.
<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
Predefinição: N/A
Presença: Opcional
Tipo: String

<XMLPayload>/<XPath>/<Type> element

Especifica o tipo de dados de saída pretendido.

Normalmente, usa "string" ou "nodeset". Use "string" se tiver a certeza de que a consulta xpath vai resultar, no máximo, num valor ou se quiser verificar, no máximo, um valor. Se a sua consulta XPath puder devolver vários valores, especifique "nodeset" para verificar todos os valores.

Por exemplo, considere a expressão XPath //*/@*. Corresponde a todos os atributos em todos os elementos. Se especificar "string" como Type, o Apigee vai converter o resultado desta consulta numa única string. Será o valor de um dos atributos num dos elementos no documento XML, mas não está definido que atributo e que elemento é. Em seguida, o Apigee realiza a correspondência de padrões com o valor apenas desse único atributo. Provavelmente, não é isto que quer.

Por outro lado, se especificar "nodeset" como o Type para essa expressão XPath, o Apigee vai realizar a correspondência de padrões com cada um dos valores dos atributos em cada elemento no documento XML.

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
Predefinição: de string
Presença: Opcional
Tipo: String
Valores válidos:

Uma destas palavras-chave: string, boolean, int, long, float, double e nodeset.

Elemento <XMLPayload>/<XPath>/<Pattern>

Define o padrão de expressão regular. Se uma expressão regular no elemento <Pattern> incluir carateres reservados em XML (", &, ', < ou .), tem de codificá-la em XML antes de a incluir.

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
Predefinição: N/A
Presença: Obrigatória
Tipo: String

Elemento <JSONPayload>

Especifica que as informações têm de ser extraídas de um payload JSON e avaliadas em função das expressões regulares fornecidas.

<JSONPayload>
   <JSONPath>
      <Expression>$.store.book[*].author</Expression>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </JSONPath>
</JSONPayload>
Predefinição: N/A
Presença: Opcional
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença
escapeSlashCharacter

Definido como true para escapar de quaisquer carateres de barra (/) nas expressões regulares em <JSONPath>/<Pattern>.

verdadeiro Opcional

Elemento <JSONPayload>/<JSONPath>/<Expression>

Especifica a expressão JSONPath definida para a variável.

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>
Predefinição: N/A
Presença: Opcional
Tipo: String

Elemento <JSONPayload>/<JSONPath>/<Pattern>

Define o padrão de expressão regular. Se uma expressão regular no elemento <Pattern> incluir carateres reservados em XML (", &, ', < ou .), tem de codificá-la em XML antes de a incluir.

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>
Predefinição: N/A
Presença: Obrigatória
Tipo: String

Referência de erro

Nesta seção, descrevemos os códigos de erro e as mensagens retornadas, bem como 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. Se você quiser capturar um erro e criar seu próprio erro personalizado, defina o atributo continueOnError="true" no elemento raiz da política. Para mais informações, 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 erro Mensagem
ExecutionFailed Failed to execute the RegularExpressionProtection StepDefinition {0}. Reason: {1}
InstantiationFailed Failed to instantiate the RegularExpressionProtection StepDefinition {0}
NonMessageVariable Variable {0} does not resolve to a Message
SourceMessageNotAvailable {0} message is not available for RegularExpressionProtection StepDefinition {1}
ThreatDetected Regular Expression Threat Detected in {0}: regex: {1} input: {2}
VariableResolutionFailed Failed to resolve variable {0}

Erros na implantação

Código de erro Mensagem Correção
CannotBeConvertedToNodeset RegularExpressionProtection {0}: Result of xpath {1} cannot be converted to nodeset. Context {2}
DuplicatePrefix RegularExpressionProtection {0}: Duplicate prefix {1}
EmptyJSONPathExpression RegularExpressionProtection {0}: Empty JSONPath expression
EmptyXPathExpression RegularExpressionProtection {0}: Empty XPath expression
InvalidRegularExpression RegularExpressionProtection {0}: Invalid Regular Expression {1}, Context {2}
JSONPathCompilationFailed RegularExpressionProtection {0}: Failed to compile jsonpath {1}. Context {2}
NONEmptyPrefixMappedToEmptyURI RegularExpressionProtection {0}: Non-empty prefix {1} cannot be mapped to empty uri
NoPatternsToEnforce RegularExpressionProtection {0}: No patterns to enforce in {1}
NothingToEnforce RegularExpressionProtection {0}: at least one of URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload is mandatory
XPathCompilationFailed RegularExpressionProtection {0}: Failed to compile xpath {1}. Context {2}

Variáveis de falha

Essas variáveis são definidas quando esta política aciona um erro. 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 acima. fault.name Matches "ThreatDetected"
regularexpressionprotection.policy_name.failed policy_name é o nome da política especificada pelo usuário que gerou a falha. regularexpressionprotection.Regular-Expressions-Protection-1.failed = true

Esquemas

Tópicos relacionados

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

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