github-starred/burp-ui
2
0
Fork 0
mirror of https://github.com/ziirish/burp-ui.git synced 2026-05-15 06:05:58 -06:00
Code Issues 1 Projects Packages Wiki Activity Actions

rework documentation

Browse source
This commit is contained in:
ziirish 2019-07-16 19:15:38 +02:00
parent 82ee1e123d
commit 02321bee1f
No known key found for this signature in database
GPG key ID: 72DB229A64B54E46
17 changed files with 189 additions and 364 deletions
Download patch file Download diff file Expand all files Collapse all files

2
burpui/app.py
View file

@ -340,7 +340,7 @@ def create_app(conf=None, verbose=0, logfile=None, **kwargs):
app.login_manager.init_app(app)
# Create WebSocket server
if create_websocket(app, websocket_server, celery_worker, gunicorn, cli):
if create_websocket(app, websocket_server, celery_worker, cli):
return app
# Create celery app if enabled

7
burpui/cli.py
View file

@ -89,9 +89,7 @@ def _die(error, appli=None):
sys.exit(2)
def _log(message, *args, **kwargs):
color = kwargs.get('color', None)
err = kwargs.get('err', False)
def _log(message, *args, color=None, err=False):
msg = message % args if args else message
if color is not None:
msg = click.style(msg, fg=color)
@ -114,8 +112,7 @@ def warn(message='', *args):
_log(message, *args, color='yellow')
def err(message='', *args, **kwargs):
err = kwargs.get('err', True)
def err(message='', *args, err=True):
_log(message, *args, color='red', err=err)

4
burpui/extensions.py
View file

