Plugins¶
Since v0.6.0, you can write your own external plugins. For now, authentication, acl and audit 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:AUTH'
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.
Audit¶
# BUIaudit, BUIauditLogger as BUIauditLoggerInterface You will find here a fully working example of an external audit plugin. Please refer to the Audit 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 | from burpui.misc.audit import interface
import logging
__type__ = 'audit'
class BUIauditLoader(interface.BUIhandler):
name = 'CUSTOM:AUDIT'
priority = 1000
def __init__(self, app):
self.app = app
self.conf = app.conf
self.level = default = logging.getLevelName(self.app.logger.getEffectiveLevel())
if self.section in self.conf.options:
self.level = self.conf.safe_get(
'level',
section=self.section,
defaults=default
)
if self.level != default:
self.level = logging.getLevelName(f'{self.level}'.upper())
if not isinstance(self.level, int):
self.level = default
self._logger = BUIauditLogger(self)
class BUIauditLogger(interface.BUIauditLogger):
def __init__(self, loader):
self.loader = loader
self._level = self.loader.level
self.LOG_FORMAT = 'CUSTOM AUDIT LOG %(levelname)s in %(from)s: %(message)s'
def log(self, level, message, *args, **kwargs):
kwargs['levelname'] = level
kwargs['message'] = message % args if args else message
print(self.LOG_FORMAT % kwargs)
|
Line 1 is mandatory since you must implement the audit interface in order for your plugin to work.
Line 5 __type__ = 'audit'
defines a auth plugin.
Line 8 defines your auth backend name.
The rest of the code is just a minimal implementation of the audit interface.
You must define a self._logger
object that implements the
BUIauditLogger
interface (see line 28).
In our example, the BUIauditLogger
object is defined line 31.
This object must implement the log
method. This is the method that will
be called when the loglevel matches your minimal log level.