Postura de seguridad

La auditoría es segura por defecto:

• La primera ejecución después de la instalación está bloqueada en modo de prueba (dry-run) independientemente de la configuración del operador. Liberar el bloqueo requiere un InitialAuditAcknowledgement (solo administrador o shell).
• La política predeterminada es report para cada categoría — las acciones destructivas son opt-in.
• Las filas del registro de auditoría (AuditRun, AuditFinding, AuditInvocation, ConfigChangeLog) son de solo añadido (append-only) a nivel de manager e instancia; las operaciones masivas update() / bulk_update() están bloqueadas.
• Las URL de webhook se tratan como credenciales y se redactan de los registros, mensajes de excepción y argv persistido.

Cómo funciona

Cada miembro del gremio se clasifica en una categoría:

El operador asigna cada categoría a una acción:

El mapeo es la configuración AA_DISCORD_AUDIT_POLICY; las anulaciones por grupo y por estado se anidan dentro de cada categoría.

Requisitos

• Python 3.10–3.13
• Django 4.2 o 5.2
• Alliance Auth 4.x o 5.x
• El módulo de servicio Discord de Alliance Auth (allianceauth.services.modules.discord) instalado y configurado (token del bot + gremio)

Instalación```sh

pip install aa-discord-audit

Luego ejecuta las migraciones:```sh python manage.py migrate aa_discord_audit

3. Revise los hallazgos en Discord Audit → Audit runs en el panel de Auth.
4. Libere el bloqueo de primera ejecución — cree una fila InitialAuditAcknowledgement a través del admin, o ejecute python manage.py audit_acknowledge_initial. Ambos requieren aa_discord_audit.run_audit y aa_discord_audit.acknowledge_initial_audit.
5. Vuelva a ejecutar con la acción destructiva de su elección cuando esté listo.

Permisos

Los nombres clave manage_* están divididos por radio de explosión, de modo que un junior con manage_bot_account_uid no pueda también desarmar la auditoría editando ManagedRoleException.

Configuración

Todas las configuraciones son opcionales. Los valores predeterminados son seguros.```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

Panel del operador

Montado bajo la navegación principal de Auth como Discord Audit. Vistas de solo lectura; cada lista tiene un cuadro de búsqueda del lado del servidor que coincide en todas las filas — no solo en la página visible — junto con sus filtros desplegables:

• Ejecuciones de auditoría — una tarjeta de resumen con la postura de auditoría en toda la flota sobre una lista etiquetada y ordenable; el detalle por ejecución se divide en tarjetas alrededor de la tabla por hallazgo.
• Explicación por hallazgo — clasificación, acción resuelta (con la política resuelta como JSON y un marcador de fecha), y qué capa de anulación (anulación por uid, política por grupo/por estado, ProtectedDiscordMember, bloqueo de primera ejecución) decidió el resultado.
• Invocaciones — cada disparador CLI/beat incluyendo intentos rechazados, con el estado de ejecución visible y el argv completo expandible. Muestra el uso del límite de tasa.
• Registro de cambios de configuración — cada edición del operador a las tablas de configuración gestionadas por el operador, representada como una diferencia antes/después a nivel de campo para actualizaciones (JSON con formato bonito para creación/eliminación) con un filtro de actor que no distingue mayúsculas/minúsculas. La pista de auditoría del auditor.

Iniciar una auditoría desde la interfaz web

Los operadores con el permiso aa_discord_audit.run_audit ven un botón Launch Audit en la página Audit runs. Al hacer clic se abre un modal de Bootstrap que muestra el modo de política configurado (solo informe o destructivo), el estado de reconocimiento inicial y un botón Confirm Launch. El envío de POST a /run-launch/, que crea un AuditRun PENDIENTE, encola process_pending_run a través de Celery y redirige a la página de detalle de la ejecución.

La ruta web refleja las puertas de seguridad de la CLI:

• Bloqueo de primera ejecución. Si no se ha ejecutado audit_acknowledge_initial, el modal muestra un bloque de rechazo (sin botón de envío) en lugar de la acción Confirm Launch. Un POST que evita el modal (por ejemplo, curl) es rechazado en el servidor, el rechazo se registra en AuditInvocation, y el operador es redirigido con un mensaje flash.
• Intención destructiva. Si un lanzamiento puede eliminar roles o expulsar miembros se decide en el servidor según los permisos del operador y la política: was_confirmation_bypassed = user.has_perm(run_audit_destructive) and policy_has_destructive(policy). La interfaz no tiene interruptor — el permiso destructivo solo determina la intención. Un operador solo con run_audit que activa un lanzamiento contra una política destructiva obtiene una ejecución silenciosa de solo INFORME (la misma coerción que aplica la CLI sin --yes).
• Límite de tasa por usuario. La misma cuota diaria que la CLI; el modal aún se abre pero el POST devuelve un flash + redirección una vez que se agota la cuota.

Mientras una ejecución está en un estado no terminal (PENDING, RUNNING o INTERRUPTED), la página de detalle de la ejecución consulta /runs/<pk>/state.json cada cinco segundos y actualiza la tarjeta de Estado en su lugar. La consulta se pausa en pestañas ocultas y se detiene tan pronto como la ejecución alcanza un estado terminal.

Observabilidad

Instrumentación opcional de Prometheus detrás del extra [metrics] — si está ausente, cada llamada de métrica se resuelve en un stub sin operación a un costo casi nulo. El módulo incluye una capa de cooperación sin dependencia: cuando django-prometheus está instalado, los contadores e histogramas de la auditoría se registran en el prometheus_client.REGISTRY predeterminado y la vista /metrics de django-prometheus los exporta junto con sus propias series.```sh pip install aa-discord-audit[metrics]

La cadena de herramientas es solo uv. La longitud de línea es 79 (Python) / 120 (Markdown).

Traducciones

• Русский

Licencia

MIT — consulte LICENSE.