Permissions

Permissions

The various command suites add many features to a CoreBot, but it's not a good idea to give every user on your server access to all commands. Here we'll explain how the permissions.yml file works and give you some recommendations

Rules

The basic building block of the permissions file is rules. Each rule specifies a list of commands to allow or deny access to, and what users the rule applies to. Rules appear under the permissions key of the permissions.yml file

To specify what commands a rule allows or denies, use allow or deny:

allow:
  - ignore
  - pardon

This would grant access to the !ignore and !pardon commands, but it's not a complete rule, because we didn't define who it applies to.

To specify who a rule applies to, use either role or users, but not both.

• role should be the name, or id of a role in your server that the rule would apply to. Any user who has that role when they issue a command will inherit permissions from the rule.

role: admin

Would apply the rule to any users with the admin role. Note: Role names are only checked during startup and are translated to ids.

• users should be a list of fullnames or ids of members of your server who the rule should apply to. Any user with a matching id or full name (including the #discriminator) will inherit permissions from the rule. Nicknames and incomplete names (without the #discriminator) cannot be used. Usernames are checked once at startup and are translated to ids. Note that it is recommended that you use ids as discord Nitro users have control of their discriminator and could use this to gain access to permissions

users:
  - 12345678
  - username#1234

This rule would apply to the user with id '12345678', as well as the user with the name 'username#1234'. At startup the bot would fetch the id of 'username#1234' so if that user changed their name, they would keep the rule until next startup and if a discord nitro user changed their name to 'username#1234' they would not inherit permissions until the next startup

Underscore

There is one last option for rules, which can be used to blanket allow or deny access to administrator commands (which start with an underscore).

If you set underscore in a rule to true or false, the user will be granted or denied access to commands starting with an underscore. The allow and deny keys take precedence, so you could set underscore to false to disable all admin commands, then explicitly list a few in allow.

One last thing

As a convenience, you can list $all as a command for allow and deny to allow or deny access to all non-underscore commands.

A complete rule

So far we have seen the components of rules, but haven't seen anything complete. Here are a few examples of what a complete rule looks like

role: moderator
allow:
  - output-dev
  - output-prod
  - bug:label
  - bug:status
  - bug:user
  - ignore
  - pardon

This would grant output-dev, output-prod, bug:label, bug:status, bug:user, ignore, and pardon to all users with the role 'moderator'.

users:
  - 12345678
allow:
  - ignore
deny:
  - pardon

This would grant access to ignore to the user with id '12345678', but deny access to pardon

role: admin
allow:
  - $all
underscore: true

This would grant access to all commands to the role 'admin'

users:
  - some_troublemaker#1234
  - 5678
deny:
  - $all
underscore: false

This would deny access to all commands to the user with id '5678' and the user with name 'some_troublemaker#1234'

Rule precedence

When a user issues a command, the bot grabs all the rules that apply to that user and checks them one-by-one until it finds a rule which either allows or denies the command. If the user has no rules which apply to the command, there are defaults, but we'll get to those later.

Rules are checked in the following order:

• Rules which use users, in order from least number of users in the list to most
• Rules which use role, in the order that roles appear in the server's role hierarchy
• The default rule (see below)
• Deny the command if starts with underscore, allow it otherwise

In other words,

users:
  - just_me#1234
deny:
  - bid

takes precedence over

users:
  - just_me#1234
  - someone_else#1234
allow:
  - $all

Because the first rule only lists one user, 'just_me#1234' would not have access to the !bid command.

- role: moderator
allow:
  - $all
underscore: false

- role: admin
underscore: true

In this example, users with both the 'admin' and 'moderator' roles would have access to all commands, assuming 'admin' appears higher in the role hierarchy. If a user just had 'admin' and not 'moderator' they would only have access to admin commands.

Defaults

After all other rules for a user have been checked, if none have defined a policy for the current command, the bot checks default permissions. You can specify defaults, using the defaults key in the permissions file. The default rule is like any other rule, except that it does not use role or users. It applies to all users but has the lowest priority of any rule.

For example:

defaults:
  deny:
    - satisfied
    - output-prod
    - output-dev
    - bug:label
    - bug:status
    - bug:user
    - owupdate
    - ignore
    - pardon
  underscore: false

This would deny access to all underscore commands as well as the listed commands, in the event that no other rule applies to a user for those commands.

The best policy is often to simply list the commands that you don't want regular users using under deny here. We don't have to explicitly list the other commands to allow because of the fallback behavior:

In the event that no rule for a user (including defaults) allows or denies access to a command, it is denied if it starts with an underscore and allowed otherwise.

Essentially, all users start with access to every non-underscore command. You should use defaults to deny access to additional commands that you don't want regular users using, and then set rules under permissions to add back permissions to specific users and roles.

Putting it all together

A complete permissions.yml file has the following structure

defaults:
  # The defaults rule
permissions:
  # A list of rules

Here is an example of a complete permissions file, used on our server

defaults:
  deny:
    - kill-beymax
    - satisfied
    - output-dev
    - output-prod
    - bug:label
    - bug:status
    - bug:user
    - owupdate
    - ignore
    - pardon
  underscore: false
permissions:
  - users:
      - 12345678
    underscore: true
  - role: Developer
    allow:
      - $all
    underscore: true
  - role: Mod
    allow:
      - kill-beymax
      - satisfied
      - bug:label
      - bug:status
      - bug:user
      - ignore
      - pardon
  - role: Blacklisted
    deny:
      - $all