Postura de segurança

A auditoria é segura por defeito:

• A primeira execução após a instalação está bloqueada em modo de simulação (dry-run), independentemente das configurações do operador. Para libertar o bloqueio é necessário um InitialAuditAcknowledgement explícito (apenas administrador ou shell).
• A política predefinida é report para todas as categorias — ações destrutivas são opt-in.
• As linhas do registo de auditoria (AuditRun, AuditFinding, AuditInvocation, ConfigChangeLog) são apenas de adição (append-only) ao nível do gestor e das instâncias; atualizações em massa update() / bulk_update() estão bloqueadas.
• Os URLs de Webhook são tratados como credenciais e ocultados dos registos, mensagens de exceção e argv persistido.

Como funciona

Cada membro do servidor é classificado numa das seguintes categorias:

O operador mapeia cada categoria para uma ação:

O mapeamento é a configuração AA_DISCORD_AUDIT_POLICY; sobreposições por grupo e por estado aninham-se dentro de cada categoria.

Requisitos

• Python 3.10–3.13
• Django 4.2 ou 5.2
• Alliance Auth 4.x ou 5.x
• Módulo de serviço Discord do Alliance Auth (allianceauth.services.modules.discord) instalado e configurado (token do bot + servidor)

Instalação```sh

pip install aa-discord-audit

Em seguida, execute as migrações:```sh python manage.py migrate aa_discord_audit

3. Revise as descobertas em Discord Audit → Audit runs no painel Auth.
4. Libere o bloqueio da primeira execução — crie uma linha InitialAuditAcknowledgement através do admin, ou execute python manage.py audit_acknowledge_initial. Ambos requerem aa_discord_audit.run_audit e aa_discord_audit.acknowledge_initial_audit.
5. Reexecute com a ação destrutiva de sua escolha quando estiver pronto.

Permissões

Os codinomes manage_* são divididos por raio de explosão para que um júnior com manage_bot_account_uid não possa também desarmar a auditoria editando ManagedRoleException.

Configurações

Todas as configurações são opcionais. Os padrões são 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

Painel do operador

Montado na navegação principal do Auth como Discord Audit. Visualizações somente leitura; cada lista possui uma caixa de pesquisa no servidor que corresponde a cada linha — não apenas a página em exibição — juntamente com seus filtros suspensos:

• Execuções de auditoria — um cartão de resumo com a postura de auditoria em toda a frota acima de uma lista classificável com badges; os detalhes por execução dividem-se em cartões ao redor da tabela por descoberta.
• Explicação por descoberta — classificação, ação resolvida (com a política resolvida como JSON e um marcador de data), e qual camada de sobreposição (sobreposição por uid, política por grupo / por estado, ProtectedDiscordMember, bloqueio de primeira execução) decidiu o resultado.
• Invocações — cada acionador CLI / beat incluindo tentativas recusadas, com o estado da execução exibido e o argv completo expansível. Exibe o uso de limite de taxa.
• Log de alterações de configuração — cada edição do operador nas tabelas de configuração gerenciadas pelo operador, renderizada como um diff antes/depois no nível do campo para atualizações (JSON formatado para criação/exclusão) com um filtro de ator insensível a maiúsculas/minúsculas. A trilha de auditoria do auditor.

Iniciando uma auditoria a partir da interface web

Operadores com a permissão aa_discord_audit.run_audit veem um botão Iniciar Auditoria na página Execuções de auditoria. Clicar nele abre um modal Bootstrap que exibe o modo de política configurado (somente relatório ou destrutivo), o estado de reconhecimento inicial e um botão Confirmar Início. Enviar POSTs para /run-launch/, que cria um AuditRun PENDENTE, enfileira process_pending_run via Celery e redireciona para a página de detalhes da execução.

O caminho web espelha as barreiras de segurança da CLI:

• Bloqueio de primeira execução. Se audit_acknowledge_initial não foi executado, o modal exibe um bloco de recusa (sem botão de envio) em vez da ação Confirmar Início. Um POST que ignora o modal (ex.: curl) é recusado no servidor, a recusa é registrada em AuditInvocation, e o operador é redirecionado com uma mensagem flash.
• Intenção destrutiva. Se uma inicialização pode remover cargos ou expulsar membros é decidido no servidor a partir das permissões do operador e da política: was_confirmation_bypassed = user.has_perm(run_audit_destructive) and policy_has_destructive(policy). A interface não tem alternância — apenas a permissão destrutiva determina a intenção. Um operador apenas com run_audit que aciona uma inicialização contra uma política destrutiva recebe uma execução silenciosa SOMENTE RELATÓRIO (a mesma coerção que a CLI aplica sem --yes).
• Limite de taxa por usuário. A mesma cota diária da CLI; o modal ainda abre, mas o POST retorna um flash + redirecionamento assim que a cota é gasta.

Enquanto uma execução está em um estado não terminal (PENDING, RUNNING ou INTERRUPTED), a página de detalhes da execução consulta /runs/<pk>/state.json a cada cinco segundos e atualiza o cartão State no local. A consulta pausa em guias ocultas e para assim que a execução atinge um estado terminal.

Observabilidade

Instrumentação opcional do Prometheus por trás do extra [metrics] — ausente, toda chamada de métrica resolve para um stub sem operação com custo próximo de zero. O módulo fornece uma camada de cooperar-não-depender: quando o django-prometheus está instalado, os contadores e histogramas da auditoria registram-se no prometheus_client.REGISTRY padrão e a visualização /metrics do django-prometheus os exporta junto com suas próprias séries.```sh pip install aa-discord-audit[metrics]

Toolchain é apenas uv. Comprimento da linha é 79 (Python) / 120 (Markdown).

Traduções

• Russo

Licença

MIT — veja LICENSE.