update doc with the new ACL options

CHANGELOG.rst

@@ -4,6 +4,7 @@ Changelog
 Current
 -------
 
+- **Breaking**: the *BASIC* `ACL` engine will now grant users on all agents if they are not explicitly defined
 - Add: new plugins system to allow users to write their own modules
 - Add: `support new burp counters <https://git.ziirish.me/ziirish/burp-ui/issues/219>`_
 - Add: `record login failure attempt <https://git.ziirish.me/ziirish/burp-ui/issues/214>`_

docs/advanced_usage.rst

@@ -458,7 +458,7 @@ Now you can add *ldap* specific options:
     # ldapauth specific options
     [LDAP]
     # Backend priority. Higher is first
-    priority = 1
+    priority = 50
     # LDAP host
     host = 127.0.0.1
     # LDAP port
@@ -522,7 +522,7 @@ Now you can add *basic* specific options:
     # is admin/admin
     [BASIC]
     # Backend priority. Higher is first
-    priority = 2
+    priority = 100
     admin = pbkdf2:sha1:1000$12345678$password
     user1 = pbkdf2:sha1:1000$87654321$otherpassword
 
@@ -557,7 +557,7 @@ Now you can add *local* specific options:
     # allow PAM to work
     [LOCAL]
     # Backend priority. Higher is first
-    priority = 3
+    priority = 0
     # List of local users allowed to login. If you don't set this setting, users
     # with uid greater than limit will be able to login
     users = user1,user2
@@ -605,15 +605,39 @@ Now you can add *basic acl* specific options:
     # access to all clients whereas other users will only see the client that have
     # the same name
     [BASIC:ACL]
+    # Backend priority. Higher is first
+    priority = 100
+    # Enable extended matching rules
+    # If the rule is a string like 'user1 = desk*', it will match any client that
+    # matches 'desk*' no mater what agent it is attached to.
+    # If it is a coma separated list of strings like 'user1 = desk*,laptop*' it
+    # will match the first matching rule no mater what agent it is attached to.
+    # If it is a dict like:
+    # user1 = '{"agents": ["srv*", "www*"], "clients": ["desk*", "laptop*"]}'
+    # It will also validate against the agent name.
+    extended = false
+    # Enable 'legacy' behavior
+    # Since v0.6.0, if you don't specify the agents name explicitly, users will be
+    # granted on every agents where a client matches user's ACL. If you enable the
+    # 'legacy' behavior, you will need to specify the agents explicitly.
+    # Note: enabling this option will also disable the extended mode
+    legacy = false
+    # List of administrators
     admin = user1,user2
+    # List of moderators. Users listed here will inherit the grants of the
+    # 'virtual' user 'moderator'
+    moderators = user5,user6
     # Please note the double-quotes and single-quotes on the following lines are
     # mandatory!
     # You can also overwrite the default behavior by specifying which clients a
     # user can access
+    moderator = '{"agents":{"ro":["agent1"]}}'
     user3 = '["client4", "client5"]'
     # In case you are not in a single mode, you can also specify which clients
     # a user can access on a specific Agent
     user4 = '{"agent1": ["client6", "client7"], "agent2": ["client8"]}'
+    # You can define read-only and/or read-write grants for moderators using:
+    user5 = '{"agents": ["www*"], "clients": {"ro": ["desk*"], "rw": ["desk1"]}}'
 
 
 .. warning:: The double-quotes and single-quotes are **MANDATORY**

docs/plugins.rst

@@ -2,7 +2,7 @@ Plugins
 =======
 
 Since *v0.6.0*, you can write your own external plugins.
-For now, only *authentication* plugins are supported.
+For now, only *authentication* and *acl* plugins are supported.
 
 Authentication
 --------------
@@ -20,6 +20,7 @@ Please refer to the `Auth API <auth.html>`_ page for more details.
 
     class UserHandler(interface.BUIhandler):
         name = 'CUSTOM'
