aa-discord-audit

Сверочный аудит интеграции Alliance Auth с Discord. Сравнивает фактические назначения ролей в настроенной гильдии Discord с тем состоянием, которое отражено в Alliance Auth (группы и состояние каждого пользователя), и закрывает лазейку, через которую модераторы могут вручную выдавать роли с именами AA пользователям, о которых AA ничего не знает.

Статус: alpha (0.1.x). Публичный API и настройки могут ещё измениться до 1.0.

Безопасность по умолчанию

Аудит безопасен по умолчанию:

Самый первый прогон после установки принудительно идёт в режиме «только отчёт», независимо от настроек оператора. Снятие блокировки требует отдельной записи InitialAuditAcknowledgement и доступа в админку или к shell.
По умолчанию в каждой категории стоит действие report; разрушительные действия включаются явно.
Записи журнала (AuditRun, AuditFinding, AuditInvocation, ConfigChangeLog) защищены от обновлений на уровне менеджера и экземпляра модели — массовые update() и bulk_update() заблокированы.
Адрес вебхука считается секретом и затирается в журналах, в сообщениях об ошибках и в сохранённой строке аргументов команды.

Как это работает

Каждый участник гильдии относится к одной из трёх категорий:

Категория	Значение
`unknown_guest`	Участник, о котором AA ничего не знает
`linked_no_perm`	Личность известна AA, но нет права `discord.access_discord`
`bot_filtered`	Учтённый бот — с ним аудит не делает ничего

Оператор для каждой категории выбирает действие:

Действие	Поведение
`report`	Только зафиксировать находку, без изменений в Discord
`strip`	Снять роли с именами AA
`strip_kick`	Снять роли с именами AA, затем удалить из гильдии

Соответствие задаётся настройкой AA_DISCORD_AUDIT_POLICY. Для каждой категории можно указать переопределения по группе и по состоянию пользователя AA.

Требования

Python 3.10–3.13
Django 5.2
Alliance Auth 5.x
Discord-сервис-модуль Alliance Auth (allianceauth.services.modules.discord) установлен и настроен (токен бота + гильдия)

Установка

pip install aa-discord-audit

В local.py Alliance Auth:

# `aa_discord_audit` обязан идти ПОСЛЕ
# `allianceauth.services.modules.discord`, чтобы модели discord-модуля
# загрузились первыми; иначе `apps.ready()` поднимет
# `ImproperlyConfigured`.
INSTALLED_APPS += ["aa_discord_audit"]

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

Затем миграции:

python manage.py migrate aa_discord_audit

CurrentUserMiddleware обязателен — apps.ready() поднимает ImproperlyConfigured, если его нет в MIDDLEWARE. Без него обработчик сигналов ConfigChangeLog не может определить автора правки в админке, и каждое изменение пишется на безличного <system>.

Быстрый старт

Выдайте право aa_discord_audit.run_audit тому, кто будет запускать аудит.
Запустите аудит в режиме отчёта:
```
python manage.py audit_discord_roles --action report
```
Посмотрите находки в разделе Discord Audit → Прогоны аудита на панели Alliance Auth.
Снимите блокировку первого прогона — либо создайте в админке запись InitialAuditAcknowledgement, либо выполните python manage.py audit_acknowledge_initial. И то и другое требует aa_discord_audit.run_audit и aa_discord_audit.acknowledge_initial_audit.
Когда готовы — перезапустите с нужным разрушительным действием.

Права

Право	На что влияет
`aa_discord_audit.run_audit`	команда, периодическая задача, удаление запусков
`aa_discord_audit.run_audit_destructive`	запуск `strip` / `strip_kick` из веб-интерфейса (отдельно от `run_audit`)
`aa_discord_audit.acknowledge_initial_audit`	снятие блокировки первого запуска
`aa_discord_audit.manage_discord_identity`	работа с `DiscordIdentity` в админке
`aa_discord_audit.manage_role_exception`	работа с `ManagedRoleException` в админке
`aa_discord_audit.manage_protected_member`	работа с `ProtectedDiscordMember` в админке
`aa_discord_audit.manage_bot_account_uid`	работа с `BotAccountUid` в админке
`aa_discord_audit.manage_finding_override`	работа с `FindingActionOverride` в админке
`aa_discord_audit.view_auditrun` и аналогичные	просмотр журнала на панели Alliance Auth

Группа прав manage_* намеренно разнесена по таблицам — сотрудник, которому выдан только manage_bot_account_uid, не сможет одновременно подменить ManagedRoleException и обезвредить аудит.

Настройки

Все настройки необязательные; значения по умолчанию подобраны безопасно.

# Политика действий. Краткая форма ниже эквивалентна
# {"default": "<действие>"}; для переопределений по группе и по
# состоянию AA-пользователя используется развёрнутая форма.
AA_DISCORD_AUDIT_POLICY = {
    "unknown_guest":  "report",
    "linked_no_perm": "report",
    # "linked_no_perm": {
    #     "default":  "strip",
    #     "by_state": {"Guest": "report"},
    #     "by_group": {"Directors": "report"},
    # },
}

# Рассылка уведомлений через AA-notify обладателям прав.
AA_DISCORD_AUDIT_NOTIFY_ADMINS = True

# Адрес вебхука Discord для итогов запуска. Считайте его секретом.
AA_DISCORD_AUDIT_WEBHOOK_URL = None

# Список идентификаторов учётных записей ботов, которые надо
# пропускать (в дополнение к таблице BotAccountUid в админке).
AA_DISCORD_AUDIT_BOT_UIDS = []

# Автоматическое распознавание ботов по эвристикам Discord-имени.
# Зарезервировано для v2, в MVP не реализовано. Стартовый валидатор
# выбрасывает ImproperlyConfigured при значении True — оставляйте
# False и ведите явную таблицу BotAccountUid в админке.
AA_DISCORD_AUDIT_AUTO_DISCOVER_BY_NICKNAME = False

# Срок хранения записей о прогонах. 0 отключает очистку, но
# валидатор откажется принять 0, пока не выставлен флаг согласия
# ниже.
AA_DISCORD_AUDIT_RUN_RETENTION_DAYS = 180
AA_DISCORD_AUDIT_RETENTION_OPT_OUT_ACKNOWLEDGED = False

AA Discord Audit

Популярное