diff --git a/burpui/misc/audit/basic.py b/burpui/misc/audit/basic.py index 6b867b3a..771dccce 100644 --- a/burpui/misc/audit/basic.py +++ b/burpui/misc/audit/basic.py @@ -64,10 +64,6 @@ class BUIauditLoader(BUIaudit): self._logger = BUIauditLogger(self) - @property - def logger(self): - return self._logger - class BUIauditLogger(BUIauditLoggerInterface): _logger = parent_logger.getChild('audit') # type: logging.Logger diff --git a/burpui/misc/audit/handler.py b/burpui/misc/audit/handler.py index 4c877b74..e59f3615 100644 --- a/burpui/misc/audit/handler.py +++ b/burpui/misc/audit/handler.py @@ -57,10 +57,6 @@ class BUIauditLoader(BUIaudit): self.backends[obj.name] = obj self._logger = BUIauditLogger(self) - @property - def logger(self) -> BUIauditLoggerInterface: - return self._logger - class BUIauditLogger(BUIauditLoggerInterface): diff --git a/burpui/misc/audit/interface.py b/burpui/misc/audit/interface.py index 4bf01fa9..635f3764 100644 --- a/burpui/misc/audit/interface.py +++ b/burpui/misc/audit/interface.py @@ -12,29 +12,6 @@ import logging from abc import ABCMeta, abstractmethod, abstractproperty -class BUIaudit(object, metaclass=ABCMeta): - """The :class:`burpui.misc.audit.interface.BUIaudit` class defines the audit - interface. - - :param app: Instance of the app we are running in - :type app: :class:`burpui.engines.server.BUIServer` - """ - - priority = 0 - - name = None - _logger = None - - def __init__(self, app): - self.app = app - - @abstractproperty - @property - def logger(self): - """:rtype: class:`BUIauditLogger`""" - return self._logger - - class BUIauditLogger(object, metaclass=ABCMeta): """The :class:`burpui.misc.audit.interface.BUIauditLogger` class defines the audit Logger interface. @@ -73,3 +50,25 @@ class BUIauditLogger(object, metaclass=ABCMeta): @abstractmethod def log(self, level, message, *args, **kwargs): pass + + +class BUIaudit(object, metaclass=ABCMeta): + """The :class:`burpui.misc.audit.interface.BUIaudit` class defines the audit + interface. + + :param app: Instance of the app we are running in + :type app: :class:`burpui.engines.server.BUIServer` + """ + + priority = 0 + + name = None + _logger = None + + def __init__(self, app): + self.app = app + + @property + def logger(self) -> BUIauditLogger: + """:rtype: class:`BUIauditLogger`""" + return self._logger diff --git a/docs/acl.rst b/docs/acl.rst index 4bb1008b..0aab69cc 100644 --- a/docs/acl.rst +++ b/docs/acl.rst @@ -2,7 +2,7 @@ ACL === Here is the *acl* interface definition in order to implement a new acl backend. -It is composed by two classes. +It is composed by three classes. .. autoclass:: burpui.misc.acl.interface.BUIaclLoader :members: diff --git a/docs/audit.rst b/docs/audit.rst new file mode 100644 index 00000000..27dafbda --- /dev/null +++ b/docs/audit.rst @@ -0,0 +1,13 @@ +Audit +===== + +Here is the *audit* interface definition in order to implement a new acl backend. +It is composed by two classes. + +.. autoclass:: burpui.misc.audit.interface.BUIauditLogger + :members: + :inherited-members: + +.. autoclass:: burpui.misc.audit.interface.BUIaudit + :members: + :inherited-members: diff --git a/docs/developer.rst b/docs/developer.rst index 1004572e..648f6155 100644 --- a/docs/developer.rst +++ b/docs/developer.rst @@ -11,4 +11,5 @@ Developer Guide parser auth acl + audit plugins diff --git a/docs/plugins.rst b/docs/plugins.rst index 5d6977f5..51be946d 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -2,7 +2,7 @@ Plugins ======= Since *v0.6.0*, you can write your own external plugins. -For now, only *authentication* and *acl* plugins are supported. +For now, *authentication*, *acl* and *audit* plugins are supported. Authentication -------------- @@ -19,7 +19,7 @@ Please refer to the `Auth API `_ page for more details. __type__ = 'auth' class UserHandler(interface.BUIhandler): - name = 'CUSTOM' + name = 'CUSTOM:AUTH' priority = 1000 def __init__(self, app): @@ -224,3 +224,75 @@ 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. + +.. code-block:: python + :linenos: + + 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.