Commit 162dbe97 authored by Ziirish's avatar Ziirish

update doc with the new ACL options

parent cd8b3efd
......@@ -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>`_
......
......@@ -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**
......
......@@ -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!
......@@ -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
------
......
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment