{
  "path": "test",
  "template": {
    "Named": "foo"
  },
  "pragma": {
    "lang": "lua",
    "allowed_caps": []
  }
}

TemplateContext

TemplateContext is a struct that represents the context of a template. Stores data including the templates data, pragma and what capabilities it should have access to. Passing a TemplateContext is often required when using AntiRaid plugins for security purposes.

Fields

• template_data (TemplateData): The data associated with the template.

Example Templates

To help you get started with templating, we have provided a few examples below along with explanations of what/how they work

Example 1: Simple Audit Logging

Explanation

1. Pragma

The first line of the template is a pragma. This is a special statement beginning with @pragma or -- @pragma that tells AntiRaid what language the template is written in, what options to use, and how tools such as CI, websites and other automation should handle your template. The rest of the pragma is a JSON object that contains the options. Note that if you do not provide a pragma, a default one will be used, however this will not allow you to provide capabilities to your template such as sending a message on Discord etc.

In this case, we want to tell AntiRaid that we are coding a template in Lua and that we want to allow the capability to send messages to Discord. This is done by adding the allowed_caps key to the pragma and specifying the capabilities we want to allow as seen below:

-- @pragma {"lang":"lua","allowed_caps":["discord:create_message"]}

Another example of pragma is on the Website:

{"lang":"lua","builderInfo":{"ver":1,"data":{"embeds":[{"title":"Test","description":"","fields":[]}],"content":""},"checksum":"72e7225dfa2725a979fccc763e2e5bac3855f1cd3c10b5cd00c90b53e724db23"},"allowed_caps":["discord:create_message"]}

Here, notice that the builderInfo contains the embeds, content, and checksum of the template. When the user wants to reread their template, the website only has to reread the pragma statement to reconstruct the state and show the right tab (either Builder if they are just making a simple embed, or Advanced if they were making changes to the content of the template itself). Without the pragma, the website would have to use its own arcane syntax on top of comments or execute the template just to reconstruct state.

2. Creating a message

Next, we need to extract the arguments and token from the context. The arguments are passed to the template when it is executed and contain all the data we need to work with. The token is used to authenticate the template and gain access to the templates context in privileged AntiRaid API's. All of this is provided using variable arguments.

local args, token = ...

There are 3 things we want to import for this template to work. The first is the Discord module, which allows us to send messages to Discord. The second is the Interop module, which provides some functions allowing for seamless interoperability between your template and AntiRaid. The third is the Formatters module, which provides some helper methods for formatting audit log fields (formally known as gwevent_fields).

local discord = require "@antiraid/discord"
local interop = require "@antiraid/interop"
local formatter = require "@antiraid/formatters"

Next, we create the embed. args.event_titlename is specific to Audit Logs and contains the friendly name for an event.

-- Make the embed
local embed = {
    title = args.event_titlename, 
    description = "", -- Start with empty description
}

NOTE: You can use the API Reference to see what functions are available in the AntiRaid SDK

3. Adding fields

TIP: When making a template for a Gateway Event, the fields are passed to the template through a table named fields.

The next step is to add fields to the embed. In this case, we can do this by iterating over fields. In Lua, tables can be iterated over using the builtin pairs function like below:

for key, value in pairs(my_table) do
    -- Do something with key and value
end

In the same way, we can now iterate over args.event_data:

for key, value in pairs(args.event_data) do
    -- Do something with key and value
end

When using Audit Log Events, there are two cases to pay attention to, the first is the field itself being nil and the second is the field type being None. In both cases, we don't want to add the field to the embed. Lets do that!

local should_set = false

if value ~= nil and value.field.type ~= "None" then
    should_set = true
end

Lastly, we need to format the field and add it to the description. Luckily, the formatter plugin provides a function for formatting any categorized field. This function is called format_gwevent_field.

local formatted_value = formatter.format_gwevent_field(value)

4. Sending the message

Finally, we can send the message using the Discord module. To do this, we need to create a message object and set the embeds property to an array containing our embed. This is also where interop comes in handy, as we need to set the metatable of the embeds array to the interop array metatable so AntiRaid knows that embeds is an array. Next, we use the Discord plugin to make a new Discord action executor which then lets us send the message to the specified channel (args.sink is another Audit Log specific variable that contains the channel ID/whatever sink is set to in the database).

local message = { embeds = {} }
setmetatable(message.embeds, interop.array_metatable)

table.insert(message.embeds, embed)

