Gunicorn¶

Starting from v0.0.6, Burp-UI supports Gunicorn in order to handle multiple users simultaneously because some operations (like the online restoration) may take some time and thus may block any further requests. With Gunicorn, you have several workers that can proceed the requests so you can handle more users.

You need to install gunicorn:

pip install "burp-ui[gunicorn]"

Gunicorn is an application server that will work similarly to php-fpm and the like. That is, it will fork several processes to handle the load. Due to this, you may need to enable advanced Burp-UI features so those processes can talk to each other (and share resources). Here is what settings can be changed in the configuration as an illustration:

[Production]
# storage backend for session and cache
# may be either 'default' or 'redis'
storage = redis
# redis server to connect to
redis = localhost:6379
# session database to use
# may also be a backend url like: redis://localhost:6379/0
# if set to 'redis', the backend url defaults to:
# redis://<redis_host>:<redis_port>/0
# where <redis_host> is the host part, and <redis_port> is the port part of
# the below "redis" setting
session = redis
# cache database to use
# may also be a backend url like: redis://localhost:6379/0
# if set to 'redis', the backend url defaults to:
# redis://<redis_host>:<redis_port>/1
# where <redis_host> is the host part, and <redis_port> is the port part of
# the below "redis" setting
cache = redis

You will then be able to launch Burp-UI this way:

gunicorn -w 4 'burpui:create_app(conf="/path/to/burpui.cfg")'

Note

If you decide to use gunicorn AND the embedded websocket server, you’ll need to use the geventwebsocket.gunicorn.workers.GeventWebSocketWorker worker name (ie. -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker). For this worker to be available, you need to install the gevent-websocket pip package.

This will listen to 127.0.0.1:8000 by default. See the gunicorn documentation for details.

You will need to add the -b 0.0.0.0:5000 option in order to listen on all interfaces on port 5000 for instance.

When using gunicorn, the command line options are not available. Instead, you run the Burp-UI create_app method directly. Here are the parameters you can play with:

conf: Path to the Burp-UI configuration file
verbose: Verbosity level between 0 and 4
logfile: Path to a logfile in order to log Burp-UI internal messages
reverse_proxy: Whether we are behind a reverse-proxy or not (defaults to True)

Warning

You MUST set the appsecret option in your configuration file when using gunicorn. The default magic value ‘random’ cannot be used. If you don’t change the settings the default value will be ‘none’ and your cookies won’t be secured.

Advanced usage¶

Gunicorn supports further settings (see its documentation for details). For instance, you would probably like to use the -c flag with the sample configuration file bundled with Burp-UI in contrib/gunicorn/burpui_gunicorn.py.

Usage example:

gunicorn -c burpui_gunicorn.py 'burpui:create_app(conf="/etc/burp/burpui.cfg",logfile="/var/log/gunicorn/burp-ui_info.log")'

Daemon¶

If you wish to run Burp-UI as a daemon process, the recommended way is to use Gunicorn.

Requirements¶

First of all, you’ll need a dedicated user.

# create the burpui user
useradd -m -r -d /var/lib/burpui -c 'Burp-UI daemon user' burpui
mkdir /etc/burp
# copy the burp-ui sample configuration file
cp /usr/local/share/burpui/etc/burpui.sample.cfg /etc/burp/burpui.cfg
mkdir -p /var/log/gunicorn
chown -R burpui: /var/log/gunicorn

You will also need a custom client configuration and you will have to create the certificates accordingly:

# create the configuration file used by burp-ui
cat >/var/lib/burpui/burp.conf<<EOF
mode = client
port = 4971
status_port = 4972
server = 127.0.0.1
password = abcdefgh
cname = bui-agent1
pidfile = /var/lib/burpui/bui-agent1.client.pid
syslog = 0
stdout = 1
progress_counter = 1
ca_burp_ca = /usr/sbin/burp_ca
ca_csr_dir = /var/lib/burpui/CA-client
ssl_cert_ca = /var/lib/burpui/ssl_cert_ca-client.pem
ssl_cert = /var/lib/burpui/ssl_cert-client.pem
ssl_key = /var/lib/burpui/ssl_cert-client.key
ssl_peer_cn = burpserver
EOF
# generate the certificates
burp_ca --name bui-agent1 --ca burpCA --key --request --sign --batch
cp /etc/burp/ssl_cert_ca.pem /var/lib/burpui/ssl_cert_ca-client.pem
cp -a /etc/burp/CA/bui-agent1.crt /var/lib/burpui/ssl_cert-client.pem
cp -a /etc/burp/CA/bui-agent1.key /var/lib/burpui/ssl_cert-client.key
chown -R burpui: /var/lib/burpui/

Now you need to add the bui-agent1 client to the authorized clients:

