Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
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 <
e >
por >
.
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: <!--#(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: <\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> |
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çalhoContent-Type
do pedido tem de ser um tipo de conteúdo XML, comoapplication/xml
outext/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çalhoContent-Type
do pedido tem de ser um tipo de conteúdo JSON, comoapplication/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 Opcionalmente, use o elemento |
N/A | Obrigatória |
continueOnError |
Definido como Definido como |
falso | Opcional |
enabled |
Defina como Defina como |
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 |
---|---|
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: |
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 |
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} |
build |
DuplicatePrefix |
RegularExpressionProtection {0}: Duplicate prefix {1} |
build |
EmptyJSONPathExpression |
RegularExpressionProtection {0}: Empty JSONPath expression |
build |
EmptyXPathExpression |
RegularExpressionProtection {0}: Empty XPath expression |
build |
InvalidRegularExpression |
RegularExpressionProtection {0}: Invalid Regular Expression {1}, Context {2} |
build |
JSONPathCompilationFailed |
RegularExpressionProtection {0}: Failed to compile jsonpath {1}. Context {2} |
build |
NONEmptyPrefixMappedToEmptyURI |
RegularExpressionProtection {0}: Non-empty prefix {1} cannot be mapped to empty
uri |
build |
NoPatternsToEnforce |
RegularExpressionProtection {0}: No patterns to enforce in {1} |
build |
NothingToEnforce |
RegularExpressionProtection {0}: at least one of URIPath, QueryParam, Header,
FormParam, XMLPayload, JSONPayload is mandatory |
build |
XPathCompilationFailed |
RegularExpressionProtection {0}: Failed to compile xpath {1}. Context {2} |
build |
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