python-app-rocketbot/docs/commands.md

Commands

Rocketbot’s functionality is broken into different functional areas that typically have a master switch to enable/disable it and some other configuration. Configuration is specific to each server the bot is invited to.

For all the examples here, I’m assuming the default command prefix of $rb_. If you set a different one in config.py, translate accordingly.

Log channel

The first thing you’ll want to do is configure a channel where bot messages can go. This should be a channel only mods can see. Go into that channel and type

$rb_config setwarningchannel

This ensures warnings will go somewhere appropriate.

You will probably also want to set a role to tag for important warnings to get their attention. E.g. to tag the @Mod role type

$rb_config setwarningmention @Mod

Entering that will configure who to mention, and it will also mention them right now in that message you just typed. Apologize to all the mods who you just bothered and explain you were just configuring a cool new bot.

Help!!

I don’t remember the commands for my own bot, so I don’t expect you will either. The only thing you need to remember is $rb_help. The bot will reply with a summary of all the top-level commands available. As an example:

Auto Kick:
  autokick       Automatically kicks all new users as soon as they join
Configuration:
  config         Manages general bot configuration
Crosspost Detection:
  crosspost      Manages crosspost detection and handling
General:
  deletemessages Mass deletes messages
  hello          Simple test reply
  shutdown       Shuts down the bot
  testwarn       Posts a test warning
Join Age:
  joinage        Tracks recently joined users with options to mass kick or ban
Join Raids:
  joinraid       Manages join raid detection and handling
Logging:
  logging        Manages event logging
Pattern Matching:
  pattern        Manages message pattern matching
URL Spam:
  urlspam        Manages URL spam detection
Username Pattern:
  username       Manages username pattern detection
No Category:
  help           Shows this message

Type $rb_help command for more info on a command.
You can also type $rb_help category for more info on a category.

Each section is known internally as a “cog”. If you’re mucking around in the code, each cog is its own source file in the rocketbot/cogs directory. But you can just think of them as categories. Some of these are commands of their own (e.g. hello, invoked with $rb_hello) but most have subcommands. You can find out more using $rb_help commandname, e.g. $rb_help config will show subcommands for config.

$rb_config

General guild configuration command group

Commands:
  getwarningchannel Shows the mod warning channel
  getwarningmention Shows the user/role to mention in warning messages
  setwarningchannel Sets the mod warning channel
  setwarningmention Sets a user/role to mention in warning messages

Type $rb_help command for more info on a command.
You can also type $rb_help category for more info on a category.

And then you can invoke a subcommand with $rb_commandname subcommandname. e.g. $rb_config setwarningchannel. To get more info about a subcommand, use $rb_help again. e.g. $rb_help config setwarningchannel.

Cogs

This section goes through each cog, what it does, and how to use it.

Autokick

Autokick is a feature of last resort, a sort of lockdown mode that immediately kicks all new users who join. (Users who joined before enabling this are fine.) We have on one occasion had some kind of bot that was doing tons and tons of joins, and there was no other way to stop them. Obviously something you want to supervise and disable as soon as the threat has passed.

Subcommands

• enable/disable - Toggle autokicking
• getbancount/setbancount - If the same person keeps rejoining after being kicked, ban them after this many rejoins.
• getofflineonly/setofflineonly - Whether to only kick users who join with a status of offline. That’s not impossible in ordinary use, but it’s suspect and likely indicative of bots versus real users.

Config

General config that isn’t specific to one cog.

Subcommands

• getwarningchannel/setwarningchannel - Determines the channel where log messages are posted. Setting the warning channel doesn’t take an argument; it uses the current channel you typed the command in.
• getwarningmention/setwarningmention - The user or role you want tagged when the bot needs to alert someone of suspicious activity. Needs to be a proper autocompleted @ mention, not just the name.

Crosspost detection

Detects an extremely common pattern we see of someone joining and copy/pasting the exact same message in as many channels as possible. This cog will look at recent messages from a user and see which ones contain the exact same text in multiple channels, and if it exceeds the configured number within the configured time span, it’s ban hammer time.

Subcommands

• enable/disable - Master toggle for this entire feature.
• getwarncount/setwarncount - How many duplicate messages will cause a warning message to be posted that alerts the mods.
• getbancount/setbancount - How many duplicate messages should result in an automatic ban. Should be greater than the warning count.
• gettimespan/settimespan - Sets the time window within which to look for duplicates. Value is in seconds. Spammers usually fire these off very quickly, so a minute or less is more than enough.
• getminlength/setminlength - For text-only messages, sets the minimum length to be considered for duplicate detection. Maybe a benign (but annoying) user posts “lol” at everything in multiple channels. Use this to filter for that case.

General

These are just general top-level commands, not subcommands.

Commands

