Manage

Since v0.3.0, Burp-UI ships with a tool called bui-manage. This tool allows you to create new users and to manage database migrations.

This tool is actually a wrapper script that interacts with the core of Burp-UI. You can use it like this:

bui-manage [wrapper options...] [--] <subcommand>

This page details the subcommand usage. The tool provides some inline help too:

bui-manage -h
usage: bui-manage [-h] [-c <CONFIG>] [-i <MIGRATIONSDIR>]
                  [-m <agent|server|worker|manage>]
                  ...

positional arguments:
  remaining

optional arguments:
  -h, --help            show this help message and exit
  -c <CONFIG>, --config <CONFIG>
                        burp-ui configuration file
  -i <MIGRATIONSDIR>, --migrations <MIGRATIONSDIR>
                        migrations directory
  -m <agent|server|worker|manage>, --mode <agent|server|worker|manage>
                        application mode
# note the -- used to separate the wrapper from the actual command
bui-manage -- --help
Usage: flask [OPTIONS] COMMAND [ARGS]...

  This shell command acts as general utility script for Flask applications.

  It loads the application configured (either through the FLASK_APP
  environment variable) and then provides commands either provided by the
  application or Flask itself.

  The most useful commands are the "run" and "shell" command.

  Example usage:

    $ export FLASK_APP=hello
    $ export FLASK_DEBUG=1
    $ flask run

Options:
  --help  Show this message and exit.

Commands:
  compile_translation  Compile translations.
  create_user          Create a new user.
  db                   Perform database migrations.
  diag                 Check Burp-UI is correctly setup.
  hash_password        Hash a given password to fill the...
  init_translation     Initialize a new translation for the given...
  legacy               Legacy server for backward compatibility.
  run                  Runs a local development server for the...
  setup_burp           Setup burp client for burp-ui.
  shell                Runs a shell in the app context.
  sysinfo              Returns a couple of system informations to...
  update_translation   Update translation files.
  websocket            Start a new websocket server.

Database

To manage database migration, you first need to enable database support within your configuration file (see Production section)

You will also need some extra requirements:

pip install --upgrade "burp-ui[sql]"

Then you just have to run the following command to have your database setup:

bui-manage db upgrade

If your configuration is not in a common location, you can specify it like this:

bui-manage -c path/to/burpui.cfg db upgrade

If you did not install Burp-UI in a common location or you want to run it without installing it directly through the sources, you may need to specify the location of the migrations scripts like this:

bui-manage -c path/to/burpui.cfg -i path/to/migrations db upgrade

Users

You can create new users using the bui-manage file like this:

bui-manage create_user <new_username>

By default, the script will create new users for the Basic authentication backend. Without further details, a new password will be generated. You can either provide a password through the command line or tell the script to ask you what to setup using either the -p or -a options.

Examples:

bui-manage create_user user1
[*] Adding 'user1' user...
[+] Generated password: 71VIanuJ
[+] Success: True

bui-manage create_user -p toto user2
[*] Adding 'user2' user...
[+] Success: True

bui-manage create_user -a user3
[*] Adding 'user3' user...
Password:
Confirm:
[+] Success: True

Hashing passwords

Since v0.3.0, the BASIC authentication backend supports hashed passwords. Support for legacy plain-text passwords will be removed in *v0.7.0*.

In order to automate user creation using external scripts, a new bui-manage subcommand has been introduced in v0.6.0.

Usage:

Usage: flask hash_password [OPTIONS]

  Hash a given password to fill the configuration file.

Options:
  -p, --password TEXT  Password to assign to user.
  -u, --username TEXT  Provide the username to get the full configuration
                                           line.
  -b, --batch          Don't be extra verbose so that you can use the output
                                           directly in your scripts. Requires both -u and -p.
  --help               Show this message and exit.

Examples:

$ bui-manage hash_password --password demo --username demo --batch
demo = pbkdf2:sha256:50000$w5jD2WT1$d89cd4da1b6c3c3f05173faaf3feea802eee7b5b9a378ae8987d5ac6676d166b

$ bui-manage hash_password --password demo --username demo
'demo' hashed into: pbkdf2:sha256:50000$feQoDIIp$d42e056b75092beda52736ce792c6518061b21d6e1b2c755fdd71a764184ebd9
#8<-----------------------------------------------------------------------------
demo = pbkdf2:sha256:50000$feQoDIIp$d42e056b75092beda52736ce792c6518061b21d6e1b2c755fdd71a764184ebd9
#8<-----------------------------------------------------------------------------

$ bui-manage hash_password -u demo
Password:
'********' hashed into: pbkdf2:sha256:50000$MNHOgtdr$22d64b17bb8135be3ad61249d649e89ed96a5d4878b23e4889be24dfc062c126
#8<-----------------------------------------------------------------------------
demo = pbkdf2:sha256:50000$MNHOgtdr$22d64b17bb8135be3ad61249d649e89ed96a5d4878b23e4889be24dfc062c126
#8<-----------------------------------------------------------------------------

$ bui-manage hash_password
Password:
'********' hashed into: pbkdf2:sha256:50000$eWzSCvSW$9df9cdf854461a5f927708475e0470ad648f8cd0613ca61f8cee639db165ab53

