aa-discord-audit

تدقيق تسوية لتكامل Discord في Alliance Auth. يقارن تعيينات الأدوار الفعلية في خادم Discord المُهيَّأ مع الحالة المعبَّر عنها في Alliance Auth (المجموعات + الحالة لكل مستخدم) ويسدّ الثغرة التي يمكن من خلالها للمشرفين تعيين أدوار تحمل اسم AA يدويًا لمستخدمين لا يعرفهم AA.

الحالة: ألفا (0.1.x). قد تتغير واجهة البرمجة العامة والإعدادات قبل الإصدار 1.0.

المحتويات

• وضع الأمان
• كيف يعمل
• المتطلبات
• التثبيت
• البدء السريع
• الأذونات
• الإعدادات
• أوامر الإدارة
• التدقيق الدوري (Celery beat)
• مهام Celery
• لوحة تحكم المشغّل
• المراقبة
• القيود
• التوثيق
• التطوير
• CI لطلبات الدمج

وضع الأمان

التدقيق آمن افتراضيًا:

• أول تشغيل بعد التثبيت مُقيَّد بوضع التشغيل التجريبي (dry-run) بغض النظر عن إعدادات المشغّل. يتطلب تحرير القفل إقرارًا صريحًا عبر InitialAuditAcknowledgement (للمشرف أو عبر shell فقط).
• السياسة الافتراضية هي report لكل فئة — الإجراءات التدميرية اختيارية.
• صفوف سجل التدقيق (AuditRun، AuditFinding، AuditInvocation، ConfigChangeLog) للإضافة فقط على مستوى المدير والنسخة؛ عمليات update() / bulk_update() الجماعية محظورة.
• تُعامَل عناوين URL الخاصة بـ Webhook كبيانات اعتماد وتُحجب من السجلات ورسائل الاستثناءات وargv المحفوظة.

كيف يعمل

يُصنَّف كل عضو في الخادم ضمن فئة واحدة:

الفئة	المعنى
unknown_guest	عضو Discord لا يعرف عنه AA شيئًا
linked_no_perm	الهوية معروفة لـ AA لكنها تفتقر إلى discord.access_discord
bot_filtered	حساب بوت مُهيَّأ — لا يُتخذ أي إجراء بحقه

يُسند المشغّل لكل فئة إجراءً واحدًا:

الإجراء	السلوك
report	تسجيل النتيجة؛ دون أي تغيير على جانب Discord
strip	إزالة الأدوار التي يديرها AA
strip_kick	إزالة الأدوار التي يديرها AA، ثم الطرد من الخادم

التعيين هو الإعداد AA_DISCORD_AUDIT_POLICY؛ التجاوزات لكل مجموعة ولكل حالة تتفرّع داخل كل فئة.

المتطلبات

• Python 3.10–3.13
• Django 5.2
• Alliance Auth 5.x
• وحدة خدمة Discord في Alliance Auth (allianceauth.services.modules.discord) مثبَّتة ومُهيَّأة (bot token + guild)

التثبيت

pip install aa-discord-audit

في ملف local.py الخاص بـ 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",
]

ثم شغّل عمليات الترحيل:

python manage.py migrate aa_discord_audit

CurrentUserMiddleware إلزامي — يرفع apps.ready() استثناء ImproperlyConfigured إذا كان مفقودًا. فهو ما يسمح لمعالج إشارة ConfigChangeLog بنسبة تعديلات المشرفين إلى مستخدم حقيقي بدلاً من <system>.

البدء السريع

1. امنح aa_discord_audit.run_audit لدور المشغّل الذي يشغّل عمليات التدقيق.

2. شغّل تدقيقًا تجريبيًا:

   python manage.py audit_discord_roles --action report
   

3. راجع النتائج ضمن Discord Audit → Audit runs في لوحة تحكم Auth.

4. حرّر قفل التشغيل الأول — إما بإنشاء صف InitialAuditAcknowledgement عبر لوحة الإدارة، أو بتشغيل python manage.py audit_acknowledge_initial. يتطلب كلاهما aa_discord_audit.run_audit و aa_discord_audit.acknowledge_initial_audit.

5. أعد التشغيل باستخدام الإجراء التدميري الذي تختاره عندما تكون مستعدًا.

الأذونات

الاسم الرمزي	يتحكم في
aa_discord_audit.run_audit	أمر الإدارة، مهمة beat، حذف التشغيل
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 (وما شابهها)	سجل تدقيق للقراءة فقط في لوحة تحكم Auth

أسماء manage_* الرمزية مقسّمة حسب نطاق التأثير بحيث لا يستطيع موظف مبتدئ يملك manage_bot_account_uid أن يعطّل التدقيق أيضًا عبر تعديل ManagedRoleException.

الإعدادات

جميع الإعدادات اختيارية. القيم الافتراضية آمنة.

# 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

# Idempotency-key TTL. When positive, prune_audit_runs releases
# AuditRun.idempotency_key on rows older than the cutoff while the
# row itself stays for RUN_RETENTION_DAYS. 0 (default) disables the
# expiry; the key dies with the row.
AA_DISCORD_AUDIT_IDEMPOTENCY_KEY_TTL_DAYS = 0

# Per-run deadline. The Celery task's soft_time_limit follows.
AA_DISCORD_AUDIT_RUN_DEADLINE_MINUTES = 60

# Rolling 24h rate limit on accepted audit triggers per user.
# DISABLED is an opt-out gate; refuses to take effect unless
# explicitly toggled.
AA_DISCORD_AUDIT_RUN_RATE_LIMIT_PER_DAY = 5
AA_DISCORD_AUDIT_RUN_RATE_LIMIT_DISABLED = False

# Discord webhook delivery tuning.
AA_DISCORD_AUDIT_WEBHOOK_TIMEOUT = 10
AA_DISCORD_AUDIT_WEBHOOK_MAX_RETRIES = 3