aa-discord-audit

Auditoria de reconciliação para a integração Discord do Alliance Auth. Compara as atribuições de cargos reais na guild Discord configurada com o estado expresso no Alliance Auth (Grupos + Estado por usuário) e fecha a lacuna pela qual moderadores podem atribuir manualmente cargos com nomes AA a usuários que o AA não conhece.

Status: alpha (0.1.x). A API pública e as configurações ainda podem mudar antes da 1.0.

Conteúdo

• Postura de segurança
• Como funciona
• Requisitos
• Instalação
• Início rápido
• Permissões
• Configurações
• Comandos de gerenciamento
• Auditoria periódica (Celery beat)
• Tarefas Celery
• Painel do operador
• Observabilidade
• Limitações
• Documentação
• Desenvolvimento
• CI de merge request

Postura de segurança

A auditoria é segura por padrão:

• A primeira execução após a instalação fica travada em modo dry-run independentemente das configurações do operador. A liberação do bloqueio exige um InitialAuditAcknowledgement explícito (somente admin ou shell).
• A política padrão é report para todas as categorias — ações destrutivas são opt-in.
• As linhas de trilha de auditoria (AuditRun, AuditFinding, AuditInvocation, ConfigChangeLog) são somente-adição nas camadas de manager e instância; update() / bulk_update() em massa são bloqueados.
• URLs de webhook são tratadas como credenciais e ocultadas dos logs, mensagens de exceção e argv persistido.

Como funciona

Cada membro da guild é classificado em uma categoria:

Categoria	Significado
unknown_guest	Membro do Discord sobre o qual o AA não sabe nada
linked_no_perm	Identidade conhecida pelo AA, mas sem discord.access_discord
bot_filtered	Conta de bot configurada — nunca sofre ação

O operador mapeia cada categoria para uma ação:

Ação	Comportamento
report	Registra a descoberta; nenhuma alteração no lado do Discord
strip	Remove cargos gerenciados pelo AA
strip_kick	Remove cargos gerenciados pelo AA e depois expulsa da guild

O mapeamento é a configuração AA_DISCORD_AUDIT_POLICY; substituições por grupo e por estado aninham-se dentro de cada categoria.

Requisitos

• Python 3.10–3.13
• Django 5.2
• Alliance Auth 5.x
• Módulo de serviço Discord do Alliance Auth (allianceauth.services.modules.discord) instalado e configurado (token do bot + guild)

Instalação

pip install aa-discord-audit

No seu Auth local.py:

# `aa_discord_audit` must appear AFTER
# `allianceauth.services.modules.discord` so the discord module's
# models load first; `apps.ready()` raises `ImproperlyConfigured`
# otherwise.
INSTALLED_APPS += ["aa_discord_audit"]

MIDDLEWARE += [
    "aa_discord_audit.current_user.CurrentUserMiddleware",
]

Em seguida, execute as migrações:

python manage.py migrate aa_discord_audit

O CurrentUserMiddleware é obrigatório — apps.ready() lança ImproperlyConfigured se estiver ausente. É ele que permite ao manipulador de sinal do ConfigChangeLog atribuir edições de administrador a um utilizador real em vez de <system>.

Início rápido

1. Conceda aa_discord_audit.run_audit à função de operador que executa auditorias.

2. Execute uma auditoria de simulação (dry-run):

   python manage.py audit_discord_roles --action report
   

3. Revise os resultados em Discord Audit → Audit runs no painel Auth.

4. Libere o bloqueio de primeira execução — crie uma linha InitialAuditAcknowledgement através do admin, ou execute python manage.py audit_acknowledge_initial. Ambos exigem aa_discord_audit.run_audit e aa_discord_audit.acknowledge_initial_audit.

5. Execute novamente com a ação destrutiva de sua escolha quando estiver pronto.

Permissões

Codename	Controla
aa_discord_audit.run_audit	comando de gerenciamento, tarefa beat, exclusão de execução
aa_discord_audit.run_audit_destructive	gate de lançamento web para strip / strip_kick (separado de run_audit)
aa_discord_audit.acknowledge_initial_audit	libera o bloqueio de execução em modo dry-run da primeira execução
aa_discord_audit.manage_discord_identity	admin de DiscordIdentity
aa_discord_audit.manage_role_exception	admin de ManagedRoleException
aa_discord_audit.manage_protected_member	admin de ProtectedDiscordMember
aa_discord_audit.manage_bot_account_uid	admin de BotAccountUid
aa_discord_audit.manage_finding_override	admin de FindingActionOverride
aa_discord_audit.view_auditrun (e similares)	trilha de auditoria somente leitura no painel Auth

Os codenames manage_* são divididos por raio de impacto para que um júnior com manage_bot_account_uid não possa também enfraquecer a auditoria editando ManagedRoleException.

Configurações

Todas as configurações são opcionais. Os padrões são seguros.

# Action policy. Bare-string form below is shorthand for
# {"default": "<action>"}; use the nested form for per-group / per-state
# overrides keyed by AA group name and state name.
AA_DISCORD_AUDIT_POLICY = {
    "unknown_guest":  "report",
    "linked_no_perm": "report",
    # "strip" is rejected at startup for linked_no_perm (it conflicts with
    # AA's update_groups task); use "strip_kick" instead.
    # "linked_no_perm": {
    #     "default":  "strip_kick",
    #     "by_state": {"Guest": "report"},
    #     "by_group": {"Directors": "report"},
    # },
}

# AA-notify fan-out to permission holders.
AA_DISCORD_AUDIT_NOTIFY_ADMINS = True

# Discord webhook for run summaries. Treat as a credential.
AA_DISCORD_AUDIT_WEBHOOK_URL = None

# uids skipped as bot accounts (in addition to the BotAccountUid admin
# table).
AA_DISCORD_AUDIT_BOT_UIDS = []

# Auto-discover bot accounts by Discord nickname heuristics. Reserved
# for v2; not implemented in the MVP. The startup validator raises
# ImproperlyConfigured if set to True — keep this False and use the
# explicit BotAccountUid admin table instead.
AA_DISCORD_AUDIT_AUTO_DISCOVER_BY_NICKNAME = False

# Retention. 0 disables pruning; the validator refuses 0 unless the
# acknowledged flag below is also set.
AA_DISCORD_AUDIT_RUN_RETENTION_DAYS = 180
AA_DISCORD_AUDIT_RETENTION_OPT_OUT_ACKNOWLEDGED = False