This is an old revision of the document!

BeBot's Security Management System


BeBot's Security Management System aims to provide a common interface and structure for dealing with all things security. This document provides a technical specification and my notes for the developer(s) of BeBot's security system.

Access Levels

The core of BeBot security is the Access Level. An Access Level is a defined constant that cannot be changed. Access Levels are not groups, even though the SUPERADMIN, ADMIN, and LEADER access levels have the same names as BeBot's default security groups.

BeBot has 8 Access Levels:

  1. OWNER (Bot Owner)
  3. ADMIN
  5. MEMBER (A member of the bot. Guild members in guildbot mode.)
  6. GUEST (Someone added to the guildbot's guest list (Not used in raidbot mode by default))
  7. ANONYMOUS (Someone who is not a guest or member, but sends a tell to the bot.)
  8. BANNED (Someone who has been banned.)

All access is defined by these eight levels.

Access Levels and Group Conventions

  1. Access Levels should always be referred to in UPPERCASE letters.
  2. Security Groups are always referred to in lowercase letters.
  3. No spaces or special characters are allowed in group names.

Determining a user's access

BeBot keeps security related information in multiple locations:

  • users.user_level
  • whois.org_rank_id (Guildbot Mode Only)
  • admin_groups and admin_members
  • Config file hard coding.

In order to bring all this information into one system, the $this → bot → security → get_access_level($player) function will return the highest access level granted to the player. To determine the players access level, the get_access_level function first checks the owner and superadmins configured in Bot.conf. If the player is configured as the bot's owner in the bot's configuration file, 256 is returned and no further checks are done. If the player is configured as a superadmin, 255 is returned and no further checks are done. This prevents the configured owner and superadmin from accidentally being banned from the bot.

The second check is the status of the user in the users table. If the player is banned, no further checks are done and -1 is returned. Otherwise, the player's user level is stored in memory for use in subsequent checks.

The third check is the player's Org Rank (in Guildbot mode only.) The bot owner can assign access levels to Org Ranks. For example, the President of an organization can be assigned LEADER, ADMIN, or SUPERADMIN privileges without adding them to the bot's configuration file or one of BeBot's groups. If the access level assigned to the player's org rank is higher than the level assigned to them in the users table, the org rank access level is stored in memory (replacing the user level) for use in subsequent checks.

The final check is default and custom groups. The bot's owner can add users to the leader, admin, and superadmin groups as well as create custom groups and assign the custom groups one of the 8 access levels. The highest group access level is found then compared with the highest access level that was discovered in check 2 and 3. The highest value is then returned.

If any value is outside the valid range (A value less than -1 or greater than 256) is discovered, the function will return -1 banned as something seems to have gone wrong. (Tampering in the database, or editing the code to change defined access levels.)

Using the Security System in your modules

To make security easy for module developers, the check_access function provides all the security checks you will need. When assigning security to commands, you should always use one of the eight access levels, not security groups. This allows the bot user full flexibility with their configuration as org ranks and custom security groups are assigned access levels.

For example, your module should only be used by bot leaders. You would use the following code:

if ($this -> bot -> security -> check_access($playername, "LEADER"))
    return "You are a LEADER or higher on <botname>!";
    return "You are not a LEADER or higher on <botname>";

check_access returns TRUE if the player meets or exceeds the level you are checking. A player with an access level of LEADER, ADMIN, SUPERADMIN, or OWNER all meet or exceed the LEADER requirement.

Security Cache Array

$this -> cache['groups'][$group_name]['acl'] = INT; // access level
$this -> cache['groups'][$group_name]['gid'] = INT; // group id number
$this -> cache['groups'][$group_name]['gn'] = STRING; // group name
$this -> cache['groups'][$group_name][$member_nick] = STRING; // group member nickname
$this -> cache['members'][$nickname] = STRING; // group member nickname
$this -> cache['guests'][$nickname] = STRING; // group member nickname
$this -> cache['banned'][$nickname] = STRING; // group member nickname
$this -> cache['orgranks'][$rank_name] = INT; // access level

Security Cache Management

The cache_mgr($action, $cache, $info, $more) function is used to add and remove information from the security cache. The cache manager function should only be called by functions that are modifying security (adding users, groups, changing group membership, etc.)

Description of function parameters: $action: add or rem $cache: Which cache to modify (groups, guests, members, banned, groupmem, orgranks) $info: The information to add (or remove) $more: Extra information needed for some actions. (Optional Parameter)


  • Add and remove a guest:
$this -> cache_mgr("add", "guests", "Glarawyn");
$this -> cache_mgr("rem", "guests", "Glarawyn");
  • Add and remove a member:
$this -> cache_mgr("add", "members", "Glarawyn");
$this -> cache_mgr("rem", "members", "Glarawyn");
  • Add and remove a ban:
$this -> cache_mgr("add", "banned", "Glarawyn");
$this -> cache_mgr("rem", "banned", "Glarawyn");
  • Add a group:
$tmp = array("gid" => "10", "name" => "groupname", "description" = "Example Group", "access_level" => 2);
$this -> cache_mgr("add", "groups", $tmp);
  • Remove a group:
$this -> cache_mgr("rem", "groups", $groupname);
  • Add and remove a group member:
$this -> cache_mgr("add", "groupmem", $groupname, $membername);
$this -> cache_mgr("rem", "groupmem", $groupname, $membername);
  • Change an org rank's access level:
$this -> cache_mgr("add", "orgrank", "President", "255");

Security Module Functions

Add a group:

add_group($groupname, $description);

Delete a group:


Add a user to a group:

add_group_member($target, $group)

Remove a user from a group:

del_group_member($target, $group)

Add a member or guest:

add_user($admin, $target, $level="guest")

Remove a member or guest:

del_user($admin, $target)

Set a ban:

set_ban($admin, $target)

Remove a ban:

rem_ban($admin, $target)

Get group id (returns -1 if group doesn't exisit)

  • security_tech_notes.1175191799.txt.gz
  • Last modified: 2020/09/12 01:30
  • (external edit)