aa-discord-audit

Alliance Auth के Discord एकीकरण के लिए सुलह ऑडिट (reconciliation audit)। यह कॉन्फ़िगर किए गए Discord guild में वास्तविक रोल असाइनमेंट की तुलना Alliance Auth (प्रति उपयोगकर्ता Groups + State) में व्यक्त स्थिति से करता है और उस अंतराल को बंद करता है जिसके माध्यम से मॉडरेटर AA-नामित रोल उन उपयोगकर्ताओं को मैन्युअल रूप से असाइन कर सकते हैं जिनके बारे में AA को जानकारी नहीं है।

स्थिति: alpha (0.1.x)। सार्वजनिक API और सेटिंग्स 1.0 से पहले अभी भी बदल सकते हैं।

विषय-सूची

• सुरक्षा दृष्टिकोण
• यह कैसे काम करता है
• आवश्यकताएँ
• इंस्टॉलेशन
• त्वरित शुरुआत
• अनुमतियाँ
• सेटिंग्स
• प्रबंधन कमांड
• आवधिक ऑडिट (Celery beat)
• Celery कार्य
• ऑपरेटर डैशबोर्ड
• अवलोकनीयता
• सीमाएँ
• दस्तावेज़ीकरण
• विकास
• मर्ज अनुरोध CI

सुरक्षा दृष्टिकोण

ऑडिट डिफ़ॉल्ट रूप से सुरक्षित है:

• इंस्टॉल के बाद पहला रन ऑपरेटर सेटिंग्स की परवाह किए बिना dry-run पर लॉक रहता है। लॉक जारी करने के लिए एक स्पष्ट InitialAuditAcknowledgement (केवल admin या shell) आवश्यक है।
• डिफ़ॉल्ट नीति प्रत्येक श्रेणी के लिए report है — विनाशकारी क्रियाएँ ऑप्ट-इन हैं।
• ऑडिट-ट्रेल पंक्तियाँ (AuditRun, AuditFinding, AuditInvocation, ConfigChangeLog) manager और instance परतों पर केवल-जोड़ने योग्य (append-only) हैं; बल्क update() / bulk_update() अवरुद्ध हैं।
• Webhook URL को क्रेडेंशियल माना जाता है और लॉग, अपवाद संदेशों और सहेजे गए argv से छिपाया (redact) जाता है।

यह कैसे काम करता है

प्रत्येक guild सदस्य को एक श्रेणी में वर्गीकृत किया जाता है:

श्रेणी	अर्थ
unknown_guest	Discord सदस्य जिसके बारे में AA को कुछ भी ज्ञात नहीं है
linked_no_perm	पहचान AA को ज्ञात है लेकिन discord.access_discord का अभाव है
bot_filtered	कॉन्फ़िगर किया गया बॉट खाता — इस पर कभी कार्रवाई नहीं की जाती

ऑपरेटर प्रत्येक श्रेणी को एक क्रिया से मैप करता है:

क्रिया	व्यवहार
report	निष्कर्ष दर्ज करें; Discord-पक्ष पर कोई परिवर्तन नहीं
strip	AA-प्रबंधित रोल हटाएँ
strip_kick	AA-प्रबंधित रोल हटाएँ, फिर guild से किक करें

मैपिंग AA_DISCORD_AUDIT_POLICY सेटिंग है; प्रति-समूह और प्रति-स्थिति ओवरराइड प्रत्येक श्रेणी के अंदर नेस्ट होते हैं।

आवश्यकताएँ

• Python 3.10–3.13
• Django 5.2
• Alliance Auth 5.x
• Alliance Auth का Discord सेवा मॉड्यूल (allianceauth.services.modules.discord) इंस्टॉल और कॉन्फ़िगर किया गया (बॉट टोकन + guild)

इंस्टॉलेशन

pip install aa-discord-audit

अपने 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",
]

फिर माइग्रेशन चलाएँ:

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. Auth डैशबोर्ड में Discord Audit → Audit runs के अंतर्गत निष्कर्षों की समीक्षा करें।

4. प्रथम-रन लॉक जारी करें — या तो admin के माध्यम से एक InitialAuditAcknowledgement पंक्ति बनाएँ, या python manage.py audit_acknowledge_initial चलाएँ। दोनों के लिए aa_discord_audit.run_audit और aa_discord_audit.acknowledge_initial_audit आवश्यक हैं।

5. तैयार होने पर अपनी पसंद की destructive कार्रवाई के साथ पुनः चलाएँ।

अनुमतियाँ

कोडनेम	नियंत्रित करता है
aa_discord_audit.run_audit	management command, beat task, run delete
aa_discord_audit.run_audit_destructive	strip / strip_kick के लिए web-launch गेट (run_audit से अलग)
aa_discord_audit.acknowledge_initial_audit	प्रथम-रन dry-run लॉक जारी करता है
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 (और संबंधित)	Auth डैशबोर्ड में read-only audit-trail

manage_* कोडनेम प्रभाव-क्षेत्र के अनुसार विभाजित हैं ताकि manage_bot_account_uid वाला एक जूनियर ManagedRoleException को संपादित करके audit को भी कमज़ोर न कर सके।

सेटिंग्स

सभी सेटिंग्स वैकल्पिक हैं। डिफ़ॉल्ट सुरक्षित हैं।

# 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