aa-discord-audit

Auditoría de reconciliación para la integración de Discord de Alliance Auth. Compara las asignaciones de roles reales en el guild de Discord configurado con el estado expresado en Alliance Auth (Grupos + Estado por usuario) y cierra la brecha por la cual los moderadores pueden asignar manualmente roles con nombre de AA a usuarios que AA no conoce.

Estado: alpha (0.1.x). La API pública y la configuración aún pueden cambiar antes de 1.0.

Contenido

• Postura de seguridad
• Cómo funciona
• Requisitos
• Instalación
• Inicio rápido
• Permisos
• Configuración
• Comandos de gestión
• Auditoría periódica (Celery beat)
• Tareas de Celery
• Panel del operador
• Observabilidad
• Limitaciones
• Documentación
• Desarrollo
• CI de merge request

Postura de seguridad

La auditoría es segura por defecto:

• La primera ejecución tras la instalación está bloqueada en modo dry-run independientemente de la configuración del operador. Liberar el bloqueo requiere un InitialAuditAcknowledgement explícito (solo admin o shell).
• La política por defecto es report para cada categoría — las acciones destructivas son opt-in.
• Las filas del registro de auditoría (AuditRun, AuditFinding, AuditInvocation, ConfigChangeLog) son de solo añadir en las capas de manager e instancia; update() / bulk_update() masivos están bloqueados.
• Las URLs de webhook se tratan como credenciales y se redactan de los logs, mensajes de excepción y argv persistido.

Cómo funciona

Cada miembro del guild se clasifica en una categoría:

Categoría	Significado
unknown_guest	Miembro de Discord del que AA no sabe nada
linked_no_perm	Identidad conocida por AA pero sin discord.access_discord
bot_filtered	Cuenta de bot configurada — nunca se actúa sobre ella

El operador asigna a cada categoría una acción:

Acción	Comportamiento
report	Registra el hallazgo; sin cambios en Discord
strip	Elimina los roles gestionados por AA
strip_kick	Elimina los roles gestionados por AA y luego expulsa del guild

La asignación es la configuración AA_DISCORD_AUDIT_POLICY; las anulaciones por grupo y por estado se anidan dentro de cada categoría.

Requisitos

• Python 3.10–3.13
• Django 5.2
• Alliance Auth 5.x
• El módulo de servicio Discord de Alliance Auth (allianceauth.services.modules.discord) instalado y configurado (token de bot + guild)

Instalación

pip install aa-discord-audit

En tu local.py de Auth:

# `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",
]

Luego ejecuta las migraciones:

python manage.py migrate aa_discord_audit

El CurrentUserMiddleware es obligatorio — apps.ready() lanza ImproperlyConfigured si falta. Es lo que permite que el manejador de señales de ConfigChangeLog atribuya las ediciones de administración a un usuario real en lugar de a <system>.

Inicio rápido

1. Conceda aa_discord_audit.run_audit al rol de operador que ejecuta las auditorías.

2. Ejecute una auditoría en modo de prueba (dry-run):

   python manage.py audit_discord_roles --action report
   

3. Revise los hallazgos en Discord Audit → Audit runs en el panel de Auth.

4. Libere el bloqueo de primera ejecución — ya sea creando una fila InitialAuditAcknowledgement a través del admin, o ejecutando python manage.py audit_acknowledge_initial. Ambos requieren aa_discord_audit.run_audit y aa_discord_audit.acknowledge_initial_audit.

5. Vuelva a ejecutar con la acción destructiva de su elección cuando esté listo.

Permisos

Codename	Controla
aa_discord_audit.run_audit	comando de gestión, tarea beat, eliminación de ejecuciones
aa_discord_audit.run_audit_destructive	puerta de lanzamiento web para strip / strip_kick (separada de run_audit)
aa_discord_audit.acknowledge_initial_audit	libera el bloqueo de ejecución en seco de primera ejecución
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 (y similares)	registro de auditoría de solo lectura en el panel de Auth

Los codenames manage_* están divididos según su radio de impacto para que un usuario junior con manage_bot_account_uid no pueda también desactivar la auditoría editando ManagedRoleException.

Configuración

Todas las configuraciones son opcionales. Los valores predeterminados son 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