Editing Security

BeBot's Security Management System
 	

'''Introduction'''

BeBot's Security Management System aims to provide a common interface and structure for dealing with all things security. This document describes the use of the Security system for Module (and BeBot) Developers.
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 security groups. The SUPERADMIN, ADMIN, and LEADER levels have the same names as BeBot's default security groups. The assist with differentiation, Access Levels are always referred to in uppercase letters and security groups are always lowercase.

BeBot has 8 Access Levels:

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

All access is defined by these eight levels. Membership is additive, meaning if you are in a higher level you automatically are a member of lower levels too, with BANNED being the notable exception. So an ADMIN is a MEMBER, GUEST, LEADER and ANONYMOUS too.
User Levels, Org Ranks, and Security Groups

A user's Access Level is determined by their user level, security group membership, and their org rank. When BeBot is in guildbot mode, all members of the org are made members of the bot when the bot reads the org's roster. In addition to assigning this access level, the bot's superadmins are able to assign Access Levels to Org Ranks. For example, every General in your org can be given Leader access via the Security Access Level interface.

In addition to the security options provided by user levels and org ranks, the bot's superadmins are able to create custom security groups and add players to these groups. When a new security group is created, it is assigned the access level ANONYMOUS. Use the Security Access Level interface to raise and lower the access of a custom group.
Basic use the Security System in your modules


'''Commands'''

Each core or module commands have a default access level hardcoded & that is set for obvious security : the highest sensibility worth the highest level, indeed. Those access levels are recorded into your database on first bot launch. That means changing the code for different access level on a command after first launch will have no effect. To edit this you must therefore edit your database, specifically the table named botname_access_level ... which could be done by direct request if you're easy enough with SQL language, otherwise and more visually we advice you to install PHPMyAdmin on your server and connect to database that way.

You will therefore be able to easily overview various commands access levels, with subcommand and/or originating channel.
Simply click the value you want to change and select the new value in the proposed list as shown below :

http://wiki.bebot.link/images/access_level_php_admin.jpg

Once all is set as you want, simply restart your bot to see changes take effect.


'''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 must be assigned access levels.

For example, if your module's commands 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>!";
    else
        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 or leader, admin, superadmin, or owner all meet or exceed the leader requirement.

BeBot check's it's banlist on all incoming tell, pgroup, and gc commands. If you are taking input from other chat channels, you may want to have a ban check.

    if ($this -> bot -> security -> is_banned($name))
    {
        $this -> bot -> send_ban($name, "Sorry, you have been banned from <botname> and cannot use that command.");
    }
    else
    {
       // your code here.
    }

When you wish to send notification about a ban, you should always use BeBot's send_ban function. The send_ban function has built in spam control that will prevent a banned user from filling up your bot's tell queue with outgoing ban notifications.
Advanced use the Security System in your modules


'''Functions'''

The Security Module provides the following functions for modifying the roster and security groups.

* Add a group:

    add_group($groupname, $description);

* Delete a group:

    del_group($target);

* 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)

    get_gid($groupname)

Expert use the Security System in your modules

The cache_mgr($action, $cache, $info, $more) function is used to add and remove information from the security cache. The advanced functions above all use the cache_mgr function to update information. If you are modifying the security database or roster directly in your module (something that in general should not be done) you must use the cache_mgr function to update the security cache as appropriate or your database modifications will not take effect until the bot is restarted.

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");