Automod System

Relevant source files

The following files were used as context for generating this wiki page:

• src/handlers/automod.ts
• src/commands/admin/automod/automod.ts
• src/commands/admin/automod/autodelete.ts
• src/database/schemas/AutomodLogs.ts
• src/data/respAutomod.json
• src/commands/admin/settings/status.ts

The Automod system is a core defensive feature of Amina, designed to automatically moderate server content based on a configurable set of rules. It proactively scans messages for violations such as spam, excessive mentions, links, and attachments. When a violation is detected, the system can delete the offending message, issue "strikes" to the user, log the incident, and ultimately apply a predefined punishment (Timeout, Kick, or Ban) when a user accumulates a maximum number of strikes. This automated enforcement helps maintain a clean and safe community environment with minimal manual intervention from moderators.

The entire system is highly configurable through a suite of slash commands, allowing administrators to tailor its behavior to their specific community needs. This includes setting strike thresholds, defining punishments, and whitelisting channels where automod rules should not apply.

Core Architecture and Processing Flow

The heart of the Automod system is the performAutomod function located in src/handlers/automod.ts. This function is triggered for incoming messages and orchestrates the entire moderation process.

Initial Checks

Before any moderation rules are applied, the shouldModerate function performs several preliminary checks to determine if a message is eligible for moderation. This prevents the bot from acting on messages from moderators or in channels where it lacks the necessary permissions.

A message will be moderated only if all the following conditions are met:

1. The message is from a valid guild member.
2. The bot has the ManageMessages permission in the message's channel.
3. The message author is not a server moderator (does not have KickMembers, BanMembers, or ManageGuild permissions).
4. The message author is not a channel moderator (does not have ManageMessages permission in the channel).
5. The channel is not in the automod whitelist (automod.wh_channels).
6. The automod.debug flag is enabled (this seems to act as a master switch for the handler).

Sources: src/handlers/automod.ts:32-52, src/handlers/automod.ts:60-62

Message Processing Flow

If a message passes the initial checks, it enters the main processing pipeline. The system evaluates the message against a series of configured rules. Each rule violation contributes to a strikesTotal count for that message.

This diagram illustrates the high-level logic flow within the performAutomod function.

Violation Detection Rules

The system checks for several types of violations. Each detected violation adds strikes and may flag the message for deletion.

Violation Type	Configuration Setting	Action	Strikes Added
Max Mentions	automod.max_mentions	Flags for strike	1
Max Role Mentions	automod.max_role_mentions	Flags for strike	1
Mass Mention	automod.anti_massmention	Flags for strike if @everyone is used or if user/role mentions exceed the limit.	1 per violation type
Max Lines	automod.max_lines	Deletes message, flags for strike	1
Attachments	automod.anti_attachments	Deletes message, flags for strike	1
Links	automod.anti_links	Deletes message, flags for strike	1
Discord Invites	automod.anti_invites	Deletes message, flags for strike. Only checked if anti_links is off.	1
Spam	automod.anti_spam	Deletes message, flags for strike. Detects identical content posted in different channels within a short time frame. Only checked if anti_links is off.	1

Sources: src/handlers/automod.ts:77-184

Anti-Spam Cache

The anti-spam mechanism uses a local antispamCache to track messages containing links. If a user sends the same message content with a link to a different channel within the MESSAGE_SPAM_THRESHOLD (3000ms), it is flagged as spam. The cache is periodically cleaned every 10 minutes.

Sources: src/handlers/automod.ts:12-25, src/handlers/automod.ts:151-174

Actions and Consequences

When one or more violations are detected, a sequence of actions is triggered.

1. Message Deletion: If any rule violation sets shouldDelete to true, the message is deleted. A temporary confirmation "auto-moderation. message deleted." is sent to the channel.
   Sources: src/handlers/automod.ts:187-194, src/data/respAutomod.json:13-17
2. Strike Application: The total calculated strikesTotal are added to the user's strikes count in the Member database schema.
   Sources: src/handlers/automod.ts:198-199
3. Database Logging: A detailed log of the violation is saved to the automod-logs collection using the addAutoModLogToDb function. This includes the reason, content, and number of strikes.
   *Sources: src/handlers/automod.ts:202-205, src/database/schemas/AutomodLogs.ts
4. Channel Logging: An embed summarizing the violation is sent to the guild's configured logs_channel.
   Sources: src/handlers/automod.ts:208-226
5. User Notification: The user receives a Direct Message detailing the violation, the number of strikes they received, and their new total strike count.
   Sources: src/handlers/automod.ts:229-242
6. Punishment: If the user's new total strike count meets or exceeds the configured automod.strikes limit, the configured automod.action (TIMEOUT, KICK, or BAN) is executed by ModUtils.addModAction. The user's strikes are then reset to 0.
   Sources: src/handlers/automod.ts:245-256

Configuration Commands

Server administrators can configure the Automod system using slash commands.

/automod

This is the primary command for managing general automod settings.

Subcommand	Description	Options
status	View the current automod configuration.	-
strikes	Set the maximum number of strikes a user can receive before action is taken.	amount (Integer)
action	Set the punishment to apply when max strikes are reached.	action (String: TIMEOUT, KICK, BAN)
debug	Toggles whether automod ignores messages from staff.	status (String: ON, OFF)
whitelist	View all channels currently exempt from automod.	-
whitelistadd	Add a channel to the automod exemption list.	channel (Channel)
whitelistremove	Remove a channel from the automod exemption list.	channel (Channel)

Sources: src/commands/admin/automod/automod.ts:11-125

/autodelete

This command manages rules that trigger automatic message deletion.

Subcommand	Description	Options
attachments	Automatically delete messages with file attachments.	status (String: ON, OFF)
invites	Automatically delete messages with Discord invite links.	status (String: ON, OFF)
links	Automatically delete messages containing any URL.	status (String: ON, OFF)
maxlines	Automatically delete messages that exceed a specified line count.	amount (Integer, 0 to disable)

Sources: src/commands/admin/automod/autodelete.ts:9-85

The overall status of automod settings can also be viewed as part of the comprehensive /settings status command.
Sources: src/commands/admin/settings/status.ts:85-95

Database Schema

AutomodLogs

Violations are logged in the automod-logs MongoDB collection. This provides a persistent record of all automated moderation actions.

This ER diagram shows the structure of the automod-logs collection.

Field	Type	Description	Required
guild_id	String	The ID of the guild where the violation occurred.	Yes
member_id	String	The ID of the member who committed the violation.	Yes
strikes	Number	The number of strikes issued for this specific violation.	Yes
reason	String	A summary of the rules that were broken.	Yes
content	String	The full content of the offending message.	Yes
moderator	String	The ID of the moderator who took action (in this case, the bot's ID).	Yes

Sources: src/database/schemas/AutomodLogs.ts:4-24