Heuristics

Understand the range of Heuristics for SajuukBot and the individual configuration settings available.

SajuukBot will be ceasing operations on March 31st 2024, due to a variety of factors. For more information, please refer to the announcement provided on the SajuukBot discord server and your options for migrating to a new bot.

So you have the censor automods set up, you've got the filters automods set up, but you still have issues with people spamming and you need them punished in some way.... never fear, thats what the Heuristics automod is for! Heuristics is basically a higher level version of Filters, with the following main difference:

• Heuristics allow punishment actions to be taken, such as tempmutes, permamutes, kicks and bans. This means that there are consequences for the users' actions if they trigger these filters, which also function as a quick and effective way of silencing spammers.

The system works best as a "last defence" against people who are egregiously spamming or being disruptive.

Configuration

This section of configuration needs to be placed under the anti spam module as an indented element. Please see the full basic configuration for more details on how it should be formatted.

  heuristics:
    enabled: false
    duplicates:
      enabled: false
      clean: false
      trigger: 20
      punishment: tempmute
      tempmute length: 0
      time: 60
    scams:
      enabled: false
      trigger: 10
      punishment: tempmute
      tempmute length: 0
      time: 60
    max messages:
      enabled: false
      clean: false
      trigger: 20
      punishment: tempmute
      tempmute length: 0
      time: 60
    newlines:
      enabled: false
      clean: false
      trigger: 100
      punishment: tempmute
      tempmute length: 0
      time: 120
    links:
      enabled: false
      clean: false
      trigger: 25
      punishment: tempmute
      tempmute length: 0
      time: 100
    mentions:
      enabled: false
      clean: false
      trigger: 50
      punishment: tempmute
      tempmute length: 0
      time: 90
    attachments:
      enabled: false
      clean: false
      trigger: 25
      punishment: tempmute
      tempmute length: 0
      time: 75

Settings

Each tab contains more details on each setting described in the configuration above

Every section allows an optional level field to be defined. If it is included in the relevant sections, then the bot uses that level to determine if a user has been excluded.

Note that the bot always uses a more specific level definition over more general ones first, so if a level is defined under a specific filter(eg duplicates), that one will be used over any global setting (either within the filters block itself or within the anti spam block).

Core

Setting	Description
enabled	Globally toggles the heuristics system on or off. If this has been disabled, none of the heuristics will be available.
level	The minimum level at which a user is automatically exempted from the heuristics functionality. This setting is optional, but it is also "global" to all heuristics and will be used if no specific level has been defined in a heuristic.

Duplicates

Setting	Description
enabled	Toggles the duplicates heuristic. If this is disabled, repeat messages containing the same content will not be actioned on.
clean	Whether to clean messages. If this is disabled, the heuristic will not remove the offending messages that caused the filter to be triggered.
trigger	The number of repeat messages that need to be sent to count as having violated the constraints.
punishment	The action to be taken by the bot for any heuristic violations. Possible values that may be given are tempmute, kick, mute and ban
tempmute length	The length of time that the tempmute should last (expressed in hours). This only matters if the punishment is tempmute, otherwise it has no effect. If the value is 0, or you do not include this key in your configuration, the default value is used automatically.
time	The amount of time in which the trigger value needs to be reached to count as having violated the constraints. EG: If trigger equals 5 and time equals 30, that means 5 duplicates need to be sent within 30 seconds to cause the bot to take action.

Scams

The scams filter uses an internal blocklist that contains all known phrases and keywords that have been attributed to a scam. Since scam messages in servers get posted to all possible channels that the scammer can post in, the feature always auto-deletes messages and the ability to prevent the bot from cleaning messages is not available.

Setting	Description
enabled	Toggles the scams heuristic. If this is disabled, messages containing phrases known to be used by compromised accounts to spread scams will not be filtered.
trigger	The number of scam messages that need to be sent across the server to count as having violated the constraints.
punishment	The action to be taken by the bot for any heuristic violations. Possible values that may be given are tempmute, kick, mute and ban
tempmute length	The length of time that the tempmute should last (expressed in hours). This only matters if the punishment is tempmute, otherwise it has no effect. If the value is 0, or you do not include this key in your configuration, the default value is used automatically.
time	The amount of time in which the trigger value needs to be reached to count as having violated the constraints. EG: If trigger equals 5 and time equals 30, that means 5 scam messages need to be sent within 30 seconds to cause the bot to take action.

