Política RegularExpressionProtection

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X.
informações

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 qualquer expressão regular especificada for avaliada como verdadeira, a mensagem será considerada uma ameaça e será rejeitada.

Vídeos

Assista os vídeos a seguir para saber mais sobre a política de proteção às expressões regulares.

Vídeo Descrição
Proteção contra ataques de injeção de SQL (New Edge) Proteger-se contra ataques de injeção de SQL usando a política de proteção de expressões regulares em a interface da nova experiência do Edge.
Proteção contra ataques de injeção de SQL (versão clássica do Edge) Proteger-se contra ataques de injeção de SQL usando a política de proteção de expressões regulares em da interface clássica do Edge.

Amostras

GitHub

O exemplo de proteção contra regex no GitHub ilustra como interceptar possíveis ataques de injeção SQL emitidos por meio de um parâmetro de consulta. Além disso, a amostra 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">
    <DisplayName>Regular Expression Protection 1</DisplayName>
    <Source>request</Source>
    <JSONPayload escapeSlashCharacter="true">
       <JSONPath>
          <Expression>$</Expression>
          <Pattern>&lt;\s*script\b[^&gt;]*&gt;[^&lt;]+&lt;\s*\/\s*script\s*&gt;
          </Pattern>
          <Pattern>n\s*\\\\\s*slash</Pattern>
          <Pattern>n\s*\/\s*slash</Pattern>
          <Pattern>n\s*\\"\s*quotes</Pattern>
          <Pattern>n\s*\\b\s*space</Pattern>
          <Pattern>n\s*\\f\s*forwardfeed</Pattern>
          <Pattern>n\s*\\n\s*newline</Pattern>
          <Pattern>n\s*\\r\s*carria</Pattern>
          <Pattern>n\s*\\t\s*tab</Pattern>
          <Pattern>n\s*\\uFFFF\s*hex</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 em <JSONPath>/<Pattern> incluir caracteres XML reservados (", &, ', <, or .), Codifique-a em XML antes de incluí-la no arquivo de configuração XML da política. Por exemplo, no exemplo acima, a expressão regular <\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*> foi codificada em XML como &lt;\s*script\b[^&gt;]*&gt;[^&lt;]+&lt;\s*\/\s*script\s*&gt;.

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>

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

O Apigee Edge permite configurar expressões regulares que podem ser avaliado em relação ao tráfego de API em tempo de execução para identificar ameaças comuns no nível do conteúdo que acompanham certos 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.

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;
Injeção de exceção Java
.*?Exception in thread.*

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.

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

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 <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: falso
Presença: Opcional
Tipo: Booleanos

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

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 Presença
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/D 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 Presença
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/D 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 Presença
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/D 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 Presença
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/D 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/D

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 Presença
prefix

Fornece um prefixo para ajudar a qualificar um determinado namespace.

N/D 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/D

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 de dados.
<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:

String. Os valores válidos incluem: 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 Presença
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 e as mensagens de erro retornados e as variáveis de falha definidas pelo Edge quando esta 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.

Os erros retornados das políticas do Edge seguem um formato consistente, conforme descrito na Referência do código de erro.

Erros de execução

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

Código do erro Mensagem
ExecutionFailed Falha ao executar a StepDefinition de RegularExpressionProtection {0}. Motivo: {1}
InstantiationFailed Falha ao instanciar CommonExpressionProtection StepDefinition {0}
NonMessageVariable A variável {0} não resulta em uma mensagem
SourceMessageNotAvailable {0} mensagem não está disponível para a StepDefinition da RegularExpressionProtection {1}
ThreatDetected Ameaça de expressão regular detectada em {0}: regex: {1} entrada: {2}
VariableResolutionFailed Falha ao resolver a variável {0}

Erros de implantação

Código do erro Mensagem Correção
CannotBeConvertedToNodeset RegularExpressionProtection: {0} o resultado de xpath {1} não pode ser convertido em nodeset. Contexto {2}
DuplicatePrefix RegularExpressionProtection {0}: prefixo duplicado {1}
EmptyJSONPathExpression RegularExpressionProtection {0}: expressão JSONPath vazia
EmptyXPathExpression RegularExpressionProtection {0}: expressão XPath vazia
InvalidRegularExpression RegularExpressionProtection {0}: expressão regular inválida {1}, contexto {2}
JSONPathCompilationFailed RegularExpressionProtection {0}: falha ao compilar jsonpath {1}. Contexto {2}
NONEmptyPrefixMappedToEmptyURI RegularExpressionProtection {0}: o prefixo não vazio {1} não pode ser mapeado para o URI vazio
NoPatternsToEnforce RegularExpressionProtection: {0} não há padrões a serem aplicados em {1}
NothingToEnforce RegularExpressionProtection {0}: pelo menos um dos URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload é obrigatório.
XPathCompilationFailed RegularExpressionProtection {0}: falha ao compilar o xpath {1}. Contexto {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

Temas relacionados

Política JSONThreatProtection

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