-- Send message using action executor
local discord_executor = discord.new(token);
discord_executor:create_message({
    channel_id = args.sink,
    message = message
})

Finally, we can put the entire loop together as so:

-- @pragma {"lang":"lua","allowed_caps":["discord:create_message"]}
local args, token = ...
local discord = require "@antiraid/discord"
local interop = require "@antiraid/interop"
local formatter = require "@antiraid/formatters"

-- Make the embed
local embed = {
    title = args.event_titlename, 
    description = "", -- Start with empty description
}

-- Add the event data to the description
for key, value in pairs(args.event_data) do
    local should_set = false

    if value ~= nil and value.type ~= "None" then
        should_set = true
    end

    if should_set then
        local formatted_value = formatter.format_gwevent_field(value)
        embed.description = embed.description .. "**" .. key:gsub("_", " "):upper() .. "**: " .. formatted_value .. "\n"
    end
end

local message = { embeds = {} }
setmetatable(message.embeds, interop.array_metatable)

table.insert(message.embeds, embed)

-- Send message using action executor
local discord_executor = discord.new(token);
discord_executor:create_message({
    channel_id = args.sink,
    message = message
})

Luau Ecosystem Integration Notes

At AntiRaid, we believe that bot developers should be able to access the best tools available to them. To this end, we have integrated some popular Luau libraries into our templating environment to provide a more powerful and flexible experience while taking into account security and stability of the bot. Below, we outline the libraries that are currently available for use in your Lua templates:

Libraries

• @lune/datetime
• @lune/regex
• @lune/serde

Legal Disclaimer

AntiRaid is not affiliated with any of the libraries mentioned above. We do not claim ownership of these libraries or their trademarks whatsoever, nor do we provide any guarantees or warranties regarding their functionality. AntiRaid absolves all liability for any damages or losses incurred through the use of these libraries, both to the libraries owner and to AntiRaid itself.

Hooks And Events

AntiRaid makes use of events for all communication between modules. Modules can either recieve events (e.g. from Discord) or generate their own events (such as PunishmentCreate/PunishmentExpire). This is what makes Anti-Raid so flexible and powerful, especially in templating.

Hooks is a module that listens for all Anti-Raid events and lets you dispatch a template whener an event is recieved (or generated) by Anti-Raid.

Discord Events

Discord Events are special. AntiRaid uses Serenity for handling Discord events. As such, please see Serenity's Documentation for what fields are available in each event. It's much better documentation than what we can come up with.

AntiRaid does not modify the events in any way, so you can expect the same fields as what Serenity provides. Note, however, that only the fields are available to templates, not the methods provided by Serenity.

Captcha

Introduction

WARNING: Captcha's are being heavily churned/rewritten into a new Lua plugin

A CAPTCHA is a security measure that can be used to try and filter out the more basic and spammy bots from accessing your server. It presents a challenge that users must complete to prove they are human. This can help protect your server from unwanted automated access and ensure that real users can interact with your community. Note that CAPTCHA's are NOT foolproof and that more sophistiated bots may still bypass them.

Of course, with the current landscape with AI everywhere, just serving a single CAPTCHA type (or config) does not really work. Furthermore, AntiRaid recognizes that different servers have different needs. Therefore, we provide a flexible CAPTCHA system, fully integrated with our Lua Templating system that allows you to completely customize the CAPTCHA experience for your users. This occurs through filters.

Examples

Sample CAPTCHA

local interop = require "@antiraid/interop"
local img_captcha = require "@antiraid/img_captcha"

local captcha_config = {}

-- Basic options
captcha_config.char_count = 7
captcha_config.filters = {}
setmetatable(captcha_config.filters, interop.array_metatable) -- Filters is an array
captcha_config.viewbox_size = { 280, 160 }
setmetatable(captcha_config.viewbox_size, interop.array_metatable) -- Viewbox size is a tuple

-- Add noise filter
local noise_filter = {
    filter = "Noise",
    prob = 0.05
}

table.insert(captcha_config.filters, noise_filter)

-- Add wave filter
local wave_filter = {
    filter = "Wave",
    f = 4.0, -- Frequency
    amp = 20.0, -- Amplitude
    d = "horizontal" -- Direction
}

table.insert(captcha_config.filters, wave_filter)

-- Add grid filter
local grid_filter = {
    filter = "Grid",
    x_gap = 10,
    y_gap = 30
}

table.insert(captcha_config.filters, grid_filter)