echo "password = abcdefgh" >/etc/burp/clientconfdir/bui-agent1
echo "restore_client = bui-agent1" >>/etc/burp/burp-server.conf

You will also need to increase the number of status clients by setting max_status_children to 15:

echo "max_status_children = 15" >>/etc/burp/burp-server.conf

Finally, make sure you set bconfcli: /var/lib/burpui/burp.conf in your Burp-UI configuration file (/etc/burp/burpui.cfg).

If you want to take advantage of advanced features such as client add/removal and configuration files edition, you should set the permissions accordingly Burp-side.

First of all, add the following lines in your /etc/burp/burp-server.conf:

user = burpui
group = burpui

Then you need to fix some permissions:

chown -R burpui: /etc/burp/{burp-server.conf,burpui.cfg,CA,CA.cnf,clientconfdir,dhfile.pem,ssl_cert_ca.pem,ssl_cert-server.key,ssl_cert-server.pem} /var/spool/burp
chgrp burpui /etc/burp
chmod g+rwx /etc/burp

Finally you can restart your burp-server.

Note

The above commands are meant for default setup. You may need to adapt the paths.

Systemd¶

You will have to create your own service. We can do this for systemd for example:

# copy the gunicorn configuration file
cp /usr/local/share/contrib/gunicorn/burpui_gunicorn.py /etc/burp/
# create the service file
cat >/etc/systemd/service/bui-gunicorn.service<<EOF
[Unit]
Description=Burp-UI gunicorn service
After=network.target

[Service]
User=burpui
Group=burpui
ExecStart=/usr/local/bin/gunicorn -c /etc/burp/burpui_gunicorn.py 'burpui:create_app(conf="/etc/burp/burpui.cfg",logfile="/var/log/gunicorn/burp-ui_info.log")'

[Install]
WantedBy=multi-user.target
EOF
# enable the new service
systemctl enable bui-gunicorn.service
# start the service
systemctl start bui-gunicorn.service

Reverse-Proxy¶

You may want to add a reverse-proxy so Burp-UI can be accessed on port 80 (or 443) along with other applications.

Here is a sample configuration for Nginx:

server {
    listen 80;
    server_name burpui.example.com;

    access_log  /var/log/nginx/burpui.access.log;
    error_log   /var/log/nginx/burpui.error.log;

    location / {

        # you need to change this to "https", if you set "ssl" directive to "on"
        proxy_set_header   X-FORWARDED_PROTO http;
        proxy_set_header   Host              $http_host;
        proxy_set_header   X-Forwarded-For   $remote_addr;

        proxy_read_timeout 300;
        proxy_connect_timeout 300;

        proxy_pass http://localhost:5000;
    }
}

Sub-root path¶

You can host Burp-UI behind a sub-root path. For instance /burpui. To accomplish this, you can either setup your reverse-proxy to announce the desired prefix, or you can use the prefix option in your Burp-UI configuration file (see usage for details).

If you want to configure this reverse-proxy side, you need to announce the HTTP Header X-Script-Name. Alternatively, you can use the X_Forwarded_Prefix.

Here is a sample configuration for Nginx:

server {
    listen 80;
    server_name example.com;

    access_log  /var/log/nginx/burpui.access.log;
    error_log   /var/log/nginx/burpui.error.log;

    location /burpui {

        # you need to change this to "https", if you set "ssl" directive to "on"
        proxy_set_header   X-FORWARDED_PROTO http;
        proxy_set_header   Host              $http_host;
        proxy_set_header   X-Forwarded-For   $remote_addr;
        # Our service is hosted behind the "/burpui" prefix
        # Alternatively you can use the "X_FORWARDED_PREFIX" instead
        proxy_set_header   X-Script-Name     /burpui;

        proxy_read_timeout 300;
        proxy_connect_timeout 300;

        proxy_pass http://localhost:5000;
    }
}

Apache sample:

ProxyPass /burp/ http://localhost:5000/burp/
ProxyPassReverse /burp/ http://localhost:5000/burp/
<Location /burp/>
    SetOutputFilter proxy-html
    ProxyPassReverse /burp/
    ProxyHTMLURLMap  http://localhost:5000/     /
    Require all granted
</Location>

Warning

If your prefix does not start with a ‘/’, it will be ignored.

Production¶

We can consider the demo as a production example of what you can setup/expect in your environment. It is using Gunicorn along with Nginx as described above.

In order to improve performances, Redis can be used to cache sessions and various API calls. You can also enable the celery worker for asynchronous jobs. Additionally, you can enable the SQL storage.

The FAQ answers these questions:

See the production section of the usage page.

Gunicorn¶

Advanced usage¶

Daemon¶

Requirements¶

Systemd¶

Reverse-Proxy¶

Sub-root path¶

Production¶

Table of Contents

Related Topics

This Page