Configure

Since v0.4.0, the bui-manage tool is now able to help you setup both Burp and Burp-UI so they speak to each other.

The available options are:

bui-manage setup_burp --help

Usage: flask setup_burp [OPTIONS]

  Setup burp client for burp-ui.

Options:
  -b, --burp-conf-cli TEXT   Burp client configuration file
  -s, --burp-conf-serv TEXT  Burp server configuration file
  -c, --client TEXT          Name of the burp client that will be used by
                             Burp-UI (defaults to "bui")
  -h, --host TEXT            Address of the status server (defaults to "::1")
  -r, --redis TEXT           Redis URL to connect to
  -d, --database TEXT        Database to connect to for persistent storage
  -p, --plugins TEXT         Plugins location
  -n, --dry                  Dry mode. Do not edit the files but display
                             changes
  --help                     Show this message and exit.

The script needs the Burp configuration files to be readable AND writable.

Note

This script was initially developped to setup the docker image. I do not guarantee to be able to support it out of the docker context.

Note

This script only supports Burp 2.0.x.

The docker image uses this script like this:

bui-manage -c $BURPUI_CONFIG setup_burp -b $BURP_CLIENT_CONFIG \
    -s $BURP_SERVER_CONFIG -h $BURP_SERVER_ADDR -c $BURPUI_CLIENT_NAME \
    -r $REDIS_SERVER -d $DATABASE_URL

WebSocket

Note

This tool first appeared with Burp-UI v0.6.0.

Launch a dedicated websocket server so you can have more than one worker. You may need a dedicated reverse-proxy though.

Example:

bui-manage websocket --help
Usage: flask websocket [OPTIONS]

  Start a new websocket server.

Options:
  -b, --bind TEXT     Which address to bind to for the websocket server
  -p, --port INTEGER  Which port to listen on for the websocket server
  -d, --debug         Whether to start the websocket server in debug mode
  --help              Show this message and exit.

Sysinfo

Note

This tool first appeared with Burp-UI v0.5.0.

This tool will help you to gather system informations in order to make a detailed bug report.

Example:

bui-manage sysinfo

Python version:  2.7.9
Burp-UI version: 0.6.0 (stable)
Single mode:     True
Backend version: 2
Config file:     share/burpui/etc/burpui.sample.cfg

You can also add the -v flag while running sysinfo but please MAKE SURE NO SENSITIVE DATA GET EXPOSED.

Example:

bui-manage sysinfo -v
Python version:  2.7.9
Burp-UI version: 0.6.0 (stable)
Single mode:     True
Backend version: 2
Config file:     share/burpui/etc/burpui.sample.cfg
>>>>> Extra verbose informations:
!!! PLEASE MAKE SURE NO SENSITIVE DATA GET EXPOSED !!!

    [Burp] section:
    8<---------------------------------------------------------------------BEGIN
    8<-----------------------------------------------------------------------END

    [Production] section:
    8<---------------------------------------------------------------------BEGIN
    storage = default
    session = default
    cache = default
    redis = localhost:6379
    celery = false
    database = none
    limiter = false
    ratio = 60/minute
    8<-----------------------------------------------------------------------END

    [Global] section:
    8<---------------------------------------------------------------------BEGIN
    version = 2
    single = true
    auth = basic
    acl = basic
    prefix = none
    plugins = none
    8<-----------------------------------------------------------------------END

Diag

Note

This tool first appeard with Burp-UI v0.5.0.

This tool will help you detect misconfiguration. It will not modify your files, you will have to use the Configure tool for that.

The available options are:

bui-manage diag --help

Usage: flask diag [OPTIONS]

  Check Burp-UI is correctly setup

Options:
  -c, --client TEXT  Name of the burp client that will be used by Burp-UI
                     (defaults to "bui")
  -h, --host TEXT    Address of the status server (defaults to "::1")
  -t, --tips         Show you some tips
  --help             Show this message and exit.

Examples:

bui-manage diag

The cname of your burp client does not match: hydrogen != bui
The burp server address does not match: 127.0.0.1 != ::1
'max_status_children' is to low, you need to set it to 15 or more. Please edit your /etc/burp/burp-server.conf file
Your burp client is not listed as a 'restore_client'. You won't be able to view other clients stats!
For performance reasons, it is recommanded to enable the 'monitor_browse_cache'
Unable to find the /etc/burp/clientconfdir/bui file
Some errors have been found in your configuration. Please make sure you ran this command with the right flags! (see --help for details)

bui-manage diag -c hydrogen -h 127.0.0.1 -t

'max_status_children' is to low, you need to set it to 15 or more. Please edit your /etc/burp/burp-server.conf file
Your burp client is not listed as a 'restore_client'. You won't be able to view other clients stats!
For performance reasons, it is recommanded to enable the 'monitor_browse_cache'
Well, if you are sure about your settings, you can run the following command to help you setup your Burp-UI agent. (Note, the '--dry' flag is here to show you the modifications that will be applied. Once you are OK with those, you can re-run the command without the '--dry' flag):
    > bui-manage setup_burp --host="127.0.0.1" --client="hydrogen" --dry

When your configuration is OK, you should see this message:

Congratulations! It seems everything is alright. Burp-UI should run without any issue now.