bui-monitor

The bui-monitor is a Burp client monitor processes pool.

This pool only supports the burp2 backend.

The goal of this pool is to have a consistent amount of burp client processes related to your Burp-UI stack.

Before this pool, you could have 1 process per Burp-UI instance (so if you use gunicorn with several workers, that would multiply the amount of processes), you also had 1 process per celery worker instance (which is one per CPU core available on your machine by default). In the end, it could be difficult to anticipate the resources to provision beforehand. Also, this wasn’t very scalable.

If you choose to use the bui-monitor pool with the appropriate backend (the parallel one), you can now take advantage of some requests parallelisation.

Cherry on the cake, the parallel backend is available within both the local Burp-UI process but also within the bui-agent!

Architecture

The architecture is described bellow:

+---------------------+
|                     |
|     celery          |
|                     |
+---------------------+
| +-----------------+ |                                 +----------------------+
| |                 | |                                 |                      |
| |  worker 1       +----------------+------------------>     bui-monitor      |
| |                 | |              |                  |                      |
| +-----------------+ |              |                  +----------------------+
| +-----------------+ |              |                  | +------------------+ |
| |                 | |              |                  | |                  | |
| |  worker n       +----------------+                  | | burp -a m   (1)  | |
| |                 | |              |                  | |                  | |
| +-----------------+ |              |                  | +------------------+ |
+---------------------+              |                  | +------------------+ |
                                     |                  | |                  | |
+---------------------+              |                  | | burp -a m   (2)  | |
|                     |              |                  | |                  | |
|     burp-ui         |              |                  | +------------------+ |
|                     |              |                  | +------------------+ |
+---------------------+              |                  | |                  | |
| +-----------------+ |              |                  | | burp -a m   (n)  | |
| |                 | |              |                  | |                  | |
| |  worker 1       +----------------+                  | +------------------+ |
| |                 | |              |                  +----------------------+
| +-----------------+ |              |
| +-----------------+ |              |
| |                 | |              |
| |  worker n       +----------------+
| |                 | |
| +-----------------+ |
+---------------------+

Requirements

The monitor pool is powered by asyncio through trio. It is part of the Burp-UI package. You can launch it with the bui-monitor command.

Configuration

There is a specific buimonitor.cfg configuration file with a [Global] section as below:

# Burp-UI monitor configuration file
[Global]
# On which port is the application listening
port = 11111
# On which address is the application listening
# '::1' is the default for local IPv6
# set it to '127.0.0.1' if you want to listen on local IPv4 address
bind = ::1
# Pool size: number of 'burp -a m' process to load
pool = 2
# enable SSL
ssl = true
# ssl cert
sslcert = /var/lib/burp/ssl/server/ssl_cert-server.pem
# ssl key
sslkey = /var/lib/burp/ssl/server/ssl_cert-server.key
# monitor password
password = password123456

## burp backend specific options
#[Burp]
## burp binary
#burpbin = /usr/sbin/burp
## burp client configuration file used for the restoration
#bconfcli = /etc/burp/burp.conf
## how many time to wait for the monitor to answer (in seconds)
#timeout = 15

Each option is commented, but here is a more detailed documentation:

  • port: On which port is bui-monitor listening.
  • bind: On which address is bui-monitor listening.
  • pool: Number of burp client processes to launch.
  • ssl: Whether to communicate with the Burp-UI server over SSL or not.
  • sslcert: What SSL certificate to use when SSL is enabled.
  • sslkey: What SSL key to use when SSL is enabled.
  • password: The shared secret between the Burp-UI server and bui-monitor.

As with Burp-UI, you need the [Burp] section to specify Burp client options. There are fewer options because we only launch client processes.

Warning

Please note there seem to be an issue Burp side when you request concurrently too much status monitor processes. I’ll tend to say the pool size should not exeed the number of CPU cores available on your machine.

Benchmark

On my development VM which has 2 vCPUs I noticed the parallel backend which interacts with the bui-monitor was twice faster than the burp2 backend.

The test script was something like:

#!/bin/bash

for client in client1 client2 client3 client4 client6 client6
do
    echo "----------------------------$client--------------------------"
    (time curl -u user:password burp-ui.server:5000/api/client/stats/$client) &
    (time curl -u user:password burp-ui.server:5000/api/client/stats/$client) &
done

The server was launched with gunicorn:

# for the parallel backend
gunicorn -b 0.0.0.0:5000 -w 2 'burpui:create_app(conf="path/to/burpui.cfg")'
# for the burp2 backend
gunicorn -k gevent -b 0.0.0.0:5000 -w 2 'burpui:create_app(conf="path/to/burpui.cfg")'

Note

The parallel backend is not compatible with gevent hence the different launching command.

Here are the results:

# with burp2 backend
bash /tmp/bench.sh  0.10s user 0.06s system 0% cpu 20.377 total
bash /tmp/bench.sh  0.11s user 0.04s system 0% cpu 21.447 total
# with parallel backend
bash /tmp/bench.sh  0.12s user 0.04s system 1% cpu 10.267 total
bash /tmp/bench.sh  0.11s user 0.05s system 1% cpu 9.735 total

My feeling is, the more you have CPU cores, the more performance improvements you’ll notice over the burp2 backend because we let the kernel handle the I/O parallelization with the parallel backend and bui-monitor.

Service

I have no plan to implement daemon features, but there are a lot of tools available to help you achieve such a behavior.

To run bui-monitor as a service, a systemd file is provided. You can use it like this:

cp /usr/local/share/burpui/contrib/systemd/bui-monitor.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable bui-monitor.service
systemctl start bui-monitor.service