Max Messages

Setting	Description
enabled	Toggles the max messages heuristic. If this is disabled, multiple unique messages will not be actioned on.
clean	Whether to clean messages. If this is disabled, the heuristic will not remove the offending messages that caused the filter to be triggered.
trigger	The number of unique messages that need to be sent to count as having violated the constraints.
punishment	The action to be taken by the bot for any heuristic violations. Possible values that may be given are tempmute, kick, mute and ban
tempmute length	The length of time that the tempmute should last (expressed in hours). This only matters if the punishment is tempmute, otherwise it has no effect. If the value is 0, or you do not include this key in your configuration, the default value is used automatically.
time	The amount of time in which the trigger value needs to be reached to count as having violated the constraints. EG: If trigger equals 20 and time equals 60, that means 20 messages need to be sent within 60 seconds to cause the bot to take action.

New Lines

Setting	Description
enabled	Toggles the new lines heuristic. If this is disabled, the number of new lines in a message, or multiple messages, will not be actioned on.
clean	Whether to clean messages. If this is disabled, the heuristic will not remove the offending messages that caused the filter to be triggered.
trigger	The number of new lines that need to be sent to count as having violated the constraints.
punishment	The action to be taken by the bot for any heuristic violations. Possible values that may be given are tempmute, kick, mute and ban
tempmute length	The length of time that the tempmute should last (expressed in hours). This only matters if the punishment is tempmute, otherwise it has no effect. If the value is 0, or you do not include this key in your configuration, the default value is used automatically.
time	The amount of time in which the trigger value needs to be reached to count as having violated the constraints. EG: If trigger equals 100 and time equals 120, that means 100 new lines need to be sent within 120 seconds to cause the bot to take action.

Links

Setting	Description
enabled	Toggles the links heuristic. If this is disabled, the number of links in a message, or multiple messages, will not be actioned on.
clean	Whether to clean messages. If this is disabled, the heuristic will not remove the offending messages that caused the filter to be triggered.
trigger	The number of links that need to be sent to count as having violated the constraints.
punishment	The action to be taken by the bot for any heuristic violations. Possible values that may be given are tempmute, kick, mute and ban
tempmute length	The length of time that the tempmute should last (expressed in hours). This only matters if the punishment is tempmute, otherwise it has no effect. If the value is 0, or you do not include this key in your configuration, the default value is used automatically.
time	The amount of time in which the trigger value needs to be reached to count as having violated the constraints. EG: If trigger equals 25 and time equals 100, that means 25 links need to be sent within 100 seconds to cause the bot to take action.

Mentions

Setting	Description
enabled	Toggles the mentions heuristic. If this is disabled, the number of mentions (user or role) in a message, or multiple messages, will not be actioned on.
clean	Whether to clean messages. If this is disabled, the heuristic will not remove the offending messages that caused the filter to be triggered.
trigger	The number of mentions (user or role) that need to be sent to count as having violated the constraints.
punishment	The action to be taken by the bot for any heuristic violations. Possible values that may be given are tempmute, kick, mute and ban
tempmute length	The length of time that the tempmute should last (expressed in hours). This only matters if the punishment is tempmute, otherwise it has no effect. If the value is 0, or you do not include this key in your configuration, the default value is used automatically.
time	The amount of time in which the trigger value needs to be reached to count as having violated the constraints. EG: If trigger equals 50 and time equals 90, that means 50 unique mentions need to be sent within 90 seconds to cause the bot to take action.

Attachments

Setting	Description
enabled	Toggles the attachments heuristic. If this is disabled, the number of attachments in a message, or multiple messages, will not be actioned on.
clean	Whether to clean messages. If this is disabled, the heuristic will not remove the offending messages that caused the filter to be triggered.
trigger	The number of attachments that need to be sent to count as having violated the constraints.
punishment	The action to be taken by the bot for any heuristic violations. Possible values that may be given are tempmute, kick, mute and ban
tempmute length	The length of time that the tempmute should last (expressed in hours). This only matters if the punishment is tempmute, otherwise it has no effect. If the value is 0, or you do not include this key in your configuration, the default value is used automatically.
time	The amount of time in which the trigger value needs to be reached to count as having violated the constraints. EG: If trigger equals 26 and time equals 75, that means 25 attachments need to be sent within 60 seconds to cause the bot to take action.