aa-discord-audit

Audit de réconciliation pour l'intégration Discord d'Alliance Auth. Compare les attributions de rôles réelles dans la guilde Discord configurée à l'état exprimé dans Alliance Auth (Groupes + État par utilisateur) et comble l'écart par lequel les modérateurs peuvent attribuer manuellement des rôles portant le nom AA à des utilisateurs qu'AA ne connaît pas.

Statut : alpha (0.1.x). L'API publique et les paramètres peuvent encore changer avant la 1.0.

Sommaire

• Posture de sécurité
• Fonctionnement
• Prérequis
• Installation
• Démarrage rapide
• Permissions
• Paramètres
• Commandes de gestion
• Audit périodique (Celery beat)
• Tâches Celery
• Tableau de bord opérateur
• Observabilité
• Limitations
• Documentation
• Développement
• CI des merge requests

Posture de sécurité

L'audit est sûr par défaut :

• La première exécution après l'installation est verrouillée en mode simulation (dry-run), quels que soient les paramètres de l'opérateur. La levée du verrou nécessite un InitialAuditAcknowledgement explicite (admin ou shell uniquement).
• La politique par défaut est report pour chaque catégorie — les actions destructives sont opt-in.
• Les lignes de piste d'audit (AuditRun, AuditFinding, AuditInvocation, ConfigChangeLog) sont en ajout seul (append-only) au niveau du manager et de l'instance ; les update() / bulk_update() en masse sont bloqués.
• Les URL de webhook sont traitées comme des identifiants et masquées dans les logs, les messages d'exception et les argv persistés.

Fonctionnement

Chaque membre de la guilde est classé dans une catégorie :

Catégorie	Signification
unknown_guest	Membre Discord qu'AA ne connaît pas
linked_no_perm	Identité connue d'AA mais sans discord.access_discord
bot_filtered	Compte bot configuré — jamais traité

L'opérateur associe chaque catégorie à une action :

Action	Comportement
report	Enregistre le constat ; aucune modification côté Discord
strip	Retire les rôles gérés par AA
strip_kick	Retire les rôles gérés par AA, puis exclut de la guilde

L'association est définie par le paramètre AA_DISCORD_AUDIT_POLICY ; les surcharges par groupe et par état s'imbriquent dans chaque catégorie.

Prérequis

• Python 3.10–3.13
• Django 5.2
• Alliance Auth 5.x
• Le module de service Discord d'Alliance Auth (allianceauth.services.modules.discord) installé et configuré (token de bot + guilde)

Installation

pip install aa-discord-audit

Dans votre local.py d'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",
]

Puis exécutez les migrations :

python manage.py migrate aa_discord_audit

Le CurrentUserMiddleware est obligatoire — apps.ready() lève ImproperlyConfigured s'il est absent. C'est lui qui permet au gestionnaire de signal ConfigChangeLog d'attribuer les modifications d'administration à un utilisateur réel plutôt qu'à <system>.

Démarrage rapide

1. Accordez aa_discord_audit.run_audit au rôle opérateur qui exécute les audits.

2. Lancez un audit en mode simulation (dry-run) :

   python manage.py audit_discord_roles --action report
   

3. Consultez les résultats sous Discord Audit → Audit runs dans le tableau de bord Auth.

4. Libérez le verrou de première exécution — soit en créant une ligne InitialAuditAcknowledgement via l'admin, soit en exécutant python manage.py audit_acknowledge_initial. Les deux nécessitent aa_discord_audit.run_audit et aa_discord_audit.acknowledge_initial_audit.

5. Relancez avec l'action destructive de votre choix lorsque vous êtes prêt.

Permissions

Nom de code	Contrôle
aa_discord_audit.run_audit	commande de gestion, tâche beat, suppression d'exécution
aa_discord_audit.run_audit_destructive	contrôle de lancement web pour strip / strip_kick (distinct de run_audit)
aa_discord_audit.acknowledge_initial_audit	libère le verrou de simulation de première exécution
aa_discord_audit.manage_discord_identity	admin DiscordIdentity
aa_discord_audit.manage_role_exception	admin ManagedRoleException
aa_discord_audit.manage_protected_member	admin ProtectedDiscordMember
aa_discord_audit.manage_bot_account_uid	admin BotAccountUid
aa_discord_audit.manage_finding_override	admin FindingActionOverride
aa_discord_audit.view_auditrun (et associés)	piste d'audit en lecture seule dans le tableau de bord Auth

Les noms de code manage_* sont répartis selon le rayon d'impact afin qu'un junior disposant de manage_bot_account_uid ne puisse pas non plus désarmer l'audit en modifiant ManagedRoleException.

Paramètres

Tous les paramètres sont facultatifs. Les valeurs par défaut sont sûres.

# 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