aa-discord-audit

تدقيق تسوية (Reconciliation audit) لتكامل Alliance Auth مع Discord. يقارن تعيينات الأدوار الفعلية في سيرفر (guild) Discord المُهيأ بحسب الحالة المعبر عنها في Alliance Auth (المجموعات + الحالة لكل مستخدم) ويُسد الفجوة التي يمكن من خلالها للمشرفين تعيين أدوار بأسماء مألوفة لـ AA لمستخدمين لا تعرفهم AA عنهم.

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

المحتويات

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

وضع الأمان

التدقيق آمن بشكل افتراضي:

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

كيفية العمل

يُصنف كل عضو في السيرفر إلى فئة واحدة:

يقوم المشغل بتعيين كل فئة إلى إجراء واحد:

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

المتطلبات

• Python 3.10–3.13
• Django 4.2 أو 5.2
• Alliance Auth 4.x أو 5.x
• وحدة خدمة Discord الخاصة بـ Alliance Auth (allianceauth.services.modules.discord) مثبتة ومُهيأة (رمز البوت + السيرفر)

التثبيت```sh

pip install aa-discord-audit

في Auth الخاص بك `local.py`:```python
# `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",
]

ثم قم بتشغيل migrations:```sh python manage.py migrate aa_discord_audit

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

## بداية سريعة

1. منح إذن `aa_discord_audit.run_audit` لدور المشغل الذي يقوم بتشغيل عمليات التدقيق.
2. قم بتشغيل تدقيق تجريبي (dry-run):   ```sh
   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. أعد التشغيل مع الإجراء التدميري الذي تختاره عندما تكون مستعدًا.

الأذونات

الأسماء الرمزية manage_* مقسمة حسب نصف قطر الانفجار بحيث لا يمكن لمبتدئ لديه manage_bot_account_uid تعطيل التدقيق عن طريق تحرير ManagedRoleException.

الإعدادات

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

Action policy. Bare-string form below is shorthand for

{"default": ""}; 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", # "linked_no_perm": { # "default": "strip", # "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

Opt-in: bulk PATCH role strip. Faster on large guilds; off by default

while we collect operator feedback on Discord-side rate-limit shape.

AA_DISCORD_AUDIT_USE_BULK_ROLE_STRIP = False

Periodic (Celery beat) audit. Destructive actions on the unattended

beat require this explicit opt-in, independent of the one-shot

first-run lock: a beat run carrying strip/kick is coerced to report

otherwise, with a startup warning on mismatch.

AA_DISCORD_AUDIT_BEAT_ALLOW_DESTRUCTIVE = False

Coarse global floor between beat runs, in minutes. 0 (default)

disables it — the Celery beat schedule is the primary cadence

control. A backstop against a misconfigured fast schedule

(QueueOnce only dedupes concurrent ticks, not back-to-back ones).

AA_DISCORD_AUDIT_BEAT_MIN_INTERVAL_MINUTES = 0

Pin the CLI acting user to a Django username (the "service principal"

pattern). The management command has no HTTP request, so the actor is

normally derived from the OS login; set this for clean, stable

ConfigChangeLog attribution from cron and manual CLI alike. Resolved

and permission-checked per invocation.

AA_DISCORD_AUDIT_CLI_ACTOR = None

Guild presence sampling. Requires the [metrics] extra and

aa-discord-audit's own /audit/discord/metrics scrape target.

PRESENCE_ENABLED is independent of [metrics]: even without

the extra, disabling it suppresses the background sampler task.

AA_DISCORD_AUDIT_PRESENCE_ENABLED = True

Desired presence sample cadence in minutes. Values below 5 fall

back to the default of 10.

AA_DISCORD_AUDIT_PRESENCE_SAMPLE_INTERVAL_MINUTES = 10

Gate for the members_by_group aggregate gauge. Disable if the

number of AA groups causes unacceptable cardinality.

AA_DISCORD_AUDIT_METRICS_MEMBERS_BY_GROUP = True

Gate for the members_by_role aggregate gauge. Off by default —

Discord guilds can have hundreds of roles; enable only after

reviewing role count to avoid a cardinality explosion.

AA_DISCORD_AUDIT_METRICS_MEMBERS_BY_ROLE = False

## أوامر الإدارة

