> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mira.lgbt/llms.txt
> Use this file to discover all available pages before exploring further.

# Antinuke

> Detects and punishes destructive actions in your server, from mass deletions to webhook spam.

Antinuke protects your server from the things people do to destroy one: mass deletions,
permission grabs, unauthorised bots, and webhook spam.

Here's how it works. mira watches the **events** you turn on, counts how many actions each
member takes against a **threshold** you set, applies your chosen **punishment** to anyone who
goes over it, and DMs you a summary with buttons to undo the damage.

<Info>
  Nothing is enabled by default. Antinuke does nothing at all until you **turn an event on**.
</Info>

## Setup

Follow these in order. You set the punishment and your exemptions first, so no event is live
while it's still half configured.

<Steps>
  <Step title="Give mira Administrator, at the top of the role list">
    Discord won't let a bot take action against anyone whose highest role sits above its own.
    If mira is somewhere in the middle of your role list, anyone above it can tear the server
    apart without being stopped.

    <Warning>
      This part isn't optional. If mira's role is below an attacker's, the action is still
      detected, but the punishment **won't go through**.
    </Warning>
  </Step>

  <Step title="Open your DMs in a server you share with mira">
    Alerts come by DM, and so do the buttons you press to restore anything that gets deleted.
    Closed DMs don't stop protection from working, but you won't hear about anything and you
    won't be able to undo it.

    <Tip>
      Discord's DM setting works **per server**, so you don't have to open your DMs anywhere
      public. Turn it on in any small private server that mira is also in and the alerts still
      reach you.
    </Tip>
  </Step>

  <Step title="Decide what happens to offenders">
    ```text theme={null}
    antinuke punishment stripstaff
    ```

    Skip this and the first false positive is a ban, since that's the default. Stripstaff and
    jail both keep the person in the server with nothing they can abuse, which is safer while
    you're still working out the right limits.
  </Step>

  <Step title="Exempt the people and bots that do this for a living">
    ```text theme={null}
    antinuke whitelist @Moderator
    antinuke whitelist @Carl-bot
    ```

    Add anything that regularly creates channels, edits roles, or posts through webhooks.
    Whitelisting only stops someone being detected, it doesn't give them any permissions.

    Mods who ban and kick using mira count toward the same limits as everyone else, so add your
    busiest staff here too.
  </Step>

  <Step title="Turn on the events you want">
    ```text theme={null}
    antinuke channel on
    antinuke role on
    antinuke ban on
    antinuke kick on
    antinuke bot on
    antinuke permissions on
    ```

    Each one starts at `3` actions per `1h`. [Events](#events) has the full list and
    [Thresholds](#thresholds) covers changing those numbers.
  </Step>

  <Step title="Check your work">
    ```text theme={null}
    antinuke settings
    ```
  </Step>
</Steps>

## Events

You turn on each event separately, and every one takes a `<status>`. The
[accepted values](/reference/syntax/arguments#booleans) are on the Arguments page.

```text Syntax theme={null}
antinuke <event> <status> [flags]
```

| Event         | Triggers on                         | Flags                       |
| ------------- | ----------------------------------- | --------------------------- |
| `ban`         | Members being banned                | `--threshold`, `--duration` |
| `kick`        | Members being kicked                | `--threshold`, `--duration` |
| `channel`     | Channels created or deleted         | `--threshold`, `--duration` |
| `role`        | Roles created or deleted            | `--threshold`, `--duration` |
| `emoji`       | Emojis created or deleted           | `--threshold`, `--duration` |
| `webhook`     | Webhooks created or deleted         | `--threshold`, `--duration` |
| `bot`         | A bot being added                   | None                        |
| `permissions` | Dangerous permissions being granted | None                        |
| `webhookspam` | Mass mentions through a webhook     | `--mentions`, `--everyone`  |

<Info>
  It doesn't matter how someone does something. Discord's own menus, another bot, and mira's
  commands all count the same, so `ban`, `kick`, and `role` are treated exactly like doing it
  through Discord. **You can't get around antinuke by using mira.**
</Info>

<Warning>
  You need a `<status>` on **every** change, even when you're only adjusting a threshold.
  `antinuke channel --threshold 2` doesn't have one, and a missing status counts as off, so the
  event you were trying to tighten turns off instead.

  ```text Correct theme={null}
  antinuke channel on --threshold 2 --duration 30m
  ```
</Warning>

The six create and delete events all work the same way. These three are different:

<AccordionGroup>
  <Accordion title="bot: instant, and the member's whitelist won't save them" icon="bot">
    ```text Syntax theme={null}
    antinuke bot <status>
    ```

    Any bot that joins gets kicked, and whoever added it gets punished. There's no count to
    build up, one bot is enough.

    To let a bot in, you whitelist **the bot**. Whitelisting the person adding it does nothing.

    ```text Clear a bot before inviting it theme={null}
    antinuke whitelist @Carl-bot
    ```

    This is on purpose. Adding a malicious bot is the quickest way to destroy a server, and it
    almost always happens through a hacked staff account that's already whitelisted.
  </Accordion>

  <Accordion title="permissions: one grant is enough, and it undoes itself" icon="key">
    ```text Syntax theme={null}
    antinuke permissions <status>
    ```

    This catches anyone giving themselves more power, or handing it to someone else:

    * Giving themselves a role with a [dangerous permission](#dangerous-permissions)
    * Adding dangerous permissions to a role that already exists
    * Giving that role to someone else, including through `role <member> <role>`

    There's nothing to count here. The first time it happens, it triggers.

    It's also the only event that fixes itself. The role's permissions go back to exactly what
    they were within milliseconds, before anyone gets a chance to use them.
  </Accordion>

  <Accordion title="webhookspam: checked per message, and it clears every webhook" icon="megaphone">
    ```text Syntax theme={null}
    antinuke webhookspam <status> [flags]
    ```

    | Flag         | Description                                                              | Range        |
    | ------------ | ------------------------------------------------------------------------ | ------------ |
    | `--mentions` | User mentions in one message before it counts as spam.                   | `5` to `100` |
    | `--everyone` | `@everyone` or `@here` mentions in one message before it counts as spam. | `0` to `5`   |

    When a webhook message goes over either limit, three things happen:

    1. Up to **200** of that webhook's recent messages in the channel are deleted, not just the
       one that went over.
    2. **Every webhook in the server** is deleted.
    3. Whoever created the offending webhook is punished.

    <Warning>
      Deleting all of them is intentional. One webhook link can be pointed at any channel, so
      mira treats the whole set as **compromised**. Real webhooks from GitHub, status pages, and
      automation tools go with them and you'll need to set those up again.
    </Warning>

    Nothing is counted over time here. mira checks each message on its own and triggers on the
    exact number you set, so `--mentions 5` goes off at 5 mentions.

    If the person who created the webhook has already left the server, they're banned no matter
    what your punishment is set to. There's nobody left to strip or jail.
  </Accordion>
</AccordionGroup>

## Thresholds

Every event except `bot`, `permissions`, and `webhookspam` counts each member's actions.

| Flag          | Description                                       | Range          | Default |
| ------------- | ------------------------------------------------- | -------------- | ------- |
| `--threshold` | Actions allowed before the punishment fires.      | `1` to `12`    | `3`     |
| `--duration`  | How long the count survives without new activity. | `10s` to `12h` | `1h`    |

[Durations](/reference/syntax/durations) lists the time formats you can use.

It works like a counter with a timer attached:

* Each matching action adds `1` to the counter.
* Each action also resets the timer to its **full** length, not to whatever was left of it.
* The counter only clears once the timer runs all the way out with no activity, and it clears
  to zero all at once. Actions don't expire one by one.

<Warning>
  The punishment lands on the action **after** the number you set. A threshold of `3` lets
  someone do three things, and the fourth one triggers it.
</Warning>

Here's `--threshold 3 --duration 60s` in action:

| Time   | Action          | Count            | Timer now runs out at |
| ------ | --------------- | ---------------- | --------------------- |
| `0s`   | Channel deleted | 1                | `60s`                 |
| `40s`  | Channel deleted | 2                | `100s`                |
| `90s`  | Channel deleted | 3                | `150s`                |
| `120s` | Channel deleted | Punishment fires |                       |

That fourth deletion came two minutes after the first. With a fixed timer the earlier ones
would have been forgotten by then, but each deletion pushed the timer back and kept the count
going.

If nothing had happened until `160s`, the timer would have run out at `150s`, the count would
have cleared, and that deletion would have started again at 1.

<Tip>
  This is why going slowly doesn't help. Deleting a channel every 50 seconds keeps the count
  alive **indefinitely**, so a `60s` timer still catches you even though you never did three
  things inside one minute.
</Tip>

## Punishments

One punishment covers every event, webhook spam included. You can't set a different one per
event.

```text Syntax theme={null}
antinuke punishment <"ban"|"kick"|"stripstaff"|"jail">
```

<Tip>
  `<>` marks a **required** argument, `[]` marks an **optional** one. Don't type the
  brackets themselves. See [Arguments](/reference/syntax/arguments) for quoting, flags,
  and everything else.
</Tip>

| Punishment   | What happens                                                           |
| ------------ | ---------------------------------------------------------------------- |
| `ban`        | Banned from the server. **Default.**                                   |
| `kick`       | Removed, and able to come back with any invite.                        |
| `stripstaff` | Every role with a dangerous permission is taken off them.              |
| `jail`       | The same strip, then moved into a jail channel with nobody to talk to. |

<Info>
  `kick` is the weakest of the four. Anyone kicked can come straight back with a new invite, and
  **an autorole will hand their permissions back**.
</Info>

<AccordionGroup>
  <Accordion title="What stripstaff takes off" icon="user-minus">
    Every role the offender has that includes a
    [dangerous permission](#dangerous-permissions), plus any role you've given custom bot command
    permissions.

    Some roles can't be removed at all. Discord won't let a bot take an integration or bot role
    off its owner, so in that case mira strips the dangerous permissions from the **role itself**
    instead.

    If there's nothing that can be taken off them, stripstaff bans them instead, or kicks them if
    mira can't ban.

    <Warning>
      Stripstaff can't touch any role sitting **above mira's own**.
    </Warning>
  </Accordion>

  <Accordion title="How jail works" icon="lock">
    Jail does the strip above, then moves the person into a jail channel where they're cut off
    from everyone.

    It sets itself up the first time you use it, so there's nothing to configure beforehand. Let
    someone out with `unjail <member>`, which gives back the roles they lost.
  </Accordion>
</AccordionGroup>

### Dangerous permissions

These are the permissions the `permissions` event watches for and stripstaff removes:

* Administrator
* Ban Members
* Kick Members
* Manage Server
* Manage Roles
* Manage Channels
* Manage Webhooks
* Manage Expressions
* Manage Nicknames
* Mention Everyone

## Whitelist and trust

These two get mixed up a lot, but they do completely different things. Whitelisting stops
someone from being detected. Trust gives someone control over antinuke.

| Property               | Whitelist               | Trust                           |
| ---------------------- | ----------------------- | ------------------------------- |
| What it does           | Exempts from detection  | Grants full control of antinuke |
| Who can grant it       | Owner or trusted member | Server owner only               |
| Covers the `bot` event | No                      | Not applicable                  |
| Receives alerts        | No                      | No                              |

Both commands toggle. Run one to add someone, run it again to take them back off.

```text Syntax theme={null}
antinuke whitelist <member>
antinuke trust <member>
```

```text Managing the lists theme={null}
antinuke whitelist list
antinuke whitelist clear
antinuke trust list
antinuke trust clear
```

<Warning>
  Trust gives someone complete control of your protection, including **turning it off**. Only
  the owner can grant it. Keep it for people you'd trust with the server itself.
</Warning>

<Info>
  `clear` empties a whole list in one command. Clear your trust list and you'll be the **only
  person left** who can change anything.
</Info>

## Alerts and recovery

Alerts go to the server owner by DM and nowhere else. Trusted members don't get anything, so
they can only help if you show them the message.

### Undone automatically

Dangerous permission grants. The role goes back to exactly the permissions it had within
milliseconds, before anyone can use them. You don't have to do anything.

### Undone with a button

Roles and channels that get deleted or created are **not** restored on their own. mira saves a
copy and DMs you buttons to undo one thing, or everything at once.

| What happened   | What undoing it does                                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| Role deleted    | Recreates it with the same name, colour, permissions, and position, and puts the members back in it. |
| Channel deleted | Recreates it along with its permission overrides.                                                    |
| Role created    | Deletes it.                                                                                          |
| Channel created | Deletes it.                                                                                          |

<Info>
  Discord doesn't remember who had a role once it's been deleted, so mira **keeps its own
  record**. That's why restored roles come back with the members still in them.
</Info>

<Warning>
  Nothing comes back until someone presses a button. Only the owner or a trusted member can press
  them, and if your DMs are closed the message **never arrives at all**.
</Warning>

## Recommended setups

<Tabs>
  <Tab title="Small or private">
    A few staff, low risk, mistakes more likely than attacks. The defaults suit this well.

    ```text theme={null}
    ntinuke punishment stripstaff
    antinuke channel on
    antinuke role on
    antinuke ban on
    antinuke kick on
    antinuke bot on
    antinuke permissions on
    ```

    With stripstaff, a mod having a bad day loses their roles instead of their place in the
    server.
  </Tab>

  <Tab title="Large or public">
    Active staff, a real chance of being targeted, and integrations posting through webhooks.

    ```text theme={null}
    antinuke punishment jail
    antinuke channel on --threshold 2 --duration 30m
    antinuke role on --threshold 2 --duration 30m
    antinuke ban on --threshold 4 --duration 10m
    antinuke kick on --threshold 5 --duration 10m
    antinuke webhook on --threshold 3 --duration 30m
    antinuke webhookspam on --mentions 15 --everyone 1
    antinuke emoji on
    antinuke bot on
    antinuke permissions on
    ```

    Ban and kick get higher limits on short timers, because moderation really does come in
    bursts. Channels and roles get tight limits, because nothing normal deletes several of them
    in half an hour. Jail keeps the person in the server so you can look at what happened before
    you decide.
  </Tab>

  <Tab title="Under attack">
    Everything as sensitive as it goes, false positives accepted.

    ```text theme={null}
    antinuke punishment ban
    antinuke trust clear
    antinuke whitelist clear
    antinuke channel on --threshold 1
    antinuke role on --threshold 1
    antinuke ban on --threshold 1
    antinuke kick on --threshold 1
    antinuke webhook on --threshold 1
    antinuke bot on
    antinuke permissions on
    ```

    Clearing both lists removes every exemption and everyone who can change your settings except
    you. Add them back once things have calmed down.
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Someone wrecked the server and nothing happened">
    Most likely reasons first: the event was never turned on, the member is whitelisted, mira's
    role is below theirs, or they own the server. `antinuke settings` shows what's on and
    `antinuke whitelist list` shows who's exempt.
  </Accordion>

  <Accordion title="A moderator got punished for doing their job">
    They went over a threshold. Either whitelist them, or raise the threshold and shorten the
    duration on that event so normal bursts clear before they add up.

    ```text theme={null}
    antinuke ban on --threshold 6 --duration 5m
    ```
  </Accordion>

  <Accordion title="I got punished using mira's own commands">
    That's expected. `ban`, `kick`, and `role` all count toward thresholds however you run them.
    Whitelist the staff who use them regularly, or raise the threshold on that event.
  </Accordion>

  <Accordion title="I lowered a threshold and the event switched off">
    Every change needs a `<status>` with it. `antinuke channel --threshold 2` doesn't have one,
    so it reads as off. Include one every time: `antinuke channel on --threshold 2`.
  </Accordion>

  <Accordion title="Every webhook in the server disappeared">
    Webhook spam protection triggered. Clearing all of them is intentional, since one webhook
    link can be used in any channel. Set your integrations up again, then raise `--mentions` if
    the message that triggered it was legitimate.
  </Accordion>

  <Accordion title="A bot I invited was kicked immediately">
    The `bot` event removes anything that isn't whitelisted, no matter who invited it. Whitelist
    the bot first, then invite it again.

    ```text theme={null}
    antinuke whitelist @Carl-bot
    ```
  </Accordion>

  <Accordion title="Something was destroyed and I got no DM">
    Your DMs are closed in every server you share with mira. Open them in any one of those, a
    small private server included. Until then the alert and its buttons have nowhere to go.
  </Accordion>
</AccordionGroup>

## Limits

* **The server owner can't be punished.** Discord won't let a bot ban, kick, or remove roles from
  the owner, so a hacked owner account is out of reach.
* **Role position decides everything.** Nothing above mira's role can be stripped or punished.
* **Only the owner is told.** Trusted members get no alerts and can only act on buttons the owner
  passes to them.
* **Restores wait for a button.** Apart from permission grants, nothing comes back on its own, so
  an absent owner leaves a wrecked server wrecked.
* **One punishment for everything.** You can't ban for channel deletions and only strip roles for
  emoji deletions.
* **There's no reset command.** Events go off one at a time with `antinuke <event> off`.
* **`antinuke settings` shows numbers, not names.** Use `antinuke whitelist list` and
  `antinuke trust list` for that.
* **Counts are per member.** Two attackers working together each build up their own count.

## Command reference

| Command                                                     | Description                                             |
| ----------------------------------------------------------- | ------------------------------------------------------- |
| `antinuke settings`                                         | Shows the current configuration. Anyone can run this.   |
| `antinuke punishment <"ban"\|"kick"\|"stripstaff"\|"jail">` | Sets the punishment for every event.                    |
| `antinuke ban <status> [flags]`                             | Protection against mass bans.                           |
| `antinuke kick <status> [flags]`                            | Protection against mass kicks.                          |
| `antinuke channel <status> [flags]`                         | Protection against channel creation and deletion.       |
| `antinuke role <status> [flags]`                            | Protection against role creation and deletion.          |
| `antinuke emoji <status> [flags]`                           | Protection against emoji creation and deletion.         |
| `antinuke webhook <status> [flags]`                         | Protection against webhook creation and deletion.       |
| `antinuke webhookspam <status> [flags]`                     | Protection against mass mentions sent through webhooks. |
| `antinuke bot <status>`                                     | Kicks bots on join unless the bot is whitelisted.       |
| `antinuke permissions <status>`                             | Protection against dangerous permission grants.         |
| `antinuke whitelist <member>`                               | Toggles detection exemption for a member or bot.        |
| `antinuke whitelist list`                                   | Lists exempt members.                                   |
| `antinuke whitelist clear`                                  | Removes every exemption.                                |
| `antinuke trust <member>`                                   | Toggles antinuke access for a member. Owner only.       |
| `antinuke trust list`                                       | Lists trusted members.                                  |
| `antinuke trust clear`                                      | Removes every trusted member. Owner only.               |
| `unjail <member>`                                           | Releases a jailed member and restores their roles.      |