# Argumentos Uma instância de função do Bot Manager tira toda a sua configuração de um objeto JSON. O objeto define a pontuação a partir da qual a função age, a ação que ela toma, os cabeçalhos que ela escreve no log de report e as regras que ela deixa de pontuar. Azion Console o renderiza como a seção **Arguments** de uma instância de função, na aba **Functions Instances** do firewall. A Azion API e o Azion CLI carregam o mesmo objeto como `args`. O Bot Manager e o [Bot Manager Lite](/pt-br/documentacao/plataforma/firewall/bot-manager/bot-manager-lite/) são configurados por esse objeto, e nenhum argumento é obrigatório. A função instalada do Bot Manager Lite não carrega esquema de argumentos, então o editor de **Arguments** não tem formulário para construir a partir dele e o objeto é escrito como JSON puro. Esta página lista os argumentos que uma instância carrega, com os seus tipos e padrões, os valores que `action`, `mode` e `engine_version` aceitam, os quatro argumentos que configuram as regras dinâmicas e o objeto recomendado como ponto de partida. --- ## Campos O objeto de argumentos é livre, e nada o valida. Toda chave enviada é armazenada e devolvida sem alteração, leia a função essa chave ou não. Por exemplo, uma chave que a função nunca lê, como `totally_bogus_key_xyz`, é armazenada e devolvida byte a byte. Um argumento escrito errado é, portanto, aceito e guardado. Enviar `thresold: 5` armazena uma chave que a função nunca lê, deixa o threshold no seu padrão e não levanta erro em nenhuma interface. Um argumento só tem efeito sob o nome exato que a função lê. Uma instância também não copia os padrões da função para o seu próprio registro. Uma instância criada com um objeto vazio armazena `{}`, e os padrões abaixo são aplicados quando a função é executada. Ler uma instância mostra, portanto, quais argumentos a instância define, não os valores com que a função é executada. O Bot Manager Lite v0.2.0 entrega um padrão para oito argumentos. Uma instância que não define nenhum deles é executada com os valores abaixo. | Argumento | Tipo | Padrão | O que faz | | ----------------------- | ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | `action` | string | `deny` | O que a função faz com uma requisição cuja pontuação alcança o threshold. Os valores estão listados em Action | | `bad_fingerprint_list` | array de strings | `[]` | Os fingerprints que a função trata como ruins | | `disabled_rules` | array de números | `[]` | Os IDs das regras que a função pula | | `good_fingerprint_list` | array de strings | `[]` | Os fingerprints que a função deixa passar | | `internal_logs` | number | `0` | Para quais requisições a função escreve uma linha de log | | `log_headers` | array de strings | Os nove cabeçalhos listados em Log headers | Os cabeçalhos de requisição que a função escreve no log de report | | `log_tag` | string | `bot-manager-instance` | A tag que identifica a instância de onde veio uma linha de log | | `threshold` | number | `30` | A pontuação que uma requisição alcança antes de `action` ser executada | Os oito são entregues com a função do Bot Manager Lite, e o Bot Manager também documenta `action`, `log_headers`, `log_tag` e `threshold`. Três desses padrões mudam conforme a edição, e cada um é coberto na sua própria seção abaixo: `action` chega como `deny` no Bot Manager Lite contra um `allow` documentado no Bot Manager, então uma instância que não define nenhum dos dois recusa requisições em uma edição e as deixa passar na outra; `threshold` chega como `30` contra um `Infinity` documentado; e `log_tag`, não definido no Bot Manager, assume o cabeçalho `host` que a requisição carregou. Duas instâncias que mantêm o `bot-manager-instance` entregue são indistinguíveis nos logs. Os argumentos abaixo não carregam padrão entregue. **Documentado para** nomeia a edição cuja referência carrega o argumento, e **Padrão documentado** é o valor que essa referência informa. | Argumento | Tipo | Padrão documentado | Documentado para | O que faz | | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `block_ai_bots` | boolean | `false` | Bot Manager Lite | Bloqueia uma requisição de um user agent de IA conhecido, sem executar as outras regras de análise | | `custom_html` | string | — | As duas edições | O HTML que a ação `custom_html` devolve. Sem valor, ou com um valor inválido, a função executa `allow` | | `custom_status_code` | number | `200` | As duas edições | O status code da resposta `custom_html` | | `disable_dynamic_rules` | boolean | `false` | Bot Manager | Desliga o método de regras dinâmicas | | `disabled_static_rules` | array de números | `[]` | Bot Manager | Os IDs das regras que continuam sendo executadas e param de somar à pontuação | | `dynamic_rules_baseline` | number | `0` | Bot Manager | Um multiplicador percentual sobre a referência calculada | | `dynamic_rules_logs_enabled` | boolean | `false` | Bot Manager | Escreve os logs de depuração das regras dinâmicas | | `dynamic_rules_tolerance` | string | `soft` | Bot Manager | O quão rigoroso é o método de regras dinâmicas. Os valores estão listados em Regras dinâmicas | | `engine_version` | number | `1` | Bot Manager | O engine que identifica o cliente. Os valores estão listados em Engine version | | `mode` | string | `web` | Bot Manager | O tipo de cliente que a função está pontuando. Os valores estão listados em Mode | | `redirect_to` | string (URI) | — | As duas edições | A URL ou o caminho relativo para onde a ação `redirect` envia a requisição. Sem valor, ou com um valor inválido, a função executa `allow` | | `reputation_network_lists` | array de números | `[]` no Bot Manager Lite, as Network Lists gerenciadas pela Azion na conta, no Bot Manager | As duas edições | As Network Lists contra as quais o IP da requisição é verificado. Uma correspondência eleva a pontuação, uma vez para cada lista em que o IP é encontrado | | `session_signature_key` | string | `az` no Bot Manager Lite, `azion` no Bot Manager | As duas edições | Assina o valor do cookie de sessão `az_asm` | | `should_write_warning_logs` | boolean | `false` | Bot Manager Lite | Se a função escreve logs de aviso no [Real-Time Events](/pt-br/documentacao/plataforma/real-time-events/) | O objeto inteiro é limitado por tamanho, e o nome de uma instância por comprimento. Para mais informações, consulte [Limites de Firewall](/pt-br/documentacao/plataforma/firewall/limites/#bot-manager). --- ## Threshold `threshold` é a pontuação que uma requisição alcança antes de o Bot Manager tomar a ação configurada. Uma requisição igual ou acima dele recebe a ação, e uma requisição abaixo dele segue. A pontuação vem das regras que a função executa contra a requisição. Para mais informações, consulte [Score de bots](/pt-br/documentacao/plataforma/firewall/bot-manager/score-de-bots/). O Bot Manager Lite v0.2.0 entrega um threshold de `30`. O Bot Manager documenta um padrão de `Infinity`: uma instância que não define threshold nunca alcança um, então toda requisição passa. Em `0` toda requisição está no threshold ou acima dele, então a ação configurada é executada em todas as requisições. O que isso significa depende da ação: com `action` definido como `deny`, toda requisição é recusada, e com `action` definido como `allow`, nada é bloqueado. O Bot Manager documenta uma exceção em `0`, um usuário que já resolveu um desafio ALTCHA, onde o ALTCHA está em uso. --- ## Action `action` nomeia o que a função faz com uma requisição cuja pontuação está no threshold ou acima dele. O Bot Manager Lite v0.2.0 entrega `deny`, e o padrão documentado no Bot Manager é `allow`. Um valor fora dos sete abaixo é lido como `allow`. | Valor | O que a função faz | | ----------------- | ------------------------------------------------------------------------------------ | | `allow` | Deixa a requisição seguir, qualquer que seja a pontuação dela | | `custom_html` | Devolve o HTML em `custom_html`, com o status code em `custom_status_code` | | `deny` | Devolve uma resposta `403` com a página de erro padrão da Azion | | `drop` | Encerra a requisição sem resposta | | `hold_connection` | Mantém a conexão aberta por 1 minuto e depois descarta a requisição | | `random_delay` | Espera um período aleatório entre 1 e 10 segundos e depois deixa a requisição seguir | | `redirect` | Redireciona a requisição para o endereço em `redirect_to` | Duas das sete exigem um segundo argumento: `custom_html` carrega o HTML a devolver, e `redirect_to` o endereço para onde enviar a requisição. Quando esse segundo argumento está ausente ou não é uma string, a função executa `allow` no lugar, e um `custom_status_code` ausente ou que não seja um número é lido como `200`. --- ## Mode `mode` diz à função que tipo de cliente ela está pontuando. O Bot Manager o documenta com um padrão de `web`. | Valor | Para que serve | | ----- | ------------------------------------------------------- | | `api` | Web services e tráfego de API que não carrega cookies | | `web` | Clientes HTTP compatíveis com cookies, como navegadores | A comparação diferencia maiúsculas de minúsculas e é em minúsculas. Qualquer valor diferente de `api` é lido como `web`, então `API` e `Api` selecionam o modo `web`. --- ## Engine version `engine_version` seleciona o engine que identifica o cliente por trás de uma requisição. O seu padrão documentado no Bot Manager é `1`. | Valor | O engine | | ----- | ----------------------------------------------------------------------------------------- | | `1` | O padrão, e o fallback quando `engine_version` está ausente ou é inválido | | `2` | Um método baseado em sessão JA4H, que produz menos colisões entre dispositivos do que `1` | Uma colisão são dois usuários ou dispositivos distintos que compartilham um fingerprint e são pontuados como uma identidade só. --- ## Regras dinâmicas Quatro argumentos configuram o método de regras dinâmicas, e o Bot Manager documenta os quatro. `disable_dynamic_rules` definido como `true` desliga o método. `dynamic_rules_logs_enabled` definido como `true` escreve os logs de depuração do método, que o Bot Manager documenta apenas para depuração. `dynamic_rules_tolerance` define o quão rigoroso o método é: | Valor | O quão rigoroso é | | -------- | ------------------------------------------------------------------ | | `soft` | O menos rigoroso, e o padrão. Um valor inválido é lido como `soft` | | `medium` | Entre `soft` e `hard` | | `hard` | O mais rigoroso | `dynamic_rules_baseline` ajusta a referência contra a qual o método compara uma requisição. É um multiplicador percentual, e uma referência mais baixa detecta com mais rigor: `0.1` eleva a referência em 10%, e `-0.234` a reduz em 23,4%. O padrão documentado é `0`. --- ## Regras desabilitadas Dois argumentos impedem que uma regra eleve a pontuação de uma requisição. `disabled_rules` carrega os IDs das regras para o Bot Manager Lite e é entregue como um array vazio. `disabled_static_rules` os carrega para o Bot Manager, com um array vazio como padrão documentado. Uma regra nomeada em `disabled_static_rules` continua sendo executada. Cada vez que uma requisição corresponde a ela, o ID da regra vai para o campo `disabled_matched_rules` do log de report e a regra não soma nada à pontuação. Uma regra desabilitada desse jeito continua, portanto, sendo contada, e as suas correspondências continuam visíveis depois que ela para de elevar a pontuação. Os IDs vêm dos seus próprios logs, onde o log de report nomeia cada regra que uma requisição correspondeu. Para mais informações, consulte [Logs](/pt-br/documentacao/plataforma/firewall/bot-manager/logs/). As regras que o Bot Manager Lite executa, cada uma com o seu ID e a pontuação que soma, estão listadas em [Bot Manager Lite](/pt-br/documentacao/plataforma/firewall/bot-manager/bot-manager-lite/). --- ## Log headers `log_headers` nomeia os cabeçalhos de requisição que a função escreve no seu log de report. O Bot Manager Lite v0.2.0 entrega nove deles: `accept`, `accept-encoding`, `accept-language`, `content-type`, `host`, `referer`, `user-agent`, `x-forwarded-for` e `x-request-id`. Sete cabeçalhos são proibidos e não podem ser registrados, qualquer que seja o conteúdo do array: `authorization`, `cookie`, `proxy-authorization`, `set-cookie`, `x-csrf-token`, `x-api-key` e `x-amz-security-token`. Os valores dos cabeçalhos são escritos em base64. Um valor lido do log é decodificado antes de ser comparado com o valor que o cliente enviou. --- ## Argumentos recomendados O Bot Manager documenta um objeto de argumentos como ponto de partida para uma instância nova: ```json { "threshold": 18, "action": "deny", "log_tag": "bot_manager", "mode": "web", "reputation_network_lists": [], "disabled_static_rules": [], "dynamic_rules_tolerance": "soft", "log_headers": [ "accept", "accept-encoding", "accept-language", "content-type", "host", "referer", "user-agent", "x-forwarded-for", "x-request-id" ] } ``` O threshold de `18` fica abaixo do `30` que o Bot Manager Lite entrega, então a ação é executada em mais requisições do que com o padrão entregue. Quatro das suas chaves, `mode`, `reputation_network_lists`, `disabled_static_rules` e `dynamic_rules_tolerance`, não estão entre os oito argumentos para os quais o Bot Manager Lite entrega um padrão. O threshold e a ação são os dois valores a calibrar contra o seu próprio tráfego. Para mais informações, consulte [Boas práticas de Firewall](/pt-br/documentacao/plataforma/firewall/boas-praticas/#bot-manager). --- ## Recursos relacionados - [Score de bots](/pt-br/documentacao/plataforma/firewall/bot-manager/score-de-bots.md): A pontuação com que o threshold é comparado, e o caminho que uma requisição percorre pela função. - [Logs](/pt-br/documentacao/plataforma/firewall/bot-manager/logs.md): O log de report em que estes argumentos escrevem, campo por campo. - [Network Lists](/pt-br/documentacao/plataforma/firewall/network-shield/network-lists.md): As listas contra as quais `reputation_network_lists` verifica o IP de uma requisição, e como criar uma. - [Rules Engine for Firewall](/pt-br/documentacao/plataforma/firewall/rules-engine.md): A regra que executa a instância de função que estes argumentos configuram.