+        priority = 1000
 
         def __init__(self, app):
             self.users = {
@@ -48,9 +49,13 @@ Please refer to the `Auth API <auth.html>`_ page for more details.
 
 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.
 
@@ -59,3 +64,74 @@ You can put this code in a file called *custom.py*, save this file in
 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 <acl.html>`_ page for more details.
+
+.. code-block:: python
+    :linenos:
+
+        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
+
+
+        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_allowed(self, username=None, client=None, server=None):
+                if not username:
+                    return False
+                return username == self.loader.admin
+
+            def is_server_allowed(self, username=None, client=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!

docs/upgrading.rst

@@ -7,6 +7,17 @@ Each section presents major/breaking changes, new requirements and new options.
 For a complete list of changes, you may refer to the
 `CHANGELOG <changelog.html>`_ page.
 
+v0.6.0
+------
+
+- **Breaking** - The *BASIC* `ACL` engine will now grant users on all agents if
+  they are not explicitly defined. It means that if you have a user called
+  `example1` with two agents (burp servers in multi-agent mode) on which you
+  have respectively two clients called `example1`, the user `example1` will be
+  granted on both clients on the two agents. You can disable this behavior with
+  the `legacy` option. See the `BASIC ACL <advanced_usage.html#basic-acl>`_
+  documentation for details.
+
 v0.5.0
 ------
 

share/burpui/etc/burpui.sample.cfg

@@ -155,7 +155,7 @@ noserverrestore = false
 ## ldapauth specific options
 #[LDAP]
 ## Backend priority. Higher is first
-#priority = 1
+#priority = 50
 ## LDAP host
 #host = 127.0.0.1
 ## LDAP port
@@ -197,7 +197,7 @@ noserverrestore = false
 ## is admin/admin
 #[BASIC]
 ## Backend priority. Higher is first
-#priority = 2
+#priority = 100
 #admin = password
 #user1 = otherpassword
 
@@ -206,27 +206,51 @@ noserverrestore = false
 ## allow PAM to work
 #[LOCAL]
 ## Backend priority. Higher is first
-#priority: 3
+#priority = 0
 ## List of local users allowed to login. If you don't set this setting, users
 ## with uid greater than limit will be able to login
-#users: user1,user2
+#users = user1,user2
 ## Minimum uid that will be allowed to login
-#limit: 1000
+#limit = 1000
 
 ## basicacl specific options
 ## Note: in case you leave this section commented, the user 'admin' will have
 ## access to all clients whereas other users will only see the client that have
 ## the same name
 #[BASIC:ACL]
+## Backend priority. Higher is first
+#priority = 100
+## Enable extended matching rules
+## If the rule is a string like 'user1 = desk*', it will match any client that
+## matches 'desk*' no mater what agent it is attached to.
+## If it is a coma separated list of strings like 'user1 = desk*,laptop*' it
+## will match the first matching rule no mater what agent it is attached to.
+## If it is a dict like:
+## user1 = '{"agents": ["srv*", "www*"], "clients": ["desk*", "laptop*"]}'
+## It will also validate against the agent name.
+#extended = false
+## Enable 'legacy' behavior
+## Since v0.6.0, if you don't specify the agents name explicitly, users will be
+## granted on every agents where a client matches user's ACL. If you enable the
+## 'legacy' behavior, you will need to specify the agents explicitly.
+## Note: enabling this option will also disable the extended mode
+#legacy = false
+## List of administrators
 #admin = user1,user2
+## List of moderators. Users listed here will inherit the grants of the
+## 'virtual' user 'moderator'
+#moderators = user5,user6
 ## Please note the double-quotes and single-quotes on the following lines are
 ## mandatory!
 ## You can also overwrite the default behavior by specifying which clients a
 ## user can access
+#moderator = '{"agents":{"ro":["agent1"]}}'
 #user3 = '["client4", "client5"]'
 ## In case you are not in a single mode, you can also specify which clients
 ## a user can access on a specific Agent
 #user4 = '{"agent2": ["client8"], "agent1": ["client6", "client7"]}'
+## You can define read-only and/or read-write grants for moderators using:
+#user5 = '{"agents": ["www*"], "clients": {"ro": ["desk*"], "rw": ["desk1"]}}'
 
 ## If you set single to 'false', add at least one section like this per
 ## bui-agent