Como Auditar Alterações de Permissão no Discord com Bot que Consulta o Log de Auditoria

Você precisa rastrear quem alterou uma permissão de cargo ou substituição de canal no seu servidor Discord. A revisão manual do log de auditoria é lenta e não confiável para servidores grandes. O Discord fornece um endpoint REST API que permite que bots consultem o log de auditoria programaticamente. Este artigo explica como configurar um bot que usa o endpoint Get Guild Audit Log para capturar alterações de permissão automaticamente.

Como o Endpoint do Log de Auditoria do Discord Funciona para Auditoria de Permissões

A API de Log de Auditoria do Discord permite que bots recuperem as entradas do log de auditoria de um servidor. Cada entrada contém um tipo de ação, o usuário que realizou a ação, o objeto alvo (cargo, canal ou membro) e um array de alterações que lista o que foi modificado. Para alterações de permissão, os tipos de ação relevantes são 24 para atualizações de cargo de membro, 31 para atualizações de substituição de canal, 3 para criação de cargo, 4 para exclusão de cargo, 5 para atualização de cargo (inclui alterações no campo de bits de permissão) e 10 para atualização de canal (inclui substituições de permissão).

O endpoint tem limite de taxa. Os bots podem fazer 10 requisições a cada 60 segundos por servidor. Cada requisição retorna até 100 entradas. Para capturar todas as alterações, você deve consultar o endpoint repetidamente e armazenar o ID da última entrada processada para evitar duplicatas.

Pré-requisitos para Usar o Endpoint do Log de Auditoria

Antes de escrever código, certifique-se de que seu bot tenha o seguinte:

• A permissão view_audit_log (valor binário 0x80) no servidor alvo.
• Um token de bot com o escopo bot e a intent guilds ativada.
• Acesso ao ID do servidor onde você deseja auditar alterações de permissão.

Passos para Construir um Bot que Consulta o Log de Auditoria em Busca de Alterações de Permissão

Os passos a seguir usam Python com a biblioteca discord.py versão 2.3 ou posterior. Você pode adaptar a lógica para outras linguagens e bibliotecas.

1. Instale o discord.py e configure o cliente do bot
   Execute pip install discord.py. Crie um cliente do bot com intents.default() e intents.guilds = True. Substitua YOUR_BOT_TOKEN pelo seu token real.
2. Defina as constantes dos tipos de ação do log de auditoria
   Importe o enum AuditLogAction do discord.py. As constantes necessárias são AuditLogAction.member_role_update (24), AuditLogAction.channel_overwrite_update (31), AuditLogAction.role_update (5) e AuditLogAction.channel_update (10).
3. Crie uma função de consulta que busca entradas do log de auditoria
   Defina uma função assíncrona que chama guild.audit_logs(limit=100, after=last_entry_id). O parâmetro after garante que você obtenha apenas novas entradas desde a última consulta. Armazene last_entry_id em um arquivo ou banco de dados.
4. Filtre as entradas por tipo de ação e extraia os detalhes das alterações
   Percorra as entradas retornadas. Para cada entrada, verifique entry.action em relação aos tipos de ação relevantes. Se corresponder, extraia entry.user (o moderador), entry.target (o cargo ou canal) e entry.changes (uma lista de objetos AuditLogChange). Cada alteração tem valores before e after.
5. Analise o array de alterações para identificar modificações de permissão
   Para atualizações de cargo, as alterações incluem permissions (um campo de bits). Compare before.value e after.value usando operações bit a bit para determinar quais bits de permissão foram adicionados ou removidos. Para substituições de canal, as alterações incluem campos de bits allow e deny para o alvo da substituição.
6. Registre ou envie os dados de auditoria para um canal designado
   Formate os dados extraídos em uma mensagem legível. Use um embed com campos para usuário, alvo, tipo de ação e permissões alteradas. Envie o embed para um canal de registro privado usando channel.send(embed=embed).
7. Execute o loop de consulta em um temporizador
   Use tasks.loop(seconds=10) do discord.py para executar a função de consulta a cada 10 segundos. Isso respeita o limite de taxa enquanto mantém o log de auditoria relativamente atualizado.

Problemas Comuns e Limitações ao Consultar o Log de Auditoria

O Bot Não Vê Entradas Recentes do Log de Auditoria

O endpoint do log de auditoria retorna apenas entradas que o bot tem permissão para ver. Se o bot não tiver a permissão view_audit_log em um canal ou cargo específico, ele pode não ver entradas relacionadas a esse objeto. Conceda ao bot a permissão Administrator temporariamente para teste e depois reduza para as permissões mínimas necessárias.

Limites de Taxa Causam Perda de Entradas

Se o intervalo de consulta for maior que 10 segundos, você pode perder entradas se muitas alterações ocorrerem em um curto período. O endpoint do log de auditoria tem um limite de 10 requisições por minuto por servidor. Defina seu intervalo de consulta para 6 segundos ou mais para ficar abaixo do limite. Se você precisar de auditoria quase em tempo real, considere usar os eventos do Gateway do Discord em vez de consultas.

Objetos de Alteração Contêm Campos de Bits Opacos

Os valores before e after para alterações de permissão são inteiros que representam campos de bits. Você deve decodificá-los usando as constantes de flags de permissão do Discord. No discord.py, use Permissions(before.value) para converter em um objeto Permissions legível. Em seguida, compare os objetos Permissions para listar permissões adicionadas e removidas.

IDs de Entrada Não São Sequenciais Entre Reinicializações

Se o seu bot reiniciar, o last_entry_id armazenado pode estar desatualizado. O endpoint do log de auditoria retorna entradas em ordem cronológica reversa. Sempre use o parâmetro after com o ID da última entrada processada com sucesso. Se você perder o ID armazenado, comece a partir do horário atual e aceite que pode perder entradas do período de inatividade.

Item	Consulta via REST API	Eventos do Gateway (GUILD_AUDIT_LOG_ENTRY_CREATE)
Entrega em tempo real	Não, consultado a cada N segundos	Sim, enviado imediatamente
Limite de taxa	10 requisições a cada 60 segundos por servidor	Sem limite de taxa no recebimento de eventos
Complexidade de implementação	Baixa, requisições HTTP simples	Média, requer intent e manipulador de eventos
Integridade dos dados	Pode perder entradas entre consultas	Completa se a conexão for estável
Requisito de permissão	view_audit_log	view_audit_log

A tabela acima compara os dois principais métodos para capturar dados do log de auditoria. Para a maioria das necessidades de auditoria de permissão, a consulta é suficiente e mais fácil de implementar. Use a abordagem de evento do Gateway apenas se você precisar de notificação em menos de um segundo.

Agora você pode construir um bot que consulta o endpoint do log de auditoria do Discord para rastrear alterações de permissão no seu servidor. Comece implementando o loop de consulta com um intervalo de 10 segundos e armazenando o ID da última entrada processada em um banco de dados persistente. Para auditoria avançada, considere combinar a abordagem de consulta com uma tarefa em segundo plano que também ouça o evento de Gateway GUILD_AUDIT_LOG_ENTRY_CREATE para reduzir a latência. Sempre teste seu bot em um servidor pequeno antes de implantar em produção para garantir que a lógica de filtragem de permissão funcione corretamente.