# Primeiros passos com Bot Manager Este guia instrui você a pontuar a sua primeira requisição com o [Bot Manager Lite](/pt-br/documentacao/plataforma/firewall/bot-manager/bot-manager-lite/), a edição que você instala por conta própria pelo Marketplace. - Crie uma instância de função no seu firewall, carregando os argumentos com que a função é executada. - Execute essa instância por uma regra do Rules Engine, em toda requisição que o firewall recebe. - Envie uma requisição com formato de bot e leia a pontuação que a função deu a ela. O Bot Manager Lite pontua cada requisição contra um conjunto publicado de regras estáticas, que carregam assinaturas de credential stuffing, varredura de vulnerabilidades e scraping de site. O [Bot Manager](/pt-br/documentacao/plataforma/firewall/#bot-manager), a edição completa, é habilitado sob demanda pelo time de Service Delivery da Azion, e acrescenta uma pontuação dinâmica e o Reputation Intelligence sobre essas regras. As duas edições são configuradas do mesmo jeito, então os estágios abaixo não mudam com a edição. Cinco objetos colocam uma requisição sob inspeção, e cada um liga ao seguinte: 1. A **função** instalada é o código do Bot Manager Lite, instalado uma vez pelo Marketplace na conta. 2. O **firewall** carrega o módulo **Functions**, que é o que executa uma função instalada. 3. A **instância de função** nesse firewall guarda os argumentos com que a função é executada. 4. A **regra do Rules Engine** no mesmo firewall carrega um comportamento `run_function`, que nomeia essa instância. 5. O **workload** que serve a sua aplicação é vinculado a esse firewall pelo seu deployment. Uma função instalada não pontua nada sozinha. Os cinco objetos precisam existir. --- Selecione a interface que você vai usar. Os pré-requisitos e cada estágio abaixo seguem essa escolha. ## Pré-requisitos - Uma conta Azion. - Bot Manager Lite instalado pelo Marketplace. A instalação é feita no Azion Console, qualquer que seja a interface dos estágios abaixo: acesse [Azion Console](https://console.azion.com/) > **Marketplace**, selecione a integração Bot Manager Lite pelo campo de busca e selecione **Install**. A função aparece então em **Functions**, em **Edge Libraries**, onde uma coluna **Vendor** a marca como instalação pelo Marketplace. Para mais informações, consulte [Instale o Bot Manager Lite](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/integracoes/bot-manager-lite/). - Um [firewall](/pt-br/documentacao/plataforma/firewall/) com o módulo **Functions** ligado. O módulo está em **Main Settings** do firewall, na seção **Modules**, e um firewall criado com o [Azion CLI](/pt-br/documentacao/devtools/cli/) já o tem ligado. Para mais informações, consulte [Defina as configurações principais de um firewall](/pt-br/documentacao/guias/seguranca-de-aplicacoes/firewall-e-waf/firewall-definir-main-settings/). - Um [workload](/pt-br/documentacao/plataforma/workloads/) servindo a sua aplicação e vinculado a esse firewall. O vínculo fica no deployment do workload. - Ligar um produto ou um módulo pode gerar custos de uso. Para as métricas pelas quais o Bot Manager é cobrado, consulte [Preços](/pt-br/documentacao/fundamentos/precos/#bot-manager). **Console** - Acesso ao Azion Console. Para entrar, consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). **CLI** - O [Azion CLI](/pt-br/documentacao/devtools/cli/) instalado e autorizado. **API** - Um personal token e o `curl`. Para criar um token, consulte [Personal Tokens](/pt-br/documentacao/fundamentos/personal-tokens/). --- ## Crie uma instância de Bot Manager Lite no seu firewall Uma instância de função carrega toda a sua configuração em um objeto JSON. Quatro argumentos bastam para uma primeira execução: ```json { "threshold": 30, "action": "deny", "internal_logs": 2, "log_tag": "storefront-bots" } ``` `threshold` e `action` são o par que decide o resultado: a função aplica `action` a uma requisição cuja pontuação alcança `threshold`, e `30` com `deny` são os valores que o Bot Manager Lite entrega. `internal_logs` em `2` escreve uma linha de report para toda requisição, incluindo uma que pontua `0`. `log_tag` identifica esta instância nessas linhas, então substitua `storefront-bots` por uma tag sua. Para cada argumento que uma instância aceita, consulte [Argumentos](/pt-br/documentacao/plataforma/firewall/bot-manager/argumentos/#campos). > **Atenção** > > Nada valida o objeto. Toda chave que você envia é armazenada e lida de volta sem alteração, leia a função essa chave ou não. Um argumento escrito errado, como `thresold: 5`, é guardado, deixa o threshold em `30` e não levanta erro em nenhuma interface. **Console** Para criar a instância no Azion Console: 1. **Abra o firewall vinculado ao seu workload** Acesse [Azion Console](https://console.azion.com/) > **Firewalls** e selecione esse firewall. 2. **Selecione a aba Functions Instances** 3. **Selecione + Function** Em um firewall que ainda não carrega instância, a mesma ação aparece como **+ Function Instance**. 4. **Nomeie a instância** Na seção **General**, informe um **Name**. Por exemplo: `bot-manager-lite`. 5. **Selecione a função instalada** Na seção **Function**, selecione a função Bot Manager Lite. O seletor lista apenas as funções da conta que são executadas em um firewall. 6. **Informe os argumentos** Na seção **Arguments**, informe o objeto. O Bot Manager Lite não carrega esquema de argumentos, então a seção guarda um editor JSON e não constrói formulário a partir dele. 7. **Salve a instância** A instância aparece em **Functions Instances**, que lista o seu **Name**, **Function**, **Last Editor** e **Last Modified**. O formulário não carrega um controle **Active** e a lista não carrega uma coluna **Status**: Azion Console cria toda instância ativa. **CLI** `azion create firewall-instance` lê os argumentos de um arquivo. O seu flag `--args` recebe um caminho, não JSON inline. 1. **Escreva os argumentos em um arquivo** Salve o objeto como `bmargs.json`: ```json { "threshold": 30, "action": "deny", "internal_logs": 2, "log_tag": "storefront-bots" } ``` 2. **Crie a instância** Substitua `` pelo id do seu firewall, e `` pelo id da função Bot Manager Lite instalada: ```bash azion create firewall-instance --name bot-manager-lite --firewall-id \ --function-id --args bmargs.json --active true ``` 3. **Leia a saída** O comando imprime o id da nova instância: ```text Created Firewall Function Instance with ID 12347 ``` Guarde esse id. A regra do próximo estágio nomeia a instância por ele, nunca pelo id da função. **API** A chamada de criação carrega o nome, o id da função e os argumentos em um corpo só. 1. **Envie a requisição de criação** Substitua `` pelo id do seu firewall, `[TOKEN VALUE]` pelo seu personal token e `12345` pelo id da função Bot Manager Lite instalada: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/firewalls//functions \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "bot-manager-lite", "function": 12345, "active": true, "args": { "threshold": 30, "action": "deny", "internal_logs": 2, "log_tag": "storefront-bots" } }' ``` 2. **Leia a resposta** Uma criação responde `202`, e `"state": "pending"` significa que a mudança ainda está se propagando: ```json { "state": "pending", "data": { "id": 12348, "name": "bot-manager-lite", "args": { "threshold": 30, "action": "deny", "internal_logs": 2, "log_tag": "storefront-bots" }, "azion_form": {}, "function": 12345, "active": true } } ``` Guarde o `id` da instância, `12348` na resposta acima. A regra do próximo estágio nomeia esse id, nunca o id da função. --- ## Execute a instância por uma regra do Rules Engine Uma regra do [Rules Engine for Firewall](/pt-br/documentacao/plataforma/firewall/rules-engine/) decide quais requisições alcançam a instância. O seu comportamento `run_function` nomeia uma instância, e a regra abaixo executa a sua em toda requisição que o firewall recebe. > **Atenção** > > Baseie o critério na URI da requisição. Um critério como `${request_args}` `matches` `.*` não corresponde a uma requisição que não carrega query string, então ele pula todo `POST` cujo payload está no corpo. **Console** Para criar a regra no Azion Console: 1. **Abra a aba Rules Engine** Em Azion Console, vá até **Firewalls**, selecione o seu firewall e depois selecione a aba **Rules Engine**. 2. **Selecione + Rule** 3. **Nomeie a regra** Informe um nome para a regra. Por exemplo: `Run Bot Manager on every request`. A descrição é opcional. 4. **Defina o critério** Na seção **Criteria**, selecione a variável `Request Uri`, o operador *starts with* e `/` como argumento. 5. **Acrescente o comportamento Run Function** Na seção **Behaviors**, selecione **Run Function**. Um segundo controle aparece, com o placeholder `Select an function`: ele lista as instâncias de função deste firewall, então selecione a que você nomeou. 6. **Salve a regra** O firewall executa a instância em toda requisição que recebe. Uma regra carrega no máximo um comportamento **Run Function**. **CLI** `azion create firewall-rule` lê a regra inteira de um arquivo JSON. Ele não tem flag para um critério ou um comportamento. 1. **Escreva a regra em um arquivo** Salve o seguinte como `rule.json`, com o id da sua instância em `value`: ```json { "name": "Run Bot Manager on every request", "active": true, "criteria": [ [ { "conditional": "if", "variable": "${request_uri}", "operator": "starts_with", "argument": "/" } ] ], "behaviors": [ { "type": "run_function", "attributes": { "value": 12347 } } ] } ``` 2. **Crie a regra** Substitua `` pelo id do seu firewall: ```bash azion create firewall-rule --firewall-id --file rule.json ``` 3. **Leia a saída** O comando imprime o id da nova regra: ```text Created Firewall Rule with ID 123458 ``` O firewall executa a instância em toda requisição que recebe. A chave do comportamento é `type`: um arquivo que escreve `name` no lugar é recusado com `Failed to decode the given 'json' file`, que não nomeia nem o campo nem o motivo. **API** Os critérios carregam `${request_uri}`, então o corpo é enviado a partir de um arquivo. 1. **Escreva a regra em um arquivo** Salve o seguinte como `rule.json`, com o id da sua instância em `value`: ```json { "name": "Run Bot Manager on every request", "active": true, "criteria": [ [ { "conditional": "if", "variable": "${request_uri}", "operator": "starts_with", "argument": "/" } ] ], "behaviors": [ { "type": "run_function", "attributes": { "value": 12348 } } ] } ``` 2. **Envie a requisição de criação** Substitua `` pelo id do seu firewall: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/firewalls//request_rules \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data @rule.json ``` 3. **Leia a resposta** A chamada responde `202`. A resposta devolve a regra e acrescenta o `order` que a plataforma atribui a ela, que é `0` para a primeira regra do firewall. O firewall executa a instância em toda requisição que recebe. A chave do comportamento é `type`, e `attributes.value` guarda o id da instância, nunca o id da função. --- ## Verifique que uma requisição é pontuada A verificação é a mesma qualquer que seja a interface que construiu a instância. O seu workload responde em um domínio no formato `.map.azionedge.net`, escrito abaixo como ``. Uma instância nova e uma regra nova levam tempo para alcançar a infraestrutura distribuída da Azion. Uma mudança em uma instância chega ao caminho das requisições em cerca de dois minutos. Espere antes de ler qualquer coisa em uma resposta. Verifique lendo o log de report, não tentando ser recusado. No threshold de `30` que este guia define, uma requisição com formato de bot é pontuada e ainda assim servida, então o log é onde o resultado está. Envie uma requisição sem user agent, que é o que um cliente programado envia: ```bash curl -A "" https:/// ``` Depois leia a linha que a função escreveu. O log de report é servido pelo dataset `functionConsoleEvents`. Envie a consulta abaixo para `https://api.azion.com/v4/events/graphql` com um cabeçalho `Authorization: Token [TOKEN VALUE]`, e um `tsRange` que cubra o momento da requisição: ```graphql { functionConsoleEvents( limit: 200 filter: { tsRange: { begin: "2026-01-01T11:30:00", end: "2026-01-01T13:00:00" } } orderBy: [ts_ASC] ) { ts line level lineSource functionId configurationId } } ``` A consulta responde `200` e devolve um registro por linha que a função escreveu. `functionId` é o id da função instalada, e `configurationId` é o id do workload em que a requisição chegou, não o id do firewall. `line` carrega a linha de report inteira, que abre com o prefixo e continua como um objeto JSON: ```text [Bot-Protection][storefront-bots] Report: {"request_id":"0123456789abcdef0123456789abcdef","remote_addr":"203.0.113.42","fingerprint":"ge20cn020000_000000000000_000000000000_000000000000","host":"","http_user_agent":"","request_uri":"/","geoip_country":"BR","geoip_region":"SP","asn":"64496","score":28,"bot_category":"Bad Bot Signatures, Malicious Intent detected","classified":"legitimate","action":"allow","matched_rules":[1,10,18,19,20]} ``` O segundo colchete do prefixo carrega a `log_tag` que você definiu, que é como você separa uma instância de outra. Quatro valores no objeto respondem à pergunta que este guia fez. `score` é `28`. `matched_rules` é `[1, 10, 18, 19, 20]`, as regras que produziram essa pontuação, entre elas a regra `1` pelo user agent vazio. `action` se lê `allow`, e `classified` se lê `legitimate`. Para cada campo que uma linha carrega, consulte [Logs](/pt-br/documentacao/plataforma/firewall/bot-manager/logs/#campos). Nada foi recusado, e esse é o resultado a esperar: `28` está abaixo do threshold de `30`, então a pontuação nunca alcançou o valor a partir do qual `deny` é executado. A requisição foi inspecionada, pontuada e servida, que é o que você se propôs a provar. O que um threshold mais baixo muda é a ação, não a pontuação. Uma requisição cuja pontuação alcança o threshold recebe `action`, e `deny` responde `HTTP 403` com a página de erro padrão da Azion. A classificação se move junto com o threshold: `classified` é um veredito relativo ao threshold em vigor, então a mesma pontuação de `28`, das mesmas regras correspondidas, se lê `legitimate` sob um threshold de `30` e `bad bot` sob um threshold que `28` alcança. Aprenda quanto o seu próprio tráfego pontua antes de reduzi-lo. --- ## Próximos passos - [Score de bots](/pt-br/documentacao/plataforma/firewall/bot-manager/score-de-bots.md): O caminho que uma requisição percorre, como uma pontuação é formada pelas regras que ela corresponde e o que os cookies de sessão fazem. - [Argumentos](/pt-br/documentacao/plataforma/firewall/bot-manager/argumentos.md): Cada argumento que uma instância aceita, com o seu tipo, o seu padrão e os valores que assume. - [Boas práticas de Firewall](/pt-br/documentacao/plataforma/firewall/boas-praticas.md#bot-manager): Como executar uma janela de observação antes de um threshold recusar qualquer coisa, e o que cada prática custa. - [Solucionar problemas de Firewall](/pt-br/documentacao/plataforma/firewall/solucao-de-problemas.md#bot-manager): O que fazer quando um cliente recebe uma resposta inesperada, ou quando uma linha de report que você espera está faltando.