-- Add line filter
local line_filter = {
    filter = "Line",
    p1 = setmetatable({ 0.0, 0.0 }, interop.array_metatable),
    p2 = setmetatable({ 30.0, 100.0 }, interop.array_metatable),
    thickness = 7.0,
    color = setmetatable({ 0, 0, 0 }, interop.array_metatable)
}

table.insert(captcha_config.filters, line_filter)

-- Add color invert filter
local color_invert_filter = {
    filter = "ColorInvert"
}

table.insert(captcha_config.filters, color_invert_filter)

-- Add random line filter
local random_line_filter = {
    filter = "RandomLine"
}

table.insert(captcha_config.filters, random_line_filter)

local captcha = img_captcha.new(captcha_config)

return captcha

CAPTCHA with increasing char count with maximum of 5 tries per user

local args, token = ...
local interop = require "@antiraid/interop"
local img_captcha = require "@antiraid/img_captcha"

local captcha_config = {}

-- Check __stack.users
if __stack._captcha_user_tries == nil then
    __stack._captcha_user_tries = {} -- Initialize users table
end

-- Check __stack._captcha_user_tries[args.user.id]
if __stack._captcha_user_tries[args.user.id] == nil then
    __stack._captcha_user_tries[args.user.id] = 0 -- Initialize user's try count
end

-- Check if user has reached maximum tries
if __stack._captcha_user_tries[args.user.id] >= 5 then
    return { __error = "You have reached the maximum number of tries in this 5 minute window."}
end

-- Basic options
captcha_config.char_count = math.min(7 + __stack._captcha_user_tries[args.user.id], 10) -- Increment the number of characters

captcha_config.filters = {}
setmetatable(captcha_config.filters, interop.array_metatable) -- Filters is an array
captcha_config.viewbox_size = { 280, 160 }
setmetatable(captcha_config.viewbox_size, interop.array_metatable) -- Viewbox size is a tuple

-- Increment the maximum number of tries
__stack._captcha_user_tries[args.user.id] += 1

captcha = img_captcha.new(captcha_config)
return captcha

Lockdowns

Lockdowns are a way to allow restricting (or 'locking down') specific channels or roles within a server when under an attack or other such crises.

Migrating from other bots

If you are coming from Wick or another anti-nuke bot like Wick, please note that AntiRaid's lockdown functionality only applies to locking down channels and roles. This means that the following Wick features are not present in AntiRaid lockdowns and are instead part of other more appropriate modules as listed below:

• Join Auto Kick (present in Inspector Auto Response Member Join)
• Join Auto Ban (present in Inspector Auto Response Member Join)
• Role Lockdown (WIP, not yet implemented)
• All / Server Wide (Most likely will not be implemented)

Note that blind lockdowns are not yet implemented in Anti-Raid.

For the sake of comparisons, here is how each lockdown mode compares to Wick's lockdown modes:

• Quick Server Lockdown (qsl) -> Wick's Channels (sc) lockdown (general performance+requirements for use should be the same as Wick's lockdown feature)
• Traditional Server Lockdown (tsl) -> No equivalent in Wick
• Single-Channel Lockdown (scl) -> Wick's Channel (c) lockdown (note that locking down multiple specific channels at once is not yet implemented in AntiRaid)

Usage Notes

If you want to know more details on each type of lockdown, how they are applied and how multiple lockdown conflicts are resolved, please refer to the dev docs for lockdown

Member Roles

When you first setup lockdown for the first time, you will be prompted for a set of member roles like below:

These roles are what AntiRaid will actually lock-down which is why they are also known as 'critical roles'.

Quick Server Lockdowns

For servers that can meet its restrictions, a quick server lockdown is the fastest way to lockdown your server in a raid. It is recommended to use this lockdown mode if possible. When using this mode, it is important to note one critical requirement:

• All critical roles must have View Channel and Send Messages. All other roles must not have View Channel and Send Messages.

What this looks like is something like the following:

Figure 1 shows a normal role without View Channel of Send Messages permissions

Figure 2 shows a critical role with View Channel and Send Messages permissions

The above two figures are how you want to configure your critical/member and normal roles. Basically, turn off View Channel and Send Messages for all your normal roles and turn it on for your critical/member roles you set up earlier in the settings for lockdown.

To make a quick server lockdown, you can use the qsl type. For example, to lock down a server, you can use the following slash command:

/lockdown lock type:qsl reason:There is a raid going on

Traditional Server Lockdown

