Política RegularExpressionProtection

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

Confira a documentação da Apigee Edge.

O que

Extrai informações de uma mensagem (por exemplo, caminho de 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 expressões regulares predefinidas. Se alguma expressão regular especificada for avaliada como verdadeira, a mensagem será considerada uma ameaça, e a política emitirá uma falha.

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.

OBSERVAÇÃO: este tópico não se destina a incluir uma introdução detalhada às expressões regulares. O principal objetivo é ilustrar a estrutura e o uso dessa política.

Se você quiser saber mais sobre expressões regulares, há muitos recursos para explorar. Você pode encontrar exemplos de expressões regulares e outras orientações no tópico Correspondência de padrões com condicionais.

Vídeos

Assista ao vídeo a seguir para saber mais sobre a política de proteção de expressão regular.

Vídeo	Descrição
Proteção contra ataques de injeção de SQL	Proteger contra ataques de injeção SQL usando a política de proteção de expressões regulares na IU da Apigee.

Amostras

GitHub

A amostra de regex-protection no GitHub ilustra como interceptar possíveis ataques de injeção de SQL emitidos por um parâmetro de consulta que pode conter código malicioso em uma sinalização <script>. A amostra também ilustra uma prática recomendada de definir um status de erro genérico de 400 para impedir que invasores recebam informações úteis a partir da resposta.

O JavaScript inclui proteção contra ataque

<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 para JavaScript com ataques. Especificamente, o conteúdo extraído por <JSONPath>/<Expression> é avaliado em relação à expressão regular em <JSONPath>/<Pattern>.

Se a expressão regular no seu <JSONPath>/<Pattern> incluir caracteres reservados em XML (", &, ', < ou >), será necessário colocá-los em uma seção CDATA (dados de caracteres), conforme mostrado na amostra acima, ou codificar os caracteres reservados em XML, por exemplo, substituindo < por < e > por >.

Além disso, se a expressão regular incluir barras (/), insira caracteres de escape definindo o atributo <JSONPayload> escapeSlashCharacter como true.

Correspondência indiferente a maiúsculas

É um caso de uso comum fazer a correspondência sem distinção entre maiúsculas e minúsculas. Veja um exemplo de como fazer isso em uma expressão regular usando a construção (?i). Neste exemplo, por exemplo, DELETE, delete e Delete serão avaliados como verdadeiros.

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

Verificações de parâmetros do 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 de política da RegularExpressionProtection avaliará os parâmetros de formulário para a ocorrência de caracteres especiais, dentro do conjunto [-+=$%&]. Esta política só terá efeito quando o cabeçalho do tipo de conteúdo na solicitação for application/x-www-form-urlencoded. A configuração da política usa uma seção CDATA (dados de caracteres) para unir as expressões regulares devido à presença do caractere &, que é especial em XML.

---

Sobre a política de proteção de expressão regular

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

Uma expressão regular, ou regex, é um conjunto de strings que especificam um padrão em uma string. As expressões regulares permitem que o conteúdo seja avaliado de maneira programática para os padrões. As expressões regulares podem ser usadas, por exemplo, para avaliar um endereço de e-mail e garantir que ele esteja estruturado de forma adequada. Para mais informações, consulte Expressões regulares nos tutoriais do Java.

O uso mais comum do 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 vários mecanismos precisam ser combinados para permitir a defesa em profundidade. Nesta seção, descrevemos alguns padrões recomendados para excluir conteúdo.

Exemplos de padrões de exclusão

As expressões regulares precisam ser codificadas em XML no arquivo de configuração XML da política. Consulte também Antipadrão: use quantificadores gananciosos na política RegularExpressionProtection.

Nome	Expressão regular
Injeção de SQL	[\s]*((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))
Injeção do Server Side Includes (SSI)	<!--#(include|exec|echo|config|printenv)\s+.* Codificado em XML: &lt;!--#(include|exec|echo|config|printenv)\s+.*
Injeção de sintaxe abreviada em XPath	(/(@?[\w_?\w:\*]+(\[[^]]+\])*)?)+
Injeção de sintaxe expandida XPath	/?(ancestor(-or-self)?|descendant(-or-self)?|following(-sibling))
Injeção JavaScript	<\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> Codificado em XML: &lt;\s*script\b[^&gt;]*&gt;[^&lt;]+&lt;\s*/\s*script\s*&gt;

Definir o cabeçalho Content-Type em uma solicitação com um payload XML ou JSON

O payload da política de proteção de expressão regular pode incluir os seguintes elementos:

• Elemento <XMLPayload>: especifica que as informações precisam ser extraídas de um payload XML e avaliadas em relação à expressão regular fornecida.

  Se você usar <XMLPayload> na política, o cabeçalho Content-Type da solicitação precisará ser um tipo de conteúdo XML, como application/xml ou text/xml.

• Elemento <JSONPayload>: especifica que as informações precisam ser extraídas de um payload JSON e avaliadas em relação à expressão regular fornecida.

  Se você usar <JSONPayload> na política, o cabeçalho Content-Type da solicitação precisará ser um tipo de conteúdo JSON, como application/json.

Normalmente, você cria uma API para aceitar XML ou JSON. No entanto, pode haver um cenário em que a API aceitou os dois. Em seguida, você pode definir uma política de Proteção de Expressão regular que usa os elementos <XMLPayload> e <JSONPayload>. Somente um elemento se aplica a uma solicitação específica com base no valor do cabeçalho Content-Type.

Referência de elemento

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

OBSERVAÇÃO: neste tópico, "REGEX PATTERN" significa um padrão de expressão regular válido usado para realizar a correspondência desejada. A Apigee segue as mesmas regras de Regex que as classes no pacote java.util.regex na linguagem Java.

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

Atributos de <RegularExpressionProtection>

<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-Protection-1">

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

Atributo	Descrição	Padrão	Presence
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	false	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.	false	Descontinuado

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.
Presence	Opcional
Tipo	String

Elemento <Source>

Indica a mensagem a partir da qual as informações precisam ser extraídas.

Se o elemento <Source> for omitido, o valor padrão será message. Por exemplo, <Source>message</Source>. Quando definida como message, a política usa a mensagem de solicitação como origem quando anexada a um fluxo de solicitação. Da mesma forma, a política usa a mensagem de resposta quando 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 for de mensagem, a política retornará um erro.

<Source>response</Source>

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

Elemento <IgnoreUnresolvedVariables>

Determina se a política retorna um erro quando encontra uma variável que não pode ser resolvida.

Se definido como false (padrão), a política retornará um erro quando uma variável não resolvida for encontrada. Se definida como true, a variável não resolvida será tratada como string vazia (nula).

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Padrão:	false
Presença:	Opcional
Tipo:	Booleano

Elemento <URIPath>

Especifica que as informações precisam ser extraídas do caminho do URI de solicitação e avaliadas em relação às expressões regulares fornecidas. Você precisa 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>

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

Elemento <QueryParam>

Especifica que as informações precisam ser extraídas do parâmetro de consulta da solicitação e avaliadas em relação às expressões regulares fornecidas. Você precisa 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>

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

Atributos

Atributo	Descrição	Padrão	Presence
name	Nome do parâmetro de consulta da solicitação de onde as informações precisam ser extraídas das avaliações nas expressões regulares fornecidas.	N/A	Obrigatório

Elemento <Header>

Especifica que as informações precisam ser extraídas dos cabeçalhos de solicitação e resposta e avaliadas em relação às expressões regulares fornecidas. Você precisa 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>

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

Atributos

Atributo	Descrição	Padrão	Presence
name	Nome do cabeçalho de solicitação e resposta de onde as informações precisam ser extraídas para avaliação em relação às expressões regulares fornecidas.	N/A	Obrigatório

Elemento <FormParam>

Especifica que as informações precisam ser extraídas do parâmetro de consulta da solicitação e avaliadas em relação às expressões regulares fornecidas. Você precisa 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>

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

Atributos

Atributo	Descrição	Padrão	Presence
name	Nome do parâmetro de formulário da solicitação de onde as informações precisam ser extraídas das avaliações nas expressões regulares fornecidas.	N/A	Obrigatório

Elemento <Variable>

Especifica que as informações precisam ser extraídas da variável fornecida e avaliadas em relação às expressões regulares fornecidas.

<Variable name="request.content">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</Variable>

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

Atributos

Atributo	Descrição	Padrão	Presence
name	Nome da variável da qual as informações precisam ser extraídas para avaliação em relação às expressões regulares fornecidas.	N/A	Obrigatório

Elemento <XMLPayload>

Especifica que as informações precisam ser extraídas de um payload XML e avaliadas em relação às 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>

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

Elemento <XMLPayload>/<Namespaces>

Especifica os namespaces a serem usados na avaliação de 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>

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

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

Especifica cada namespace a ser usado na avaliação XPath.

<Namespaces>
   <Namespace prefix="apigee">http://www.apigee.com</Namespace>
</Namespaces>

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

Atributos

Atributo	Descrição	Padrão	Presence
prefixo	Fornece um prefixo para ajudar a qualificar um determinado namespace.	N/A	Obrigatório

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>

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

Especifica o XPath definido para a variável.

Especifica a expressão XPath definida para a variável. Somente expressões XPath 1.0 são compatíveis. Por exemplo, <Expression>/company/employee[@age>=$request.header.age]</Expression> extrai detalhes para funcionários com idade maior ou igual 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>

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

Elemento <XMLPayload>/<XPath>/<Type>

Especifica o tipo desejado para os dados de saída.

Normalmente, você usará "string" ou "nodeset". Use "string" se tiver certeza de que sua consulta xpath resultará em, no máximo, um valor ou se quiser verificar no máximo um valor. Se a consulta xpath puder retornar vários valores, especifique "nodeset" para verificar todos eles.

Por exemplo, considere a expressão XPath //*/@*. Ela corresponde a todos os atributos em todos os elementos. Se você especificar "string" como Type, a Apigee forçará o resultado dessa consulta a uma única string. Ele será o valor de um dos atributos de um dos elementos do documento XML, mas não está definido qual atributo e qual elemento. A Apigee realizará a comparação de padrões apenas em relação ao valor desse único atributo. Isso provavelmente não é o que você quer.

Por outro lado, se você especificar "nodeset" como o Type para essa expressão XPath, a Apigee executará a comparação de padrões com cada um dos valores de atributo em cada elemento do documento XML.

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>

Padrão:	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 caracteres XML reservados (", &, ', <, or .). Será preciso codificá-la em XML antes de incluí-la.

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>

Padrão:	N/A
Presença:	Obrigatório
Tipo:	String

Elemento <JSONPayload>

Especifica que as informações precisam ser extraídas de um payload JSON e avaliadas em relação às expressões regulares fornecidas.

<JSONPayload>
   <JSONPath>
      <Expression>$.store.book[*].author</Expression>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </JSONPath>
</JSONPayload>

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

Atributos

Atributo	Descrição	Padrão	Presence
escapeSlashCharacter	Defina como true para fazer o escape de qualquer caractere de barra (/) nas expressões regulares em <JSONPath>/<Pattern>.	true	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>

Padrã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 caracteres XML reservados (", &, ', <, or .). Será preciso codificá-la em XML antes de incluí-la.

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>

Padrão:	N/A
Presença:	Obrigatório
Tipo:	String

Referência de erros

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.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

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

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

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

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

Temas relacionados

Política JSONThreatProtection

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