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

# Honeypot

> A bait channel that catches compromised accounts the moment they start spreading scams.

The honeypot does two things, and the second one is the reason to set it up even if you never get raided.

<CardGroup cols={2}>
  <Card title="The bait channel" icon="crosshairs">
    A channel nobody should ever post in. Anything posted there is treated as proof the account is compromised, and it's punished instantly.
  </Card>

  <Card title="Server-wide image scanning" icon="fingerprint" href="#image-scanning">
    Fingerprints every scam image it catches, then blocks that image **everywhere** — even when the scammers change the text around it.
  </Card>
</CardGroup>

The bait works because the accounts you're trying to catch aren't reading. A hijacked account running a scam script blasts its payload into every channel it can see — including this one, usually before it reaches the channels your members actually use.

Requires **Administrator**.

## Setting it up

```javascript theme={null}
!honeypot setup
!honeypot scan on
```

That's genuinely it. The first command creates the channel, locks it down, writes a warning topic and starts watching. The second turns on [image scanning](#image-scanning), which is where most of the ongoing value is.

### Setup flags

| Flag           | Aliases             | Default   | Effect                                       |
| -------------- | ------------------- | --------- | -------------------------------------------- |
| `--punishment` | `action`            | `softban` | `ban`, `softban`, `jail` or `timeout`        |
| `--dm`         | `send_dm`, `notify` | `true`    | DM the user explaining what happened         |
| `--boosters`   | `boosts`            | `false`   | Whether boosters get punished too            |
| `--warmer`     | `active`, `alive`   | `true`    | Post occasionally so the channel looks alive |
| `--random`     | `names`             | `false`   | Use a randomised channel name and topic      |
| `--string`     | `random_string`     | `false`   | Use a random string as the channel name      |

```javascript theme={null}
!honeypot setup --punishment ban --dm true --boosters false
```

<Tip>
  `softban` is the default for a reason. It bans and immediately unbans, which wipes the account's recent messages across the whole server but lets the real owner rejoin once they've recovered their account. `ban` is the right call if you'd rather they contact you first.
</Tip>

### Why `--warmer` matters

An empty channel with no history looks suspicious to the scam and gets skipped by some scripts. With the warmer on, mira posts occasionally to keep it looking like a real, quiet channel. Leave it on unless you have a reason not to.

## Punishment

```javascript theme={null}
!honeypot punishment ban
```

| Value     | Effect                                                         |
| --------- | -------------------------------------------------------------- |
| `ban`     | Banned permanently                                             |
| `softban` | Banned and unbanned — deletes their messages, lets them return |
| `jail`    | Given the jail role, loses channel access                      |
| `timeout` | Timed out                                                      |

Aliases: `punishments`, `action`, `actions`, `punish`, `do`.

## Cleaning up their other messages

```javascript theme={null}
!honeypot history 1h
```

When someone trips the honeypot, their messages from the last *N* of history are deleted across the whole server. This is what actually stops the scam — the bait message is irrelevant, the twelve copies they've already posted in your real channels are the problem.

`1h` is a sensible default. Aliases: `prune`, `purge`.

## Image scanning

```javascript theme={null}
!honeypot scan on
```

Aliases: `images`, `scanimages`, `sc`, `imgs`.

This is the part worth turning on regardless of whether you're being raided. Every image the honeypot catches is fingerprinted with **perceptual hashing**, and from then on that image is blocked in **every channel in your server** — not just the bait channel.

### Why perceptual hashing matters

A normal file hash changes if a single pixel changes, which makes it useless against scammers. Perceptual hashing fingerprints what the image *looks like*, so the same graphic still matches after it's been:

* Re-saved, re-compressed, or screenshotted
* Resized or cropped slightly
* Recoloured or watermarked
* Wrapped in different text, a different link, or a different filename

Scam campaigns reuse the same handful of graphics for weeks and rotate everything around them. Catching the graphic once means catching every later variation of it automatically.

### The workflow

<Steps>
  <Step title="Someone posts a scam image in the honeypot">
    They're punished, their recent messages are purged, and the image is fingerprinted.
  </Step>

  <Step title="The same image is now blocked server-wide">
    Anyone posting it in any channel gets caught, including accounts that never touched the bait channel.
  </Step>

  <Step title="Add anything that slips through by hand">
    ```javascript theme={null}
    !honeypot blacklist add
    ```

    Reply to the offending message. Every image attached to it is fingerprinted and blocked from then on.
  </Step>
</Steps>

<Tip>
  `!honeypot blacklist add` works on **any** message, not just honeypot ones. When a scam graphic gets posted in `#general`, replying to it with that command is the fastest way to make sure it never appears again — and it takes effect immediately for every channel.
</Tip>

### Managing the blocklist

<CodeGroup>
  ```javascript Blacklist a message's images theme={null}
  !honeypot blacklist add
  ```

  ```javascript View blocked hashes theme={null}
  !honeypot blacklist list
  ```

  ```javascript Remove a hash theme={null}
  !honeypot blacklist remove d4a1f0c39b2e6785
  ```

  ```javascript Clear everything theme={null}
  !honeypot blacklist clear
  ```
</CodeGroup>

`honeypot blacklist add` works on a reply or a message link, and hashes every image attached to it. Use it when a scam graphic gets through — that exact image will never post again.

Requires **Manage Server** for add/list/remove; **Administrator** to clear.

## Other settings

<CodeGroup>
  ```javascript Notify the user theme={null}
  !honeypot dm on
  ```

  ```javascript Spare boosters theme={null}
  !honeypot boosters off
  ```

  ```javascript Customise the warning theme={null}
  !honeypot message {title: Don't post here} {description: This channel is bait. Posting in it gets you removed.} {color: #ef767a}
  ```

  ```javascript Tear it down theme={null}
  !honeypot disable
  ```
</CodeGroup>

`honeypot message` accepts a full [script](/scripting/overview), so the channel topic message can be an embed or a container.

`honeypot disable` deletes the channel and stops all monitoring.

## Reviewing the configuration

```javascript theme={null}
!honeypot settings
```

Shows the channel, punishment, DM setting, booster setting, history window, scan state and blocklist size.

## Command reference

| Command                            | Permission    | Description                    |
| ---------------------------------- | ------------- | ------------------------------ |
| `honeypot setup [flags]`           | Administrator | Create the channel and start   |
| `honeypot punishment <action>`     | Administrator | ban / softban / jail / timeout |
| `honeypot history [duration]`      | Administrator | How much history to purge      |
| `honeypot scan (on/off)`           | Administrator | Scan attachments server-wide   |
| `honeypot dm (on/off)`             | Administrator | DM punished users              |
| `honeypot boosters (on/off)`       | Administrator | Punish boosters too            |
| `honeypot message <script>`        | Administrator | Customise the warning message  |
| `honeypot blacklist add [message]` | Manage Server | Blacklist a message's images   |
| `honeypot blacklist list`          | Manage Server | View blocked hashes            |
| `honeypot blacklist remove <hash>` | Manage Server | Unblock a hash                 |
| `honeypot blacklist clear`         | Administrator | Clear the blocklist            |
| `honeypot settings`                | Administrator | Configuration overview         |
| `honeypot disable`                 | Administrator | Delete the channel and stop    |

Group aliases: `honey`, `pot`, `hp`.

<Warning>
  Tell your staff the channel exists. The most common honeypot incident is a moderator posting "what's this channel for" in it and immediately softbanning themselves.
</Warning>