Traditional Server Lockdown is a more traditional lockdown method. It is more flexible than Quick Server Lockdown as it has no required prior setup. However, it is much slower and should be avoided if possible.

WARNING: Super large servers may have outages when using a traditional server lockdown that a quick server lockdown may not lead to.

To make a traditional server lockdown, you can use the tsl type. For example, to lock down a server, you can use the following slash command:

/lockdown lock type:tsl reason:There is a raid going on

Single-Channel Lockdown

In some cases, only a single channel needs to be locked down. In such a case, a single-channel lockdown is needed.

To make a single-channel lockdown, you can use the scl type. For example, to lock down a server, you can use the following slash command:

/lockdown lock type:scl/<channel_id> reason:There is a raid going on

Where <channel_id> is the ID of the channel to lockdown.

Backups

What's backed up

Guild structure (roles/channels/name/icon/other settings), some messages (Discord has limits here) and attachments (within reasonable limits).

What's not backed up?

Members and bots. Note that for members, we have something coming up soon that may allow you to 'backup/restore' (with consent + regularly re-providing consent) members.

Note that new discord features may also not be backed up/restored immediately on release.

More details

See the dev guide to learn more about the format

Go Jobserver

The Go Jobserver handles server backups, message prunes and other long running tasks on a server

Backups

Note that this document describes the technical details of the backup system

Format

A backup is an https://github.com/infinitybotlist/iblfile with the standard AutoEncryptedFile format and has the following fields:

