Plugins

Since v0.6.0, you can write your own external plugins. For now, only authentication and acl plugins are supported.

Authentication

You will find here a fully working example of an external authentication plugin. Please refer to the Auth API page for more details.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
from burpui.misc.auth import interface

__type__ = 'auth'

class UserHandler(interface.BUIhandler):
    name = 'CUSTOM'
    priority = 1000

    def __init__(self, app):
        self.users = {
            'toto': CustomUser('toto', 'toto'),
            'tata': CustomUser('tata', 'tata'),
            'titi': CustomUser('titi', 'titi'),
            'tutu': CustomUser('tutu', 'tutu'),
        }

    def user(self, name):
        return self.users.get(name, None)

    @property
    def loader(self):
        return self

class CustomUser(interface.BUIuser):
    def __init__(self, name, password):
        self.name = self.id = name
        self.password = password

    def login(self, passwd):
        self.authenticated = passwd == self.password
        return self.authenticated

Line 1 is mandatory since you must implement the auth interface in order for your plugin to work.

Line 3 __type__ = 'auth' defines a auth plugin.

Line 6 defines your auth backend name.

The rest of the code is just a minimal implementation of the auth interface.

This plugin defines four hardcoded users: toto, tata, titi, tutu with respectively the same passwords as their username.

You can put this code in a file called custom.py, save this file in /etc/burp/plugins for instance, and set plugins = /etc/burp/plugins. The plugin will be automatically loaded.

Note

This is just an example, do not run this particular plugin in production!

ACL

You will find here a fully working example of an external acl plugin. Please refer to the ACL API page for more details.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
    from burpui.misc.acl import interface

    __type__ = 'acl'

    class ACLloader(interface.BUIaclLoader):
        name = 'CUSTOM:ACL'
        priority = 1000

        def __init__(self, app):
            self.app = app
            self.admin = 'toto'
            self._acl = CustomACL(self)

        @property
        def acl(self):
            return self._acl

        @property
        def grants(self):
            return None

        @property
        def groups(self):
            return None

        def reload(self):
            """This method is used to reload the rules in case of config
            change for instance"""
            pass


    class CustomACL(interface.BUIacl):

        def __init__(self, loader):
            self.loader = loader

        def is_admin(self, username=None):
            if not username:
                return False
            return username == self.loader.admin

        def is_moderator(self, username=None):
            if not username:
                return False
            return username == self.loader.admin

        def is_client_rw(self, username=None, client=None, server=None):
            if not username:
                return False
            return username == self.loader.admin

        def is_client_allowed(self, username=None, client=None, server=None):
            if not username:
                return False
            return username == self.loader.admin

        def is_server_rw(self, username=None, server=None):
            if not username:
                return False
            return username == self.loader.admin

        def is_server_allowed(self, username=None, server=None):
            if not username:
                return False
            return username == self.loader.admin

Line 1 is mandatory since you must implement the acl interface in order for your plugin to work.

Line 3 __type__ = 'acl' defines a acl plugin.

Line 6 defines your acl backend name.

The rest of the code is just a minimal implementation of the acl interface.

This plugin defines a hardcoded admin user: toto which will be granted admin rights through the whole application.

You can put this code in a file called custom_acl.py, save this file in /etc/burp/plugins for instance, and set plugins = /etc/burp/plugins. The plugin will be automatically loaded.

Note

This is just an example, do not run this particular plugin in production!

ACL engine has built-in Groups support, to take full advantage of this feature, it is recommended to use the meta_grants object as shown bellow:

Note

The grant syntax is explained in the ACL documentation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
    from burpui.misc.acl.meta import meta_grants
    from burpui.misc.acl import interface

    from six import iteritems

    __type__ = 'acl'

    class ACLloader(interface.BUIaclLoader):
        name = 'CUSTOM2:ACL'
        priority = 1001

        _groups = {
            'gp1': {
                'grants': '["server1", "server2"]',  # this needs to be a string
                'members': ['user1'],
            },
        }

        def __init__(self, app):
            self.app = app
            self.admin = 'toto'
            self.init_rules()
            self._acl = meta_grants
            # We need to register our backend in order to be notified of
            # configuration changes in other registered backends.
            # This will then call our 'reload' function in order to re-apply
            # our grants.
            meta_grants.register_backend(self.name, self)

        def init_rules(self):
            for gname, content in iteritems(self._groups):
                meta_grants.set_group(gname, content['members'])
                meta_grants.set_grant(gname, content['grants'])

        @property
        def acl(self):
            return self._acl

        @property
        def grants(self):
            return self.acl.grants

        @property
        def groups(self):
            return self._groups

        def reload(self):
            """This method is used to reload the rules in case of config
            change for instance"""
            self.init_rules()

You can omit either the meta_grants.set_grant or the meta_grants.set_group part if you like. For instance to define the grants of a given group using another ACL backend, and using your plugin to manage groups membership only.