Argumentos
Consulte cada argumento que uma instância de função do Bot Manager aceita, com o tipo, o padrão e os valores que ele assume.
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 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 |
O objeto inteiro é limitado por tamanho, e o nome de uma instância por comprimento. Para mais informações, consulte Limites de Firewall.
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.
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. 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.
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:
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.