• backup_opts - JSON containing a types.BackupCreateOpts object
• core/guild - The core guild data (discordgo.Guild)
• assets/{asset_name} - The guild icon data ([]byte)
• messages/{channel_id} - The messages in a channel along with basic attachment metadata ([]types.BackupMessage).
• dbg/* - Debug information. This may vary across backups and MUST NOT be used in restoring a backup.
• attachments/{attachment_id} - The attachments data itself

Definitions

• Critical Roles: the roles which are given to members and should hence be locked down. In essence, one can define a set of critical roles (hence the name) which are either the critical roles and defaults to the @everyone role if not set.

Lockdown Types

Quick Server Lockdown

Specificity

• 0 (Lowest specificity)

Rationale

Quickly lockdown a server as fast as possible

Syntax

• qsl

Description

Quick Lockdown allows for quickly locking down a server given the following permission overwrite setup:

• All critical roles must have View Channel and Send Messages. All other roles must not have View Channel and Send Messages

Internally, qsl modifies only the critical roles to the locked down set of permissions. This requires much fewer API calls and is hence much faster than traditional lockdowns.

Traditional Server Lockdown

Specificity

• 1 (TSL > QSL as it updates all channels in a server)

Rationale

In many cases, the requirements for qsl are not feasible for servers to meet. In such a case, a traditional lockdown is needed.

Syntax

• tsl

Description

Traditional Lockdown is a more traditional lockdown method. It is more flexible than qsl as it has no required prior setup. However, it is much slower and should be avoided if possible.

Internally, tsl works by iterating over all channels and setting the permission overwrites for all critical roles to the locked down set. This is a slow process and can take a long time for large servers. In addition, super large servers may have outages when using a tsl that a qsl may not lead to.

Single-Channel Lockdown

Specificity

• 2 (SCL > TSL as it updates a single channel)

Rationale

In some cases, only a single channel needs to be locked down. In such a case, a single-channel lockdown is needed.

Syntax

• scl/<channel_id>

Where <channel_id> is the ID of the channel to lockdown

Description

Single-Channel Lockdown is a lockdown method that locks down a single channel.

Internally, scl/<channel_id> works by setting the permission overwrites for all critical roles to the locked down set for the specified channel. This is a fast process and is recommended for locking down a single channel.

Specificity

When multiple lockdowns are made on the same item (which will now be called a handle from now on), there needs to be a way to know what lockdown owns/has the handle. In AntiRaid, this is controlled through specificity based on the rules:

• Rule 0: When a handle is locked, the priority is added without replacing older priorities. When a handle is unlocked, the priority is removed leading to its previous value.
• Rule 1: A handle is controlled unlocked by a lockdown A if the lockdown (say, lockdown B) corresponding to the largest specificity that has locked the handle is less than the specificity of lockdown A. Otherwise, it is considered locked and cannot be modified by lockdown A.
• Rule 2: The underlying permissions or permission overwrites of a role/channel are defined as the saved permissions/permission overwrites of the role/channel of the oldest possible lockdown which has saved said data.

As an example, consider a case where a tsl is first applied and then an scl/<channel_id>. As per Rule 1, the tsl has a lower specificity than the scl/<channel_id> and so the scl/<channel_id> will also lock the channel handle. When the tsl is then removed, the channel is still locked by scl/<channel_id> which has a greater specificity. Hence, by Rule 1, the scl/<channel_id> locked channel will remain locked even after the tsl is removed as expected.

Next, consider what happens when the scl/<channel_id> is removed. As tsl stores the original channel permission overwrites of all channels and was created before the scl/<channel_id>, Rule 2 applies. Hence, the underlying permissions of the channel is considered to come from the tsl's stored data and NOT the scl/<channel_id> which was set during the lockdown. This means that when the scl/<channel_id> is removed, the channel will revert to the permissions it had before the tsl was applied which was the original channels permissions.

As such, using Rules 1 and 2, the following holds true:

tsl + scl/<channel_id> - tsl - scl/<channel_id> = 0

Silverpelt

Silverpelt provides a standard library for all Anti-Raid modules.

To create a new Anti-Raid bot making use of Anti-Raid modules, simply implement the trait silverpelt::module::Module. These modules must then be added to a SilverpeltCache which is then inserted into silverpelt::Data.

Most things in silverpelt are abstracted out through traits or dispatched via events. This allows silverpelt to be used as an abstract interface allowing for Anti-Raid to quickly evolve and change/adapt to different targets.

Note: AntiRaid uses a event-driven architecture. This means that modules+the main bot process make events that are dispatched to modules. The event system is currently passive (meaning there is no continously running event loop), however this is subject to change in the future.

Interfaces

Sting

Silverpelt provides concrete structures, utilities and special events for handling stings.

Punishments

Silverpelt provides concrete structures, utilities and special events for handling punishments.

Some extra misc points

• A command is the base unit for access control. This means that all operations with differing access controls must have commands associated with them.

• This means that all operations (list backup, create/restore backup, delete backup) MUST have associated commands

• Sometimes, an operation (such as a web-only operation) may not have a module/command associated with it. In such cases, a 'virtual' module should be used. Virtual modules are modules with commands that are not registered via Discord's API. They are used to group commands together for access control purposes and to ensure that each operation is tied to a command

Anti-Raid Templating System

Supported Languages

• Lua (luau / Roblox Lua) - Tier 1

Lua is the recommended language for templating

WIP/Potential Languages

• JavaScript (see lang_javascript_quickjs and lang_javascript_v8 for the current load experiments + integration experiments), potential but unlikely unless someone finds a solution
• WebAssembly (potential, not yet decided)

Language Requirements

1. All languages must export the following modules/helpers to the extent required as per the templating documentation. (TODO: Improve this spec)

• Messages
• Permissions
• Captcha
• Actions
• Key Value API

2. All languages must provide a way to sandbox the execution of the code. This is a security requirement. In particular, timeouts and heap/stack/memory limits are required.
3. Callers must use the abstracted out function calls from lib.rs

My language vent

For reference on my discord vents: https://discord.com/channels/763812938875535361/1040734156327501905/1267195190100361440

Why is lua the only sane language for embedding V8 has big ffi problems with rust. If you try spawning too many isolates, you have a 100% chance of aborting your process and this issue can only be resolved by performing unsafe void* pointer casts Quickjs is a bit too slow and poorly documented Rhai is good but it’s a custom language and it’s sandboxing abilities need unsafe code to fully work (and said unsafe code involves pointer arithmetic that is not thread safe) and heap memory limits require you to manually calculate the heap usage Tera has virtually no safety features and will gladly execute an infinite recursion For starlark/skylark, go to the point on rhai but hopefully without the unsafe bits I can understand now why the game modding industry uses lua, it’s basically the only sane language for handling user input Lua is legit the only sane scripting language on this entire list

[rhai is not only slower than lua, its sandboxing (i said it above here too in a vent i think) requires actual pointer arithmetic that isnt thread safe, its also a custom lang no one knows while lua is well known in the game community. Luau is used in Roblox games so it caters to Discords target market as well]

Template Tokens

All lua templates include a special template token in addition to the template arguments. Modules requiring more privileged levels of access (or otherwise require the template state) should require this token and use it to access the required template state.

Text difference utilities

diff.rs: Taken from https://docs.rs/text-diff/latest/src/text_diff with some modernizing. All credits go to the author.

Other utilities are taken too. To be documented