commands.md 11KB
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.
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
/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
/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 /help. Typing the command alone will show
a top-level list of commands available. You can optionally search for commands
or keywords by typing /help <keywords>. As you type, matching suggestions will
appear in an autocomplete list. You can search for commands, subcommands, modules,
or keywords.
Each section is known internally as a “cog,” though I try to refer to them as
“modules” externally to be a little less jargony. 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 top-level commands
(e.g. /hello) but most have subcommands. You can find out more using
/help <commandname>, e.g. /help config will show subcommands for
config.
And then you can invoke a subcommand with /commandname subcommandname. e.g.
/config setwarningchannel. To get more info about a subcommand, use /help
again. e.g. /help /config setwarningchannel.
Configuration
There are four top-level commands used for configuring most functionality.
/get <setting>- Shows the current value for a configuration setting./set <setting> <new_value>- Sets a new value./enable <module>- Enables a module./disable <module>- Disables a module.
You can also use
/get all- Shows all configuration settings and their current values.
Cogs
This section goes through each cog, what it does, and how to use it. While I
will try to keep this document up to date, the most authoritative info is via
the /help command since that info lives right there with the code.
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
/enableor/disable autokick- Toggle autokicking/getor/set autokick_bancount- If the same person keeps rejoining after being kicked, ban them after this many rejoins./getor/set autokick_offlineonly- 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
/config get_warning_channelorset_warning_channel- 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./config get_warning_mentionorset_warning_mention- 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.
Bang Commands
Bang commands are one-word chat commands starting with an exclamation (a “bang”)
similar to what Twitch bots use. When a user types the command by itself in a
message, the bot will respond with the configured text. E.g. a !rules command
can be defined that summarizes the guild rules, and typing !rules in chat
will get a reply with the list of rules.
Subcommands
/command define- Defines a command or redefines an existing one./command undefine- Deletes a previously created command./command list- Lists all defined commands./command invoke- Silently invokes a bang command without typing anything visible in chat
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
/enableor /disable crosspost- Master toggle for this entire feature./getor/set crosspost_warncount- How many duplicate messages will cause a warning message to be posted that alerts the mods./getor/set crosspost_bancount- How many duplicate messages should result in an automatic ban. Should be greater than the warning count./getor/set crosspost_timespan- 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./getor/set crosspost_minlength- 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
/delete_messages <@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 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
/enableor/disable joinraid- Toggle the feature./getor/set joinraid_joincount- Sets the minimum number of suspicious joins./getor/set joinraid_jointime- 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
/enableor/disable logging- 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
/pattern add ...- Adds a new pattern to look for (see Patterns)./pattern remove <name>- Removes a previously added pattern by name./pattern list- Show all configured patterns./pattern 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
/enableor/disable urlspam- Toggle the feature./getor/set urlspam_joinage- Sets the length of time after joining when posted links are considered suspicious, in seconds./getor/set urlspam_action- Action to take when a join age link is detected. One of these values:nothing- Ignoremodwarn- Post a warning message in the log channel and tag mods.delete- Delete the message.kick- Kick the user.ban- Ban the user.
/getor/set urlspam_deceptiveaction- Action to take when a deceptive link is detected. One of these values:nothing- Ignoremodwarn- 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
/enableor/disable username- Toggle the feature./username add <pattern>- Adds a substring to look for in usernames of newly joined members./username remove <pattern>- Removes a pattern./username list- Lists all tracked patterns.