@ -193,8 +193,7 @@ def create_db(myapp, cli=False, unittest=False, create=True, celery_worker=False
return None
def create_websocket(myapp, websocket_server=False, celery_worker=False,
gunicorn=False, cli=False):
def create_websocket(myapp, websocket_server=False, celery_worker=False, cli=False):
"""Create the websocket server if possible
:param myapp: Application context
@ -234,7 +233,6 @@ def create_websocket(myapp, websocket_server=False, celery_worker=False,
myapp.config['WS_MANAGE_SESSION'] = not myapp.config.get('WITH_SRV_SESSION', False)
if os.getenv('BUI_MODE', '') == 'celery':
myapp.config['WS_ASYNC_MODE'] = 'threading'
# myapp.config['WS_ASYNC_MODE'] = 'threading' if not gunicorn else None
if celery_worker:
return False

87
contrib/debian/bui-celery.init
View file

@ -1,87 +0,0 @@
#!/bin/sh
### BEGIN INIT INFO
# Provides: bui-celery
# Required-Start: $network $local_fs $remote_fs
# Required-Stop: $network $local_fs $remote_fs
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Burp-UI Celery worker
# Description: Burp UI Celery worker to manage background jobs
### END INIT INFO
DAEMON=/usr/local/bin/bui-celery
DESC=bui-celery
NAME=bui-celery
DUSER=burpui
DGROUP=burpui
PIDFILE=/var/run/bui-celery.pid
# Exit if the package is not installed
[ -x $DAEMON ] || exit 0
# Load the VERBOSE setting and other rcS variables
. /lib/init/vars.sh
# Function that starts the daemon/service
do_start()
{
# Return
# 0 if daemon has been started
# 1 if daemon was already running
# 2 if daemon could not be started
start-stop-daemon --start --quiet --pidfile $PIDFILE --chuid $DUSER:$DGROUP --exec $DAEMON --test > /dev/null \
|| return 1
start-stop-daemon --start --quiet --pidfile $PIDFILE --chuid $DUSER:$DGROUP --make-pidfile --background --exec $DAEMON -- \
|| return 2
}
# Function that stops the daemon/service
do_stop()
{
# Return
# 0 if daemon has been stopped
# 1 if daemon was already stopped
# 2 if daemon could not be stopped
# other if a failure occurred
start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 --pidfile $PIDFILE --name $NAME
RETVAL="$?"
[ "$RETVAL" = 2 ] && return 2
#
start-stop-daemon --stop --quiet --oknodo --retry=0/30/KILL/5 --exec $DAEMON
[ "$?" = 2 ] && return 2
# Many daemons don't delete their pidfiles when they exit.
rm -f $PIDFILE
return "$RETVAL"
}
case "$1" in
start)
[ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC "
do_start
case "$?" in
0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
esac
;;
stop)
[ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC"
do_stop
case "$?" in
0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
esac
;;
restart)
do_stop
do_start
;;
*)
echo "Usage: $SCRIPTNAME {start|stop|restart}" >&2
exit 3
;;
esac
:

85
contrib/debian/init.sh
View file

@ -1,85 +0,0 @@
#!/bin/sh
### BEGIN INIT INFO
# Provides: burp-ui
# Required-Start: $network $local_fs $remote_fs
# Required-Stop: $network $local_fs $remote_fs
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: User interface for burp backup
# Description: Burp UI work with burp backup and restore.
### END INIT INFO
DAEMON=/usr/local/bin/burp-ui
DESC=burp-ui
NAME=burp-ui
PIDFILE=/var/run/burp-ui.server.pid
# Exit if the package is not installed
[ -x $DAEMON ] || exit 0
# Load the VERBOSE setting and other rcS variables
. /lib/init/vars.sh
# Function that starts the daemon/service
do_start()
{
# Return
# 0 if daemon has been started
# 1 if daemon was already running
# 2 if daemon could not be started
start-stop-daemon --start --quiet --pidfile $PIDFILE --exec $DAEMON --test > /dev/null \
|| return 1
start-stop-daemon --start --quiet --pidfile $PIDFILE --make-pidfile --background --exec $DAEMON -- \
|| return 2
}
# Function that stops the daemon/service
do_stop()
{
# Return
# 0 if daemon has been stopped
# 1 if daemon was already stopped
# 2 if daemon could not be stopped
# other if a failure occurred
start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 --pidfile $PIDFILE --name $NAME
RETVAL="$?"
[ "$RETVAL" = 2 ] && return 2
#
start-stop-daemon --stop --quiet --oknodo --retry=0/30/KILL/5 --exec $DAEMON
[ "$?" = 2 ] && return 2
# Many daemons don't delete their pidfiles when they exit.
rm -f $PIDFILE
return "$RETVAL"
}
case "$1" in
start)
[ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC "
do_start
case "$?" in
0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
esac
;;
stop)
[ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC"
do_stop
case "$?" in
0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
esac
;;
restart)
do_stop
do_start
;;
*)
echo "Usage: $SCRIPTNAME {start|stop|restart}" >&2
exit 3
;;
esac
:

15
contrib/gunicorn.d/burp-ui
View file

@ -1,15 +0,0 @@
CONFIG = {
'working_dir': '/',
'args': (
# '--preload',
'--bind=0.0.0.0:5000',
'--user=burpui',
'--group=burpui',
'--workers=5',
'--timeout=300',
'--worker-class=eventlet',
'--access-logfile=/var/log/gunicorn/burp-ui_access.log',
'--error-logfile=/var/log/gunicorn/burp-ui_error.log',
'burpui:create_app(conf="/etc/burp/burpui.cfg",logfile="/var/log/gunicorn/burp-ui_info.log")',
),
}

2
contrib/gunicorn/burpui_gunicorn.py
View file

@ -77,7 +77,7 @@ backlog = 2048
# 'geventwebsocket.gunicorn.workers.GeventWebSocketWorker'
workers = 5
worker_class = 'gevent'
worker_class = 'sync'
worker_connections = 1000
timeout = 300
keepalive = 2

13
contrib/systemd/bui-celery-beat.service Normal file
View file

@ -0,0 +1,13 @@
[Unit]
Description=Burp-UI celery service
After=network.target
[Service]
User=burpui
Group=burpui
RuntimeDirectory=bui-celery
RuntimeDirectoryMode=0770
ExecStart=/usr/bin/bui-celery -c /etc/burp/burpui.cfg -t beat --pidfile=/var/run/bui-celery/bui-celery.pid -s /var/lib/burpui/celerybeat-schedule
[Install]
WantedBy=multi-user.target

4
contrib/systemd/bui-celery.service
View file

@ -5,9 +5,7 @@ After=network.target
[Service]
User=burpui
Group=burpui
RuntimeDirectory=bui-celery
RuntimeDirectoryMode=0770
ExecStart=/usr/bin/bui-celery -c /etc/burp/burpui.cfg --pidfile=/var/run/bui-celery/bui-celery.pid --beat -s /var/lib/burpui/celerybeat-schedule
ExecStart=/usr/bin/bui-celery -c /etc/burp/burpui.cfg
[Install]
WantedBy=multi-user.target

1
docker/docker-alpine/assets/setup/install
View file

@ -31,7 +31,6 @@ pip install mysqlclient
pip install psycopg2
pip install psycogreen
pip install flask-limiter
pip install Flask-Session
pip install Flask-SQLAlchemy
pip install Flask-Migrate
pip install sqlalchemy-utils

1
docs/index.rst
View file

@ -19,7 +19,6 @@ Documentation
:maxdepth: 2
introduction
requirements
architecture
installation
basic_usage

155
docs/introduction.rst
View file

@ -30,9 +30,9 @@ Compatibility
+----------------------------+-------+-------+
| 2.0.0 => 2.0.16 | | |
+----------------------------+-------+-------+
| 2.0.18 => 2.0.X protocol 1 | | X |
| 2.0.18 => 2.3.X protocol 1 | | X |
+----------------------------+-------+-------+
| 2.0.18 => 2.0.X protocol 2 | | X* |
| 2.0.18 => 2.3.X protocol 2 | | X* |
+----------------------------+-------+-------+
\* The protocol 2 is in heavy development Burp side so the support in
@ -48,5 +48,156 @@ issues in the `bug-tracker <https://git.ziirish.me/ziirish/burp-ui/issues>`_.
You will also find there the current opened issues.
Requirements
------------
Please note that, `Burp-UI`_ must be running on the same server that runs the
burp-server for some features.
.. note::
At the moment, `Burp-UI`_ and this doc is mostly debian-centric but feel
free to contribute for other distributions!
Python
^^^^^^
`Burp-UI`_ is built against python 3.6. The support for python <=3.5 has been
removed since `v0.7.0 <upgrading.html#v0-7-0>`__. Python 2.7 is about to be EOL
and won't be supported anymore by the CPython core team by the end of 2019.
Unit tests are ran against python 3.6 and python 3.7. If you encounter
compilation errors with one of these version, feel free to report them.
Libraries
^^^^^^^^^
Some libraries are required to be able to compile some requirements:
::
apt-get install libffi-dev libssl-dev python-dev python-pip
LDAP
^^^^
For `LDAP authentication <advanced_usage.html#ldap>`__ (optional), we need extra
dependencies. You can install them using the following command:
::
pip install "burp-ui[ldap_authentication]"
Redis
^^^^^
If you wish to use redis for Caching and/or managing user sessions, you need
additional dependencies:
::
pip install "burp-ui[gunicorn-extra]"
Redis is also a required dependency if you want to use `celery <celery.html>`__.
Celery
^^^^^^
The `celery <celery.html>`__ worker also needs additional dependencies that you
can install using:
::
pip install "burp-ui[celery]"
SQL
^^^
If you need persistent data, you will need additional dependencies as well:
::
pip install "burp-ui[sql]"
Now if you want to use a MySQL database, you will need the proper driver. For
instance:
::
pip install mysqlclient
.. warning:: The MySQL driver does not seem to play nicely with concurrency, you
should set ``preload=False`` within your gunicorn config.
To use a PostgreSQL database, you need the ``psycopg2`` driver:
::
pip install psycopg2
.. warning:: The PostgreSQL driver does not seem to play nicely with
concurrency, you should set ``preload=False`` within your gunicorn
config.
Limiter
^^^^^^^
If you want to `rate-limit <advanced_usage.html#production>`__ the API, you will
need additional dependencies too:
::
pip install flask-limiter
WebSocket
^^^^^^^^^
If you want to enable the `WebSockets <websocket.html>`__ support, you need to
install the following:
::
pip install "burp-ui[websocket]"
Burp1
-----
The `burp1 backend <advanced_usage.html#burp1>`__ supports burp versions from
1.3.48 to 1.4.40.
With these versions of burp, the status port is only listening on the local
machine loopback interface (ie. ``localhost`` or ``127.0.0.1``). It means you
*MUST* run `Burp-UI`_ on the same host that is running your burp server in order
to be able to access burp's statistics.
Alternatively, you can use a `bui-agent <buiagent.html>`__.
Burp2
-----
The `burp2 backend <advanced_usage.html#burp2>`__ supports only burp 2.0.18 and
above.
Some versions are known to contain critical issues resulting in a non-functional
`Burp-UI`_: 2.0.24, 2.0.26 and 2.0.30
If you are using an older version of burp2 `Burp-UI`_ will fail to start.
Getting started
---------------
The first thing to do before digging into `Burp-UI`_ is probably to read its
`architecture <architecture.html>`_ in order to understand how it works.
Once it's done, you can refer to the `installation <installation.html>`_ page.
.. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui
.. _Burp: http://burp.grke.org/
.. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui

145
docs/requirements.rst
View file

@ -1,145 +0,0 @@
Requirements
============
Please note that, `Burp-UI`_ must be running on the same server that runs the
burp-server for some features.
.. note::
At the moment, `Burp-UI`_ and this doc is mostly debian-centric but feel
free to contribute for other distributions!
Python
------
`Burp-UI`_ is built against python 2.7. The support for python 2.6 has been
removed since it is not supported anymore by the CPython core team.
Unit tests are ran against python 2.7 and python 3.6. If you encounter
compilation errors with one of these version, feel free to report them.
Libraries
---------
Some libraries are required to be able to compile some requirements:
::
apt-get install libffi-dev libssl-dev python-dev python-pip
LDAP
----
For LDAP authentication (optional), we need extra dependencies. You can install
them using the following command:
::
pip install "burp-ui[ldap_authentication]"
Redis
-----
If you wish to use redis for Caching and/or managing user sessions, you need
additional dependencies:
::
pip install "burp-ui[gunicorn-extra]"
Celery
------
The celery worker also needs additional dependencies that you can install using:
::
pip install "burp-ui[celery]"
SQL
---
If you need persistent data, you will need additional dependencies as well:
::
pip install "burp-ui[sql]"
Now if you want to use a MySQL database, you will need the proper driver. For
instance:
::
pip install mysqlclient
.. warning:: The MySQL driver does not seem to play nicely with concurrency, you
should set ``preload=False`` within your gunicorn config.
To use a PostgreSQL database, you need the ``psycopg2`` driver:
::
pip install psycopg2
.. warning:: The PostgreSQL driver does not seem to play nicely with
concurrency, you should set ``preload=False`` within your gunicorn
config.
Limiter
-------
If you want to rate-limit the API, you will need additional dependencies too:
::
pip install flask-limiter
WebSocket
---------
If you want to enable the WebSockets support, you need to install the following:
::
pip install "burp-ui[websocket]"
Burp1
-----
The `burp1 backend <advanced_usage.html#burp1>`__ supports burp versions from
1.3.48 to 1.4.40.
With these versions of burp, the status port is only listening on the local
machine loopback interface (ie. ``localhost`` or ``127.0.0.1``). It means you
*MUST* run `Burp-UI`_ on the same host that is running your burp server in order
to be able to access burp's statistics.
Alternatively, you can use a `bui-agent <buiagent.html>`__.
Burp2
-----
The `burp2 backend <advanced_usage.html#burp2>`__ supports only burp 2.0.18 and
above.
Some versions are known to contain critical issues resulting in a non-functional
`Burp-UI`_: 2.0.24, 2.0.26 and 2.0.30
If you are using an older version of burp2 `Burp-UI`_ will fail to start.
Getting started
---------------
The first thing to do before digging into `Burp-UI`_ is probably to read its
`architecture <architecture.html>`_ in order to understand how it works.
Once it's done, you can refer to the `installation <installation.html>`_ page.
.. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui

22
docs/step-by-step.rst
View file

@ -119,14 +119,11 @@ Our `Burp`_ server is now set up, we can start it:
/etc/init.d/burp start
Now we can configure `Burp-UI`_. The package comes with a default configuration
and init scripts. We copy them at the right place:
Now we can configure `Burp-UI`_. The package comes with a default configuration.
We copy it at the right place:
::
cp /usr/local/share/burpui/contrib/debian/init.sh /etc/init.d/burp-ui
chmod +x /etc/init.d/burp-ui
update-rc.d burp-ui defaults
cp /usr/local/share/burpui/etc/burpui.sample.cfg /etc/burp/burpui.cfg
@ -135,7 +132,7 @@ server:
::
sed -i "s/^version = .*/version = 1/" /etc/burp/burpui.cfg
sed -i "s/^backend = .*/backend = burp1/" /etc/burp/burpui.cfg
The default configuration is plug and play for this case, we just have to start
@ -143,7 +140,7 @@ The default configuration is plug and play for this case, we just have to start
::
/etc/init.d/burp-ui start
burp-ui -- -h 0.0.0.0 -p 5000
Your server is now fully set-up, you can access `Burp-UI`_ by pointing your
@ -184,7 +181,7 @@ Now we retrieve the `Burp`_ sources and then we compile and install it:
cd /usr/src
git clone https://github.com/grke/burp.git
cd burp
git checkout tags/2.0.54
git checkout tags/2.2.18
./configure --prefix=/usr --sysconfdir=/etc/burp --localstatedir=/var
make
make install
@ -263,14 +260,11 @@ Our `Burp`_ server is now set up, we can start it:
/etc/init.d/burp start
Now we can configure `Burp-UI`_. The package comes with a default configuration
and init scripts. We copy them at the right place:
Now we can configure `Burp-UI`_. The package comes with a default configuration.
We copy it at the right place:
::
cp /usr/local/share/burpui/contrib/debian/init.sh /etc/init.d/burp-ui
chmod +x /etc/init.d/burp-ui
update-rc.d burp-ui defaults
cp /usr/local/share/burpui/etc/burpui.sample.cfg /etc/burp/burpui.cfg
@ -279,7 +273,7 @@ We can start `Burp-UI`_:
::
/etc/init.d/burp-ui start
burp-ui -- -h 0.0.0.0 -p 5000
Your server is now fully set-up, you can access `Burp-UI`_ by pointing your

7
docs/upgrading.rst
View file

@ -13,10 +13,14 @@ For a complete list of changes, you may refer to the
v0.7.0
------
- **Breaking** - you now need python 3.6 or above. `Burp-UI`_ won't work on
python 2.7 anymore.
- **Breaking** - the *single* and *version* options within the ``[Global]``
section have been removed in favor of a new unified *backend* option. See the
`Backends <advanced_usage.html#backends>`__ section of the documentation for
details.
- **Breaking** - there was a bug when using burp-server >= 2.1.10 where
timestamps where wrongly computed on the global clients view due to the fact
timestamps have offsets since burp-server 2.1.10. The new behaviour is to
@ -27,15 +31,18 @@ v0.7.0
`Backend options <advanced_usage.html#options>`__ for details).
The drawback of enabling the ``deep_inspection`` is this requires some extra
work that may slow down burp-ui.
- **Breaking** - the authentication backends section have been renamed with the
``:AUTH`` suffix (so ``BASIC`` becomes ``BASIC:AUTH``, etc.).
Please make sure you rename those sections accordingly so you won't be locked
out.
- **Breaking** - the ``bui-agent`` will now exit when its *system* requirements
are not met at startup time (that is: the burp-server must be up and running
and the burp-client used by burp-ui must be able to reach the burp-server).
A new timeout has been added though in order for ``bui-agent`` to wait for the
burp-server to be ready.
- **Breaking** - the ``prefix`` option has been moved from the ``[Global]``
configuration section to the ``[Production]`` one for consistency with the new
*Production* options introduced.

1
requirements.txt
View file

@ -6,6 +6,7 @@ Flask-Babel==0.12.2
Flask-WTF==0.14.2
flask-restplus==0.12.1
Flask-Caching==1.7.2
Flask-Session==0.3.1
WTForms==2.1
arrow==0.14.2
pluginbase==1.0.0

2
setup.py
View file

@ -306,7 +306,7 @@ setup(
extras_require={
'ldap_authentication': ['ldap3'],
'gunicorn': ['gunicorn'],
'gunicorn-extra': ['redis', 'Flask-Session==0.3.1'],
'gunicorn-extra': ['redis'],
'ci': test_requires,
'dev': dev_requires,
'celery': ['Celery>=4.3', 'redis'],