Skip to content

How a Discord anti-nuke bot should decide who to punish

Lessons from auditing Krypton's anti-nuke: matching audit-log entries to the right target, a single trust order, punishing once, and reverting every untrusted change.

5 min read

An anti-nuke bot watches a Discord server for destructive actions, such as mass channel deletions, role changes or bans, and stops whoever is doing them. Most write-ups describe thresholds and punishments. When I audited the anti-nuke in Krypton, the bugs that mattered had nothing to do with either. They were about deciding who did what. Punishing the wrong moderator is worse than doing nothing, because it teaches server owners to switch protection off.

The hard part is attribution

Discord's gateway tells you that a channel was deleted. It does not tell you who deleted it. For that you read the audit log, which is a separate API call, arrives a moment later, and contains entries for everything that happened recently. The bot has to pick the entry that belongs to this event. Get that wrong and every later step, whitelists included, operates on the wrong person.

Six ways to blame the wrong person

The audit turned up these, each of which punished someone who had done nothing wrong:

  1. Settings cached per guild, not per module. The first module checked in a cache window decided the whitelist for every module.
  2. Whitelist changes took up to a minute to apply, because nothing invalidated the cache. A user whitelisted moments before acting was punished.
  3. No member cache. Audit-log actors arrived as bare users without roles, so role whitelists only worked by accident.
  4. Entries not matched to the target. The newest entry of that type was used, at any age, so a boost could punish whoever last edited the server weeks earlier.
  5. The bot's own entries skipped. When the bot gave a role through a command, the previous entry for that member was blamed instead, and the bot then fought its own reverts.
  6. Ownership transfers counted as server updates, so the previous owner was punished for handing the server over.

Matching entries to targets

The rewrite treats attribution as its own step with strict rules:

  • An entry must be for this event's target. A role entry must contain the dangerous role that was added; a webhook entry must be for that channel.
  • Entries older than 60 seconds are never used.
  • Each entry is claimed once per module, so it can never be acted on twice.
  • If the entry is not there yet, the read retries twice, after 0.7 and 1.5 seconds, to wait out audit-log lag.
  • Events that arrive together share one audit-log read. Thirty deletions cost one or two reads in the tests, instead of thirty.
  • No matching entry means no action. Guessing is how innocent people get banned.

Cheap checks run before any of this. Position-only changes, boosts and emoji availability changes never touch the audit log at all.

One trust order

Every module now goes through one function that decides whether an actor is trusted, in a fixed order: this bot, the server owner, a backup owner, extra owners, users whitelisted for that module, then whitelisted roles. If roles need checking and the member is not cached, the bot fetches them. If that fails, the actor is unverifiable and nothing is done.

Settings for every module load in one query and are cached per guild for five minutes, and every write from the settings commands invalidates the cache immediately. A generation counter stops a slow load that raced a write from caching stale data.

Punish once, revert everything

During a real nuke, dozens of events arrive within a second. The rules that keep that sane:

  • Punishment happens once per actor. Concurrent events share it, and later events within ten seconds reuse its result.
  • The cooldown is recorded only after success or a permanent failure, so a transient failure is retried by the next event instead of giving the attacker a free pass.
  • Removing roles strips every role with dangerous permissions, not just Administrator.
  • A ban works even after the attacker has left.
  • Every untrusted change is reverted, whether or not that event was the one that punished. Punishment and reversal run in parallel, each with a timeout.
  • Reverts go back to the state before the first bad change, restore only fields the channel type supports, and rebuild a deleted category's channels inside its restored copy.

Failing safe

A security bot has to keep working when its dependencies do not. If the database is down, the last known settings keep protecting the guild for up to an hour. With no cached copy, the bot does nothing rather than guess. Every query has a five-second timeout, and the single guild-wide lock that used to serialise every event, held across API calls with no timeouts, is gone.

Testing it

The test suite runs the real event handlers against a fake guild and audit log, with real PostgreSQL and discord.py's real audit-entry parsing. It covers every module against every kind of actor, the attribution rules above, thirty simultaneous deletions (one punishment, thirty restores, at most two audit reads), two attackers at once, replayed events, and the failure cases: database down, slow database, missing permissions, an attacker above the bot.

If you run a server, the practical takeaway is to choose protection that explains its decisions. Every enforcement in Krypton now logs the actor, target, whitelist decision and reason, punishment result, revert result and the audit entry it used. That line is what lets an owner trust the bot. More on the project in the Krypton case study, and the recovery side in backup owner codes.

Illustrated avatar of Kumar Manas

Written by Kumar Manas

Full-stack developer in India. I build Melodius and Krypton.

Related projectKrypton: discord security bot