• deletemessages <@user> <timespan> - Manually deletes a bunch of messages by a particular user. Useful if you banned but accidentally forgot to delete recent history, or to clean up after someone had a bit of a manic posting spree. The timespan is a value like “30s” for 30 seconds, “5m” for 5 minutes, or “1h30m” for an hour and a half. NOTE: This only works for fairly recent messages. You can’t use it to delete things posted way back in the scrollback.
• hello - Just for testing bot responsiveness. Or a desperate need to be seen.
• shutdown - Terminates the bot. I forgot this was here. I’ve never needed it. If somehow the bot goes rogue and you’re not there to ctrl+C it, use this.
• testwarn - Posts a test mod warning in the configured warning channel with the configured mention user/role.

Join age

This cog isn’t really needed any more since the Members tab was added to Discord. It’s used for seeing who joined most recently. The list of recent joins is only kept in memory, and it keeps a limited number, so it’s really only useful for the past few days.

Subcommands

• enable/disable - Toggle join tracking.
• getjointime/setjointime - How long to track a join, in seconds.
• search <timespan> - Shows all users who joined in the last x length of time. Values are like 30s for 30 seconds, 5m for 5 minutes, 1h30m for an hour and a half, etc.

Join raids

While not as common in the past year or two, we used to get a suspicious number of users all joining in very close succession with no obvious cause, followed by users being spammed in DMs by them. This cog attempts to alert us to such spikes in joins.

Subcommands

• enable/disable - Toggle the feature.
• getjoincount/setjoincount - Sets the minimum number of suspicious joins.
• getjointime/setjointime - Sets the span of time that number of joins must occur to be suspicious, in seconds.

Logging

We found it valuable to log certain events, namely message edits and deletions, due to some users frequently saying something questionable and then covering their tracks. We used to use another bot to do that until it silently just decided to stop being maintained. Thanks. So this cog attempts to reproduce that, logging as many meaningful events as possible.

Subcommands

• enable/disable - You get the full firehose or you get nothing.

Patterns

This is the most flexible cog. It can match arbitrary messages with complex criteria and take a number of automatic actions on them. The full syntax is kind of complex and is detailed in its own document.

Subcommands

• add ... - Adds a new pattern to look for (see Patterns).
• remove <name> - Removes a previously added pattern by name.
• list - Show all configured patterns.
• setpriority <name> <priority> - Alters the priority of a pattern. The priority is a unitless value used to pick which pattern wins if a message matches more than one. Patterns without priorities set have a default value of 100. The highest value wins.

URL spam

This cog detects two kinds of suspicious link post behaviors.

The first is posting a link suspiciously soon after joining. Honestly, this has had a pretty low hit rate. Join age seems unreliable. Supposedly, Discord imposes a 10m cooldown after joining a server before you can post, but I’ve seen people post within the first minute. And they are usually benign, like a reaction GIF or relevant Twitch clip. While the actual spammers don’t seem to get flagged, as they seem to use accounts that have been lying in wait a long time. YMMV.

The second is deceptive links. Discord added the ability in 2024 or 25 to change the text of a link instead of it always just showing the URL using the markdown syntax [link text](https://urlhere) which shows up as “link text” in blue. While Discord does warn users whenever they click a link where the text isn’t exactly the same as the URL, this happens in benign circumstances often enough that users may ignore it. Discord prevents posting mismatching URLs like [https://goodsite.com](https://badsite.com), however it doesn’t prevent posting things that are URL-like, like [goodsite.com](https://badsite.com) (without the https://). Our deceptive link detection catches these URL-like link labels.

Subcommands

• enable/disable - Toggle the feature.
• getjoinage/setjoinage - Sets the length of time after joining when posted links are considered suspicious, in seconds.
• getaction/setaction - Action to take when a join age link is detected. One of these values:
  • nothing - Ignore
  • modwarn - Post a warning message in the log channel and tag mods.
  • delete - Delete the message.
  • kick - Kick the user.
  • ban - Ban the user.
• getdeceptiveaction/setdeceptiveaction - Action to take when a deceptive link is detected. One of these values:
  • nothing - Ignore
  • modwarn - Post a warning message in the log channel and tag mods.
  • modwarndelete - Post a mod warning message and delete the message.
  • chatwarn - Reply to the message in the same channel calling out the suspicious link.
  • chatwarndelete - Reply to the message and delete it.
  • delete - Delete the message.
  • kick - Kick the user.
  • ban - Ban the user.

Username patterns

Notifies us when users with certain usernames join a server. Problem users will often get banned and just create another similarly named account, so this helps us catch ban evasion. When a matching username joins the server, a mod warning message will be posted in the log channel. The pattern is just a simple substring matched case-insensitively.

Subcommands

• enable/disable - Toggle the feature.
• add <pattern> - Adds a substring to look for in usernames of newly joined members.
• remove <pattern> - Removes a pattern.
• list - Lists all tracked patterns.