| الأمر                  | الغرض                                                          |
|--------------------------|------------------------------------------------------------------|
| `audit_discord_roles`    | نقطة الدخول الرئيسية. `--action {report,strip,strip_kick}`.       |
| `audit_discord_roles --resume <run_id>`        | إعادة مراجعة نتائج PENDING لتشغيل موجود.       |
| `audit_discord_roles --abandon <run_id>`       | وضع تشغيل عالق كـ ABANDONED.                     |
| `audit_discord_roles --diff <run_id>`          | مقارنة الحالة الحالية بتشغيل سابق.         |
| `audit_discord_roles --explain <member_id>`    | تصنيف لكل عضو (للقراءة فقط).             |
| `audit_discord_roles --policy-preview <json>`  | عرض سياسة افتراضية.                     |
| `audit_discord_roles --from-fixture <path>`    | إعادة التشغيل مقابل لقطة JSON.                    |
| `audit_acknowledge_initial` | إلغاء قفل التشغيل الجاف الأول من وحدة التحكم.          |
| `audit_benchmark`        | قياس أداء تحميل اصطناعي (راجع [`docs/performance.md`](https://gitlab.com/eveo7/aa-discord-audit/-/blob/main/docs/performance.md)). |
| `prune_audit_runs`       | تقليم الاحتفاظ.                                               |
| `audit_abandon_stuck_runs` | تسوية تشغيلات PENDING العالقة التي تسربت من عامل معطل – تحويلها إلى ABANDONED (راجع دليل التشغيل؛ للتشغيل RUNNING العالق استخدم `audit_discord_roles --abandon`). |

يتفاعل `audit_discord_roles` عند التشغيل الطويل مع `SIGTERM` و`SIGINT` بشكل نظيف: يتم تحويل التشغيل إلى `INTERRUPTED` وتخرج حلقة التطبيق عند الحدود التالية للنتائج بحيث يكون العمل الجزئي ثابتًا في مسار التدقيق. `audit_discord_roles --resume <run_id>` يستأنف التشغيل من النتائج المتبقية `PENDING`.

## التدقيق الدوري (Celery beat)

`audit_orphan_members` يشغل نفس مسار البناء + التطبيق وفقًا لجدول زمني تقوم بتوصيله بـ Celery beat (ليس مجدولًا افتراضيًا). المسار غير المراقب مقيد للأمان:

- **تقرير فقط ما لم يتم تسليحه.** يتم إجبار تشغيل beat على `report` بغض النظر عن السياسة ما لم يتم تعيين `AA_DISCORD_AUDIT_BEAT_ALLOW_DESTRUCTIVE` — إلغاء قفل التشغيل الجاف الأول لتشغيل CLI يدوي لا يسّلح الـ beat. يتم إطلاق تحذير عند بدء التشغيل عندما تكون السياسة مدمرة ولكن الـ beat لم يوافق.
- **منسوب.** كل تشغيل beat يكتب `AuditInvocation` مقبول من فاعل النظام (`triggered_by=BEAT`)، بحيث يغطي مسار تدقيق المدقق التشغيل غير المراقب أيضًا.
- **الشفاء الذاتي.** يتم تسوية تشغيل عالق بسبب ضربة حد زمني ناعم أو تعطل عامل إلى الحالة القابلة للاستئناف `INTERRUPTED` في الدورة التالية. `AA_DISCORD_AUDIT_BEAT_MIN_INTERVAL_MINUTES` هو حد أدنى تقريبي ضد جدول سريع تم تكوينه بشكل خاطئ.

## مهام Celery

يسجل الحزمة خمس مهام تحت بادئة الاسم `aa_discord_audit.*`. فقط مهام beat تحتاج إلى جدول زمني؛ الباقي يعمل بأحداث أو عند الطلب. لا شيء مجدول لك.

| المهمة | كيفية تشغيلها | ما تقوم به |
|------|-------------|--------------|
| `aa_discord_audit.audit_orphan_members` | Celery beat — تقوم بجدولتها | تدقيق البناء + التطبيق غير المراقب الموصوف أعلاه. تقرير فقط ما لم يتم تسليحه؛ يشارك قفل `discord.user_actions.<uid>` مع `update_groups` من AA. |
| `aa_discord_audit.retry_pending_kicks` | Celery beat — تقوم بجدولتها | مسح محدود يعيد إرسال الطرد المؤجل بسبب فشل Discord مؤقت، مع احترام فترة تهدئة لكل صف حتى لا يتعرض العضو الفاشل بشدة. |
| `aa_discord_audit.process_pending_run` | مدفوع بالأحداث — يتم وضعه في قائمة الانتظار بواسطة إطلاق ويب | يلتقط تشغيل `PENDING` الذي أنشأه إطلاق ويب، يحوله إلى `RUNNING`، ويدفع المسار مقابل علم التأكيد المجمد للتشغيل. |
| `aa_discord_audit.prune_audit_runs` | Celery beat / cron — تقوم بجدولتها (أيضًا أمر إدارة) | الاحتفاظ: انتهاء صلاحية مفتاح عدم التكرار ثم حذف الصف (راجع **أوامر الإدارة** ودليل التشغيل). |
| `aa_discord_audit.sample_guild_presence` | Celery beat — تقوم بجدولتها | عينة خفيفة، REST فقط، من أعضاء السيرفر / المتصلين / عدد المعززين في لقطة وجود أحدث فقط لمقاييس وجود Prometheus. مقيدة بـ `AA_DISCORD_AUDIT_PRESENCE_ENABLED`; حارس تخطي يحد من جدول سريع تم تكوينه بشكل خاطئ (حد أدنى `AA_DISCORD_AUDIT_PRESENCE_SAMPLE_INTERVAL_MINUTES`، افتراضي 10). خامل حتى يتم تقديم كل من إضافة `[metrics]` وإدخال beat (راجع [`docs/METRICS.md`](https://gitlab.com/eveo7/aa-discord-audit/-/blob/main/docs/METRICS.md)). |

لجدولة مهام beat، أضفها إلى `CELERYBEAT_SCHEDULE` في ملف `local.py` الخاص بك، على سبيل المثال:```python
CELERYBEAT_SCHEDULE["aa_discord_audit_sample_guild_presence"] = {
    "task": "aa_discord_audit.sample_guild_presence",
    "schedule": 600,  # seconds; honoured no finer than the sampler floor
}

لوحة تحكم المشغل

مثبتة تحت التنقل الرئيسي للمصادقة باسم Discord Audit. وجهات عرض للقراءة فقط؛ كل قائمة تحمل مربع بحث من جانب الخادم يطابق عبر كل صف - وليس فقط الصفحة المعروضة - إلى جانب فلاتر القائمة المنسدلة الخاصة بها:

• عمليات التدقيق - بطاقة ملخص مع وضع التدقيق عبر الأسطول فوق قائمة قابلة للفرز مع شارات؛ يتم تقسيم تفاصيل كل تشغيل إلى بطاقات حول جدول كل نتيجة.
• شرح كل نتيجة - التصنيف، الإجراء المُحلّ (مع السياسة المُحلّة بصيغة JSON وعلامة زمنية (as-of))، وأي طبقة تجاوز (تجاوز لكل معرف مستخدم، سياسة لكل مجموعة/حالة، ProtectedDiscordMember، قفل التشغيل الأول) حددت النتيجة.
• الاستدعاءات - كل مشغل CLI / beat بما في ذلك المحاولات المرفوضة، مع إظهار حالة التشغيل وإمكانية توسيع argv بالكامل. يُظهر استخدام حد المعدل.
• سجل تغيير التكوين - كل تعديل من المشغل على جداول التكوين التي يديرها المشغل، معروض كفرق قبل/بعد على مستوى الحقل للتحديثات (JSON مطبوع بشكل جميل للإنشاء/الحذف) مع مرشح فاعل غير حساس لحالة الأحرف. مسار تدقيق المدقق.

إطلاق عملية تدقيق من واجهة الويب

يرى المشغلون الذين لديهم إذن aa_discord_audit.run_audit زر إطلاق التدقيق في صفحة عمليات التدقيق. يؤدي النقر عليه إلى فتح نافذة منبثقة Bootstrap تعرض وضع السياسة المُكوّن (تقرير فقط أو تدميري)، وحالة الإقرار الأولي، وزر تأكيد الإطلاق. إرسال POSTs إلى /run-launch/، والذي ينشئ AuditRun بحالة PENDING، ويُدرج process_pending_run عبر Celery، ويعيد التوجيه إلى صفحة تفاصيل التشغيل.

يتبع مسار الويب نفس بوابات الأمان لواجهة CLI:

• قفل التشغيل الأول. إذا لم يتم تشغيل audit_acknowledge_initial، تعرض النافذة المنبثقة كتلة رفض (بدون زر إرسال) بدلاً من إجراء تأكيد الإطلاق. يتم رفض POST الذي يتجاوز النافذة المنبثقة (مثل curl) من جانب الخادم، ويتم تسجيل الرفض في AuditInvocation، ويتم إعادة توجيه المشغل مع رسالة وميض.
• النية التدميرية. ما إذا كان بإمكان الإطلاق إزالة الأدوار أو طرد الأعضاء يتم تحديده من جانب الخادم بناءً على أذونات المشغل والسياسة: was_confirmation_bypassed = user.has_perm(run_audit_destructive) and policy_has_destructive(policy). لا تحتوي واجهة المستخدم على مفتاح تبديل — إذن التدمير وحده يحدد النية. المشغل الذي لديه إذن run_audit فقط ويطلق عملية تدقيق ضد سياسة تدميرية يحصل على تشغيل بصيغة REPORT-only صامت (نفس الإكراه الذي تطبقه CLI بدون --yes).
• حد المعدل لكل مستخدم. نفس الحصة اليومية لواجهة CLI؛ تظل النافذة المنبثقة مفتوحة ولكن POST يعيد وميضًا + إعادة توجيه بمجرد استنفاذ الحصة.

أثناء وجود تشغيل في حالة غير نهائية (PENDING أو RUNNING أو INTERRUPTED)، تصوّت صفحة تفاصيل التشغيل على /runs/<pk>/state.json كل خمس ثوانٍ وتقوم بتحديث بطاقة الحالة في مكانها. يتوقف التصويت في علامات التبويب المخفية ويتوقف بمجرد وصول التشغيل إلى حالة نهائية.

قابلية المراقبة

أجهزة Prometheus الاختيارية خلف الامتداد [metrics] — في حال عدم وجودها، يتحول كل استدعاء مقياس إلى كعب لا يعمل بتكلفة شبه معدومة. تأتي الوحدة مع طبقة تعاون لا تعتمد: عند تثبيت django-prometheus، يتم تسجيل عدادات ورسوم بيانية للتدقيق في prometheus_client.REGISTRY الافتراضي، وتقوم طريقة عرض /metrics الخاصة بـ django-prometheus بتصديرها جنبًا إلى جنب مع سلاسلها الخاصة.```sh pip install aa-discord-audit[metrics]

مقاييس اللقطة — وجود الخادم (guild) وتجميعات العضوية لكل مجموعة/دور — تأخذ مسارًا ثانيًا: فهي موجودة في سجل مخصص يتم تصديره بواسطة نقطة النهاية `/audit/discord/metrics` الخاصة بالوحدة. جامع العمليات المتعددة لـ django-prometheus يقرأ فقط ملفات mmap ويتجاوز المجمعات المخصصة، لذا تحتاج هذه المقاييس إلى هدف سحب (scrape) خاص بها. مثل أي هدف `/metrics`، فهو غير موثّق — قيّده عند الوكيل العكسي أو طبقة الشبكة. يظل كلا السطحين خاملين بدون إضافة `[metrics]`.

دليل المقاييس، ومفردات التصنيفات، ووصفات Grafana موجودة في [`docs/METRICS.md`](https://gitlab.com/eveo7/aa-discord-audit/-/blob/main/docs/METRICS.md) (الترجمة الروسية: [`docs/METRICS.ru.md`](https://gitlab.com/eveo7/aa-discord-audit/-/blob/main/docs/METRICS.ru.md)).

## القيود

- **خادم واحد.** التدقيق يوفق بين خادم Discord الواحد الذي تم تكوين AA لاستخدامه؛ لا يمتد عبر خوادم متعددة.
- **أدوار مدارة من AA فقط.** إزالة/طرد تعمل على الأدوار المسماة من قبل AA وعضوية الخادم؛ الأدوار التي لا يديرها AA لا يتم لمسها أبدًا.
- **لا اكتشاف تلقائي للكُنًى.** يتم التعرف على حسابات البوت فقط عبر جدول `BotAccountUid` الصريح / `AA_DISCORD_AUDIT_BOT_UIDS` — `AA_DISCORD_AUDIT_AUTO_DISCOVER_BY_NICKNAME` محجوز للإصدار v2 وغير مطبق.
- **سطح ألفا.** قد تتغير أسماء الإعدادات وواجهة برمجة التطبيقات العامة قبل `1.0`.

## التوثيق

- [`docs/runbook.md`](https://gitlab.com/eveo7/aa-discord-audit/-/blob/main/docs/runbook.md) — دليل المشغل: أذونات بوت Discord، قائمة الفحص قبل التشغيل، تحرير قفل التشغيل الأول، دفاتر تشغيل الحوادث، مفاتيح التشخيص.
- [`docs/performance.md`](https://gitlab.com/eveo7/aa-discord-audit/-/blob/main/docs/performance.md) — أرقام مرجعية `audit_benchmark` وتأثيرات الحجم.
- [`docs/METRICS.md`](https://gitlab.com/eveo7/aa-discord-audit/-/blob/main/docs/METRICS.md) / [`docs/METRICS.ru.md`](https://gitlab.com/eveo7/aa-discord-audit/-/blob/main/docs/METRICS.ru.md) — دليل مقاييس Prometheus، مفردات التصنيفات، وصفات Grafana.
- الكود المصدري: <https://gitlab.com/eveo7/aa-discord-audit>
- متتبع المشكلات: <https://gitlab.com/eveo7/aa-discord-audit/-/issues>
- سجل التغييرات: [`CHANGELOG.md`](https://gitlab.com/eveo7/aa-discord-audit/-/blob/main/CHANGELOG.md)

## التطوير```sh
make dev         # uv sync --all-groups + pre-commit install
make tests       # uv run nox -s tests
make lint        # uv run nox -s lint
make typecheck   # mypy + basedpyright
make coverage    # term + html + xml report
make package     # uv build

سلسلة الأدوات هي uv-only. طول السطر هو 79 (Python) / 120 (Markdown).

الترجمات

• Русский

الترخيص

MIT — انظر LICENSE.