# Exceções Uma exceção isenta uma parte de uma requisição de uma regra interna do [Web Application Firewall](/pt-br/documentacao/plataforma/firewall/#waf) (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](/pt-br/documentacao/plataforma/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](/pt-br/documentacao/plataforma/firewall/waf/rule-sets/#regras-internas). 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`. ```json { "match": "any_query_string_value" } ``` ```json { "match": "specific_query_string_name", "name": "q" } ``` ```json { "match": "specific_query_string_value", "value": "o-neill" } ``` 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. > **Atenção** > > Uma chave que o formato da condição não carrega é descartada, não rejeitada. Uma condição enviada como `{"match": "any_http_header_value", "name": "cookie"}` retorna `202` e é lida de volta como `{"match": "any_http_header_value"}`, sem o `name`. A exceção passa a cobrir todos os headers da requisição em vez de um, e nada na resposta, na leitura de volta ou no Console indica isso. Use uma match zone `specific_*` sempre que a exceção precisar nomear um header, um parâmetro de query string ou um campo de formulário. --- ## 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](/pt-br/documentacao/plataforma/firewall/network-shield/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](/pt-br/documentacao/guias/seguranca-de-aplicacoes/firewall-e-waf/tune-waf/). Para saber por que o tuning é repetido em vez de feito uma única vez, consulte [Score e modos](/pt-br/documentacao/plataforma/firewall/waf/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](/pt-br/documentacao/fundamentos/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](/pt-br/documentacao/plataforma/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 ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/wafs/12345/exceptions \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "rule_id": 1013, "name": "docs-rework-waf-exc-generic", "path": "/search", "operator": "contains", "active": true, "conditions": [ { "match": "any_query_string_value" } ] }' ``` A resposta carrega `202`, e não `201`: ```json { "state": "pending", "data": { "id": 123456, "rule_id": 1013, "name": "docs-rework-waf-exc-generic", "path": "/search", "conditions": [ { "match": "any_query_string_value" } ], "operator": "contains", "active": true, "last_editor": "[ACCOUNT EMAIL]", "last_modified": "2026-01-01T12:00:00.000000Z" } } ``` 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. ```json { "rule_id": 1013, "name": "docs-rework-waf-exc-specific", "path": "/search", "operator": "contains", "active": true, "conditions": [ { "match": "specific_query_string_name", "name": "q" } ] } ``` O corpo abaixo limita a mesma exceção a um valor de query string. Ele responde `202` com um `id` de `123458`. ```json { "rule_id": 1013, "name": "docs-rework-waf-exc-value", "path": "/search", "operator": "contains", "active": true, "conditions": [ { "match": "specific_query_string_value", "value": "o-neill" } ] } ``` ### Listar exceções ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/wafs/12345/exceptions \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` 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](/pt-br/documentacao/devtools/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`. > **Atenção** > > Na 4.23.0, `azion create waf-exceptions --conditions` envia um array `conditions` vazio qualquer que seja o valor recebido, e a API rejeita a requisição com `400` e `10049 Min Length List Field` em `/data/conditions`. Crie a exceção a partir de um arquivo, com `--file`. Na mesma versão, a coluna `RULE ID` de `azion list waf-exceptions` imprime um valor que não é o ID da regra; leia o ID da regra com `azion describe waf-exceptions` ou pela API. Escreva o corpo em um arquivo: ```json { "rule_id": 1013, "name": "docs-rework-waf-exc-cli-file", "path": "/", "operator": "contains", "active": true, "conditions": [ { "match": "any_query_string_value" } ] } ``` Depois crie a exceção a partir dele: ```bash azion create waf-exceptions --waf-id 12345 --file exc.json ``` ```text Created WAF Exception with ID 123459 ``` `azion describe waf-exceptions` retorna uma exceção, com as chaves ordenadas pela CLI: ```bash azion describe waf-exceptions --waf-id 12345 --exception-id 123457 --format json ``` ```json {"active": true, "conditions": [{"match": "specific_query_string_name", "name": "q"}], "id": 123457, "last_editor": "[ACCOUNT EMAIL]", "last_modified": "2026-01-01T12:00:02.000000Z", "name": "docs-rework-waf-exc-specific", "operator": "contains", "path": "/search", "rule_id": 1013} ``` --- ## 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: ```json { "errors": [ { "code": "10059", "title": "Required Field", "detail": "This field is required.", "status": "400", "source": { "pointer": "/data/conditions/0/name" } } ] } ``` | 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. --- ## Recursos relacionados - [Score e modos](/pt-br/documentacao/plataforma/firewall/waf/score-e-modos.md): O modelo de score do qual uma exceção isenta uma requisição, e o loop de tuning em volta dele. - [Boas práticas de Firewall](/pt-br/documentacao/plataforma/firewall/boas-praticas.md#waf): Quando uma exceção é a resposta certa, o risco que cada uma carrega e como manter o conjunto pequeno. - [Crie uma exceção do WAF](/pt-br/documentacao/guias/seguranca-de-aplicacoes/firewall-e-waf/configurar-waf-allowed-rules.md): O procedimento que cria uma exceção no Azion Console, com um falso positivo resolvido. - [Ajuste um WAF rule set](/pt-br/documentacao/guias/seguranca-de-aplicacoes/firewall-e-waf/tune-waf.md): Os passos que executam a tela de Tuning e transformam suas linhas em exceções.