aa-discord-audit

Abgleichsprüfung für die Discord-Integration von Alliance Auth. Vergleicht die tatsächlichen Rollenzuweisungen in der konfigurierten Discord-Guild mit dem in Alliance Auth ausgedrückten Zustand (Gruppen + Status pro Benutzer) und schließt die Lücke, über die Moderatoren AA-benannte Rollen manuell an Benutzer vergeben können, die AA nicht kennt.

Status: Alpha (0.1.x). Die öffentliche API und die Einstellungen können sich vor 1.0 noch ändern.

Inhalt

Sicherheitshaltung
Funktionsweise
Voraussetzungen
Installation
Schnellstart
Berechtigungen
Einstellungen
Verwaltungsbefehle
Periodische Prüfung (Celery beat)
Celery-Tasks
Operator-Dashboard
Observability
Einschränkungen
Dokumentation
Entwicklung
Merge-Request-CI

Sicherheitshaltung

Die Prüfung ist standardmäßig sicher:

Der erste Lauf nach der Installation ist unabhängig von den Operator-Einstellungen auf Dry-Run festgelegt. Das Aufheben der Sperre erfordert eine ausdrückliche InitialAuditAcknowledgement (nur Admin oder Shell).
Die Standardrichtlinie ist report für jede Kategorie — destruktive Aktionen sind Opt-in.
Audit-Trail-Zeilen (AuditRun, AuditFinding, AuditInvocation, ConfigChangeLog) sind auf Manager- und Instanzebene nur anhängbar; Massen-update() / bulk_update() sind blockiert.
Webhook-URLs werden als Anmeldedaten behandelt und aus Logs, Ausnahmemeldungen und persistierten argv-Daten redigiert.

Funktionsweise

Jedes Guild-Mitglied wird in eine Kategorie eingestuft:

Kategorie	Bedeutung
`unknown_guest`	Discord-Mitglied, über das AA nichts weiß
`linked_no_perm`	Identität ist AA bekannt, aber es fehlt `discord.access_discord`
`bot_filtered`	Konfiguriertes Bot-Konto — wird nie bearbeitet

Der Operator ordnet jeder Kategorie eine Aktion zu:

Aktion	Verhalten
`report`	Befund aufzeichnen; keine Änderung auf Discord-Seite
`strip`	AA-verwaltete Rollen entfernen
`strip_kick`	AA-verwaltete Rollen entfernen, dann aus der Guild kicken

Die Zuordnung erfolgt über die Einstellung AA_DISCORD_AUDIT_POLICY; Überschreibungen pro Gruppe und pro Status sind innerhalb jeder Kategorie verschachtelt.

Voraussetzungen

Python 3.10–3.13
Django 5.2
Alliance Auth 5.x
Das Discord-Service-Modul von Alliance Auth (allianceauth.services.modules.discord) ist installiert und konfiguriert (Bot-Token + Guild)

Installation

pip install aa-discord-audit

In Ihrer 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",
]

Dann führe die Migrationen aus:

python manage.py migrate aa_discord_audit

Die CurrentUserMiddleware ist obligatorisch — apps.ready() löst ImproperlyConfigured aus, wenn sie fehlt. Sie ist es, die es dem ConfigChangeLog-Signal-Handler ermöglicht, Admin-Änderungen einem echten Benutzer statt <system> zuzuordnen.

Schnellstart

Gewähre aa_discord_audit.run_audit der Operator-Rolle, die Audits ausführt.

Führe ein Dry-Run-Audit aus:

python manage.py audit_discord_roles --action report

Überprüfe die Ergebnisse unter Discord Audit → Audit runs im Auth-Dashboard.
Gib die Sperre für den ersten Lauf frei — entweder durch Erstellen einer InitialAuditAcknowledgement-Zeile über das Admin, oder durch Ausführen von python manage.py audit_acknowledge_initial. Beides erfordert aa_discord_audit.run_audit und aa_discord_audit.acknowledge_initial_audit.
Führe den Lauf bei Bedarf mit der destruktiven Aktion deiner Wahl erneut aus.

Berechtigungen

Codename	Steuert
`aa_discord_audit.run_audit`	Management-Command, Beat-Task, Löschen von Läufen
`aa_discord_audit.run_audit_destructive`	Web-Start-Sperre für `strip` / `strip_kick` (getrennt von `run_audit`)
`aa_discord_audit.acknowledge_initial_audit`	Freigabe der Dry-Run-Sperre für den ersten Lauf
`aa_discord_audit.manage_discord_identity`	`DiscordIdentity`-Admin
`aa_discord_audit.manage_role_exception`	`ManagedRoleException`-Admin
`aa_discord_audit.manage_protected_member`	`ProtectedDiscordMember`-Admin
`aa_discord_audit.manage_bot_account_uid`	`BotAccountUid`-Admin
`aa_discord_audit.manage_finding_override`	`FindingActionOverride`-Admin
`aa_discord_audit.view_auditrun` (und verwandte)	schreibgeschützter Audit-Trail im Auth-Dashboard

Die manage_*-Codenames sind nach Schadensradius aufgeteilt, damit ein Junior mit manage_bot_account_uid das Audit nicht ebenfalls entschärfen kann, indem er ManagedRoleException bearbeitet.

Einstellungen

Alle Einstellungen sind optional. Die Standardwerte sind sicher.

# 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

AA Discord Audit

Beliebteste