Exceções
Consulte os campos de uma exceção de WAF, suas quinze match zones, a tela de Tuning e a API e a CLI que a gerenciam.
Uma exceção isenta uma parte de uma requisição de uma regra interna do Web Application Firewall (WAF), ou de todas elas, para que um padrão que essa regra pontuaria deixe de ser pontuado ali. O resto da regra continua funcionando: em todo lugar onde a exceção não corresponde, a regra é acionada como antes. O Azion Console chama o objeto de allowed rule e o lista na aba Allowed Rules de um rule set; a API da Azion e a Azion CLI chamam o mesmo objeto de exceção.
Uma exceção pertence a um rule set e é executada onde esse rule set é executado, ou seja, em um Firewall com o módulo WAF ativo. Ela pode ser escrita a partir de uma requisição que o WAF já marcou como ameaça, ou criada de antemão para um teste.
Esta página lista os campos de uma exceção, as quinze match zones que suas condições aceitam, a tela de Tuning que cria exceções em massa e as superfícies de API e CLI que as gerenciam.
Campos
Uma exceção carrega seis campos que uma requisição pode definir. Outros três são definidos pela plataforma e retornados em uma resposta, nunca enviados.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
id | integer | Somente leitura | — | O identificador que toda chamada posterior usa |
rule_id | integer | Não | 0 | A regra interna a que a exceção se aplica. 0 significa todas as regras. O Console o renderiza como o dropdown Rule ID |
name | string, de 1 a 255 caracteres | Sim | — | Texto livre indicando para que serve a exceção. O Console o renderiza como o campo Description |
path | string, até 255 caracteres, nullable | Não | — | Restringe a exceção a um path de requisição. Uma exceção sem path se aplica em todo lugar em que suas condições correspondem |
conditions | array de objetos, com pelo menos 1 entrada | Sim | — | As partes da requisição que a exceção cobre. O Console renderiza uma entrada como o campo Condition |
operator | string | Não | contains | Como as strings da exceção são comparadas: contains ou regex |
active | boolean | Não | true | Se a exceção está em vigor. Uma exceção inativa permanece no rule set e deixa de isentar qualquer coisa |
last_editor | string | Somente leitura | — | O e-mail da conta que alterou a exceção pela última vez |
last_modified | date-time | Somente leitura | — | Quando a exceção foi alterada pela última vez |
A menor exceção que a API aceita carrega um name e uma condição. Ela então se aplica a todas as regras, em todos os paths, com contains, e está ativa.
rule_id recebe um identificador do rule set interno, e 0 representa todas as regras dele. Para a lista de identificadores e o que cada regra detecta, consulte WAF Rule Sets. Os mesmos identificadores nomeiam as linhas da tela de Tuning, e o Console mostra a descrição de cada regra ao lado do seu identificador.
last_editor e last_modified são retornados pela API e pela CLI. O formulário do Console não os exibe.
Condições
Uma condição nomeia uma match zone e, onde a zona é específica, a string a que essa zona se aplica. O formato de uma condição é fixado pelo seu valor de match, e há três.
| Formato | Chaves | Match zones que o aceitam |
|---|---|---|
| Genérico | match | As nove zonas cujo nome não carrega specific |
| Específico em um nome | match e name | specific_body_form_field_name, specific_http_header_name, specific_query_string_name |
| Específico em um valor | match e value | specific_body_form_field_value, specific_http_header_value, specific_query_string_value |
O name ou o value de uma condição carrega entre 1 e 255 caracteres. Uma condição specific_* enviada sem nenhum dos dois retorna 400 com 10059 Required Field, e uma enviada com uma string vazia retorna 400 com 10018 Blank Field.
Uma exceção carrega mais de uma condição, e toda entrada é mantida.
Operador
operator decide como as strings da exceção são comparadas, e governa dois lugares ao mesmo tempo: o path da exceção e o name ou value da condição.
Sob o padrão contains, ambos são substrings e nenhum dos dois é lido como um padrão.
Sob regex, ambos são expressões regulares, e cada um é validado separadamente. Um path malformado retorna 400 com 26008 Invalid Regex Value e um ponteiro source de /data/path; um name de condição malformado retorna o mesmo código com um ponteiro de /data/conditions/0/name. Não há como tornar um deles uma expressão regular e o outro um literal — regex amplia os dois juntos, então uma exceção que precisa de um padrão na sua condição também precisa de um no seu path.
O Console renderiza a escolha como o dropdown Operator, com o placeholder Select an operator. Não existe um switch de regex separado em nenhum lugar da interface.
Match zones
Uma match zone é a parte de uma requisição que uma condição compara. A API a recebe como conditions[].match. O Azion Console rotula o campo como Condition, e não como match zone, e o inicializa com Any HTTP Header Value.
São quinze, listadas abaixo na ordem em que o Console as oferece. Uma opção que começa com Specific revela um campo Name ou Value adicional, e qual dos dois aparece é fixado pela opção.
| Opção do Console | Valor da API | Formato da condição | O que compara |
|---|---|---|---|
| Any HTTP Header Value | any_http_header_value | Genérico | O valor de cada header da requisição, como Mozilla/5.0 ou application/json |
| Any HTTP Header Name | any_http_header_name | Genérico | O nome de cada header da requisição, como User-Agent ou Authorization |
| Specific HTTP Header Value | specific_http_header_value | Específico em um valor | O value da condição, contra o valor de cada header da requisição. Não carrega nome de header |
| Specific HTTP Header Name | specific_http_header_name | Específico em um nome | O name da condição, como cookie, contra o nome de um header da requisição |
| Any Query String Value | any_query_string_value | Genérico | O valor de cada parâmetro de query string. Em ?id=123&user=admin, 123 e admin |
| Any Query String Name | any_query_string_name | Genérico | O nome de cada parâmetro de query string. Em ?id=123&user=admin, id e user |
| Specific Query String Value | specific_query_string_value | Específico em um valor | O value da condição, contra o valor de cada parâmetro de query string |
| Specific Query String Name | specific_query_string_name | Específico em um nome | O name da condição, como token, contra o nome de um parâmetro de query string |
| Body Form Field Value | body_form_field_value | Genérico | O valor de cada campo de formulário no corpo da requisição |
| Body Form Field Name | body_form_field_name | Genérico | O nome de cada campo de formulário no corpo da requisição |
| Specific Body Form Field Value | specific_body_form_field_value | Específico em um valor | O value da condição, contra o valor de cada campo de formulário no corpo |
| Specific Body Form Field Name | specific_body_form_field_name | Específico em um nome | O name da condição, como api_key, contra o nome de um campo de formulário no corpo |
| Any URL | any_url | Genérico | A URL da requisição |
| Raw Body | raw_body | Genérico | O corpo da requisição não interpretado, como um payload JSON ou XML |
| File Extension | file_extension | Genérico | A extensão de arquivo na requisição, como .php, .exe ou .sh |
Um valor fora desse conjunto retorna 400 com 10039 Invalid Choice e um ponteiro source que nomeia a condição, como /data/conditions/0/match.
specific_http_header_value não nomeia um header. Suas duas chaves são match e value, portanto a string que ela carrega é comparada contra valores de header, e não contra um nome de header. Uma condição {"match": "specific_http_header_value", "value": "Cookie"} corresponde, então, a qualquer header cujo valor contenha Cookie, o que não é a mesma coisa que uma exceção para o header Cookie.
specific_http_header_name com um name é o único formato que limita o escopo de uma exceção a um header nomeado. A API armazena a string exatamente como ela é enviada, então cookie, Cookie e HTTP_COOKIE são todos aceitos e todos lidos de volta sem alteração.
Tuning
Tuning é uma aba de um rule set. Ela lista as requisições que cada regra interna correspondeu ao longo de uma janela escolhida, agrupadas por ID da regra, e transforma os registros selecionados em exceções em massa. É onde um falso positivo é encontrado antes de ser permitido.
Uma consulta precisa de um domínio. Os outros filtros a restringem.
| Filtro | O que restringe |
|---|---|
| Domain | O workload ou domínio cujas requisições são lidas. Obrigatório |
| Time Range | A janela ao longo da qual as requisições são lidas. As opções são Last 1 hour, Last 3 hours, Last 6 hours, Last 12 hours, Last day, Last 2 days e Last 3 days. Last 3 days é a janela mais longa disponível |
| Network Lists | As requisições cujo endereço de origem está em uma entrada de Network Lists |
| IP Address | As requisições vindas de um ou mais endereços de origem |
| Country | O país de onde a requisição veio |
Azion Console recusa duas combinações: IP Address com um filtro de network list IP/CIDR, e Country com um filtro de network list Countries.
O resultado é uma linha por regra interna que correspondeu, carregando as colunas Rule ID, Hits, Paths, IPs, Countries, Top 10 IP Addresses e Top 10 Countries, acima de uma contagem dos registros encontrados.
Selecionar uma linha abre More Details, que lista as ocorrências por trás daquele ID da regra e as restringe ainda mais por network list, país, endereço IP e Path.
Selecionar linhas e escolher Allow Rules as grava nas allowed rules do rule set. A confirmação pergunta o motivo pelo qual essas regras estão sendo permitidas, e informa que uma regra separada é criada para cada possível ataque em cada URI, então uma seleção produz várias exceções. A aba Allowed Rules carrega um botão Create from Tuning de volta para esta tela.
Para o procedimento, consulte Ajuste um WAF rule set. Para saber por que o tuning é repetido em vez de feito uma única vez, consulte Score e modos.
API
Toda operação é autenticada e fica sob https://api.azion.com/v4/workspace/wafs/{waf_id}/exceptions. Uma requisição carrega um token de Personal Tokens no header Authorization sob o esquema Token, e uma requisição com corpo também carrega Content-Type: application/json. A API gerencia exceções independentemente do Console, então uma delas pode ser criada, alterada ou removida a partir de um script.
| Operação | Método e path |
|---|---|
| Criar uma exceção | POST /wafs/{waf_id}/exceptions |
| Listar exceções | GET /wafs/{waf_id}/exceptions |
| Recuperar uma exceção | GET /wafs/{waf_id}/exceptions/{exception_id} |
| Substituir uma exceção | PUT /wafs/{waf_id}/exceptions/{exception_id} |
| Atualizar parte de uma exceção | PATCH /wafs/{waf_id}/exceptions/{exception_id} |
| Remover uma exceção | DELETE /wafs/{waf_id}/exceptions/{exception_id} |
Uma criação, uma substituição, uma atualização parcial e uma remoção respondem 202. Uma leitura responde 200.
As operações acima são chamadas de API comuns, então a gestão de exceções cabe em um pipeline de entrega como qualquer outra mudança de configuração. A evidência a partir da qual uma exceção é escrita vem de outra superfície: Tuning é uma tela do Azion Console, e a API não a expõe. Um script lê essa evidência no Real-Time Events, onde wafMatch nomeia as regras internas que uma requisição acionou e wafScore informa o score que cada família de ameaças alcançou. Ele então cria uma exceção para cada falso positivo que esses registros confirmam. A Azion CLI é a outra superfície, e sua flag --conditions não funciona na 4.23.0, então um script usa --file ou a API diretamente.
Criar uma exceção
A resposta carrega 202, e não 201:
O state de pending indica que a exceção foi aceita, e o id em data é o handle que toda chamada posterior usa. last_editor carrega o e-mail da conta que alterou a exceção pela última vez, e o valor acima é um placeholder.
A mesma chamada com o corpo abaixo cria uma exceção com escopo no parâmetro de query string chamado q. A resposta carrega 202, um novo id de 123457 e a condição ecoada sem alteração.
O corpo abaixo limita a mesma exceção a um valor de query string. Ele responde 202 com um id de 123458.
Listar exceções
A resposta carrega 200 e o envelope de coleção abaixo, com uma exceção por entrada em results, cada uma no formato que a resposta de criação carrega.
| Campo | O que carrega |
|---|---|
count | Exceções que o rule set contém |
total_pages | Páginas em que o resultado se divide, no page_size atual |
page | A página que esta resposta carrega |
page_size | Exceções por página. O padrão é 10 |
next | A URL da página seguinte, ou null |
previous | A URL da página anterior, ou null |
results | Uma exceção por entrada, carregando os campos listados em Campos |
O endpoint aceita created_at__gte, created_at__lte, description, fields, id, last_editor, last_modified__gte, last_modified__lte, ordering, page, page_size, path e search como parâmetros de query string. page_size vai de 1 a 100 e tem 10 como padrão. Um valor acima de 100 retorna 400 com 10097 Invalid Page Size.
Recuperar, atualizar e remover uma exceção
GET /wafs/{waf_id}/exceptions/{exception_id} responde 200 e retorna a exceção em data, sem a chave state.
PUT /wafs/{waf_id}/exceptions/{exception_id} substitui uma exceção e recebe o mesmo corpo de uma criação. Ele responde 202 com um state de pending. O array conditions é substituído, e não mesclado, então uma substituição envia todas as condições que a exceção deve manter.
PATCH /wafs/{waf_id}/exceptions/{exception_id} recebe apenas os campos enviados e responde 202. Um corpo de {"active": false} desativa uma exceção e deixa o resto dela como estava.
DELETE /wafs/{waf_id}/exceptions/{exception_id} responde 202 com um corpo vazio.
CLI
A Azion CLI gerencia exceções sob o substantivo waf-exceptions. As flags abaixo são as que a Azion CLI 4.23.0 carrega, sem as flags globais que todo comando recebe.
| Comando | O que faz |
|---|---|
azion create waf-exceptions | Cria uma exceção em um rule set |
azion list waf-exceptions | Lista as exceções que um rule set contém |
azion describe waf-exceptions | Retorna uma exceção |
azion update waf-exceptions | Altera uma exceção |
azion delete waf-exceptions | Remove uma exceção |
azion create waf-exceptions e azion update waf-exceptions compartilham suas flags, exceto que --exception-id pertence ao update.
| Flag | O que define |
|---|---|
--waf-id | O rule set a que a exceção pertence |
--name | O nome da exceção |
--rule-id | A regra interna a que a exceção se aplica |
--path | O path a que a exceção fica restrita |
--operator | regex ou contains |
--active | true ou false. O padrão é true |
--conditions | As condições, em JSON. Consulte o alerta abaixo antes de usá-la |
--file | Um arquivo JSON que carrega o corpo, ou - para ler o corpo da entrada padrão |
--exception-id | A exceção a ser alterada. Apenas em azion update waf-exceptions |
azion list waf-exceptions recebe --waf-id, --details, --filter para filtrar por nome, --order-by, --page com padrão 1 e --page-size com padrão 50. azion describe waf-exceptions e azion delete waf-exceptions recebem, cada um, --waf-id e --exception-id.
Escreva o corpo em um arquivo:
Depois crie a exceção a partir dele:
azion describe waf-exceptions retorna uma exceção, com as chaves ordenadas pela CLI:
Erros
Uma requisição rejeitada retorna um array errors. Cada entrada carrega um code, um title, um detail, o status e um ponteiro source que nomeia o campo sobre o qual é a rejeição. Para uma condição, o ponteiro indexa o array, então /data/conditions/0/name nomeia a primeira condição:
| Código | Título | Status | O que causa | O que fazer |
|---|---|---|---|---|
10004 | Not Found | 404 | Um waf_id ou um exception_id que não existe | Verifique cada segmento do path |
10009 | Unsupported Media Type | 415 | Uma escrita enviada com um Content-Type diferente de application/json | Envie Content-Type: application/json |
10018 | Blank Field | 400 | Um name ou value de condição que é uma string vazia | Envie de 1 a 255 caracteres |
10039 | Invalid Choice | 400 | Um valor fora de um enum: rule_id, operator ou o match de uma condição | Envie um dos valores listados em Campos e Match zones. O ponteiro source nomeia o campo |
10046 | Max Length | 400 | Um name com mais de 255 caracteres | Encurte o nome |
10049 | Min Length List Field | 400 | Um array conditions vazio, que é o que azion create waf-exceptions --conditions sempre envia | Envie pelo menos uma condição, pela API ou com azion create waf-exceptions --file |
10059 | Required Field | 400 | Um campo obrigatório está ausente, como uma condição specific_* sem name | Adicione o campo que o ponteiro source nomeia |
10097 | Invalid Page Size | 400 | Um page_size acima de 100 em uma requisição de listagem | Peça 100 ou menos |
26008 | Invalid Regex Value | 400 | operator é regex e o path da exceção, ou o name ou o value de uma condição, não é um padrão válido | Corrija o padrão que o ponteiro source nomeia. O meta.regex_value da entrada repete o valor que falhou |
Um rule_id de 0 não é um erro. É o valor legal que significa todas as regras, e responde 202 como qualquer outro.