aa-discord-audit

Audit di riconciliazione per l'integrazione Discord di Alliance Auth. Confronta le assegnazioni di ruolo effettive nella gilda Discord configurata con lo stato espresso in Alliance Auth (Gruppi + Stato per utente) e colma la lacuna attraverso cui i moderatori possono assegnare manualmente ruoli con nome AA a utenti che AA non conosce.

Stato: alpha (0.1.x). L'API pubblica e le impostazioni potrebbero ancora cambiare prima della 1.0.

Indice

• Postura di sicurezza
• Come funziona
• Requisiti
• Installazione
• Avvio rapido
• Permessi
• Impostazioni
• Comandi di gestione
• Audit periodico (Celery beat)
• Task Celery
• Dashboard operatore
• Osservabilità
• Limitazioni
• Documentazione
• Sviluppo
• CI delle merge request

Postura di sicurezza

L'audit è sicuro per impostazione predefinita:

• La prima esecuzione dopo l'installazione è bloccata in modalità dry-run indipendentemente dalle impostazioni dell'operatore. Il rilascio del blocco richiede un esplicito InitialAuditAcknowledgement (solo admin o shell).
• La policy predefinita è report per ogni categoria — le azioni distruttive sono opt-in.
• Le righe del registro di audit (AuditRun, AuditFinding, AuditInvocation, ConfigChangeLog) sono append-only a livello di manager e di istanza; le operazioni bulk update() / bulk_update() sono bloccate.
• Gli URL dei webhook sono trattati come credenziali e oscurati nei log, nei messaggi di eccezione e negli argv persistiti.

Come funziona

Ogni membro della gilda viene classificato in una categoria:

Categoria	Significato
unknown_guest	Membro Discord di cui AA non sa nulla
linked_no_perm	Identità nota ad AA ma priva di discord.access_discord
bot_filtered	Account bot configurato — mai oggetto di azioni

L'operatore associa ogni categoria a un'azione:

Azione	Comportamento
report	Registra il rilevamento; nessuna modifica lato Discord
strip	Rimuove i ruoli gestiti da AA
strip_kick	Rimuove i ruoli gestiti da AA, poi espelle dalla gilda

La mappatura è l'impostazione AA_DISCORD_AUDIT_POLICY; le sovrascritture per gruppo e per stato si annidano all'interno di ciascuna categoria.

Requisiti

• Python 3.10–3.13
• Django 5.2
• Alliance Auth 5.x
• Il modulo del servizio Discord di Alliance Auth (allianceauth.services.modules.discord) installato e configurato (token del bot + gilda)

Installazione

pip install aa-discord-audit

Nel tuo local.py di 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",
]

Poi esegui le migrazioni:

python manage.py migrate aa_discord_audit

Il CurrentUserMiddleware è obbligatorio — apps.ready() solleva ImproperlyConfigured se manca. È ciò che consente al gestore del segnale ConfigChangeLog di attribuire le modifiche dell'admin a un utente reale anziché a <system>.

Avvio rapido

1. Concedi aa_discord_audit.run_audit al ruolo operatore che esegue gli audit.

2. Esegui un audit in modalità dry-run:

   python manage.py audit_discord_roles --action report
   

3. Esamina i risultati in Discord Audit → Audit runs nella dashboard Auth.

4. Rilascia il blocco di prima esecuzione — crea una riga InitialAuditAcknowledgement tramite l'admin, oppure esegui python manage.py audit_acknowledge_initial. Entrambi richiedono aa_discord_audit.run_audit e aa_discord_audit.acknowledge_initial_audit.

5. Riesegui con l'azione distruttiva di tua scelta quando sei pronto.

Permessi

Codename	Controlla
aa_discord_audit.run_audit	comando di gestione, attività beat, eliminazione esecuzione
aa_discord_audit.run_audit_destructive	gate di avvio web per strip / strip_kick (separato da run_audit)
aa_discord_audit.acknowledge_initial_audit	rilascia il blocco dry-run di prima esecuzione
aa_discord_audit.manage_discord_identity	admin di DiscordIdentity
aa_discord_audit.manage_role_exception	admin di ManagedRoleException
aa_discord_audit.manage_protected_member	admin di ProtectedDiscordMember
aa_discord_audit.manage_bot_account_uid	admin di BotAccountUid
aa_discord_audit.manage_finding_override	admin di FindingActionOverride
aa_discord_audit.view_auditrun (e affini)	audit-trail in sola lettura nella dashboard Auth

I codename manage_* sono suddivisi per raggio d'impatto, così un utente junior con manage_bot_account_uid non può anche neutralizzare l'audit modificando ManagedRoleException.

Impostazioni

Tutte le impostazioni sono opzionali. I valori predefiniti sono sicuri.

# 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