Usage

Burp-UI has been written with modularity in mind. The aim is to support Burp from the stable to the latest versions. Burp exists in two major versions: 1.x.x and 2.x.x.

Note

The version 2.x.x of Burp is currently in heavy development and should bring a lot of improvements, but also a lot of rework especially regarding the status port which is the main communication system between Burp and Burp-UI.

Both Versions are supported by Burp-UI thanks to its modular design. The consequence is you have various options in the configuration file to suite everybody needs.

There are also different modules to support Authentication and ACL within the web-interface.

Warning

Burp-UI tries to be as less intrusive as possible, nevertheless it ships with the ability to manage Burp‘s configuration files. This feature requires Burp-UI to be launched on the same server that hosts your Burp instance. You also have to make sure the user that runs Burp-UI has enough privileges to edit those files.

Configuration

The burpui.cfg configuration file contains a [Global] section as follow:

[Global]
# On which port is the application listening
port: 5000
# On which address is the application listening
# '::' is the default for all IPv6
# set it to '0.0.0.0' if you want to listen on all IPv4 addresses
bind: ::
# enable SSL
ssl: false
# ssl cert
sslcert: /etc/burp/ssl_cert-server.pem
# ssl key
sslkey: /etc/burp/ssl_cert-server.key
# burp server version 1 or 2
version: 1
# Handle multiple bui-servers or not
# If set to 'false', you will need to declare at least one 'Agent' section (see
# bellow)
standalone: true
# authentication plugin (mandatory)
# list the misc/auth directory to see the available backends
# to disable authentication you can set "auth: none"
# you can also chain multiple backends. Example: "auth: ldap,basic"
# the order will be respected unless you manually set a higher backend priority
auth: basic
# acl plugin
# list misc/acl directory to see the available backends
# default is no ACL
acl: basic
# You can change the prefix if you are behind a reverse-proxy under a custom
# root path. For example: /burpui
# You can also configure your reverse-proxy to announce the prefix through the
# 'X-Script-Name' header. In this case, the bellow prefix will be ignored in
# favour of the one announced by your reverse-proxy
prefix: none

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

  • port: On which port is Burp-UI listening. This option is ignored when using Gunicorn.

  • bind: On which address is Burp-UI listening. This option is ignored when using Gunicorn.

  • ssl: Whether to enable SSL or not. This option is ignored when using Gunicorn.

  • sslcert: SSL certificate to use when SSL support is enabled.

  • sslkey: SSL key to use when SSL support is enabled.

  • version: What version of Burp this Burp-UI instance manages. Can either be 1 or 2. This parameter determines which backend is loaded at runtime.

    (see Versions for more details)

  • standalone: Burp-UI can run in two different modes. If it runs in standalone mode (meaning you set this parameter to true), you can only address one Burp server of the version specified by the previous parameter.

    If this option is set to false, Burp-UI will run as a proxy allowing you to address multiple Burp servers. In this mode, you need to configure at least one Agent section in your configuration file. You also need to run one bui-agent per server.

    (see Modes for more details)

  • auth: What Authentication backend to use.

  • acl: What ACL module to use.

  • prefix: You can host Burp-UI behind a sub-root path. See the gunicorn page for details.

There is also a [UI] section in which you can configure some UI parameters:

[UI]
# refresh interval of the pages in seconds
refresh: 180
# refresh interval of the live-monitoring page in seconds
liverefresh: 5

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

  • refresh: Time in seconds between two refresh of the interface.
  • liverefresh: Time in seconds between two refresh of the live-monitor page.

Production

The burpui.cfg configuration file contains a [Production] section as follow:

[Production]
# storage backend for session and cache
# may be either 'default' or 'redis'
storage = default
# 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 = default
# 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 = default
# redis server to connect to
redis = localhost:6379
# whether to use celery or not
# may also be a broker url like: redis://localhost:6379/0
# if set to "true", the broker url defaults to:
# redis://<redis_host>:<redis_port>/2
# where <redis_host> is the host part, and <redis_port> is the port part of
# the above "redis" setting
celery = false
# database url to store some persistent data
# none or a connect string supported by SQLAlchemy:
# http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls
# example: sqlite:////var/lib/burpui/store.db
database = none

Experimental

There is a [Experimental] section for features that have not been deeply tested:

[Experimental]
## This section contains some experimental features that have not been deeply
## tested yet
# enable zip64 feature. Python doc says:
# « ZIP64 extensions are disabled by default because the default zip and unzip
# commands on Unix (the InfoZIP utilities) don’t support these extensions. »
zip64: false

These options are also available in the bui-agent configuration file.

Security

The [Security] section contains options to harden the security of the application:

[Security]
## This section contains some security options. Make sure you understand the
## security implications before changing these.
# list of 'root' paths allowed when sourcing files in the configuration.
# Set this to 'none' if you don't want any restrictions, keeping in mind this
# can lead to accessing sensible files. Defaults to '/etc/burp'.
# Note: you can have several paths separated by comas.
# Example: /etc/burp,/etc/burp.d
includes: /etc/burp
# if files already included in config do not respect the above restriction, we
# prune them
enforce: false
# enable certificates revocation
revoke: false
# remember_cookie duration in days
cookietime: 14
# whether to use a secure cookie for https or not. If set to false, cookies
# won't have the 'secure' flag.
# This setting is only useful when HTTPS is detected
scookie: true
# application secret to secure cookies. If you don't set anything, the default
# value is 'random' which will generate a new secret after every restart of your
# application. You can also set it to 'none' although this is not recommended.
appsecret: random

Some of these options are also available in the bui-agent configuration file.

Modes

Burp-UI provides two modes:

These modes allow you to either access a single Burp server or multiple Burp servers hosted on separated hosts.

Standalone

This mode is the default and the easiest one. It can be activated by setting the standalone parameter in the [Global] section of your burpui.cfg file to true:

[Global]
standalone: true

That’s all you need to do for this mode to work.

Multi-Agent

This mode allows you access multiple Burp servers through the bui-agent. The architecture is available on the bui-agent page.

To enable this mode, you need to set the standalone parameter of the [Global] section of your burpui.cfg file to false:

[Global]
standalone: false

Once this mode is enabled, you have to create one [Agent] section per agent you want to connect to in your burpui.cfg file:

# If you set standalone to 'false', add at least one section like this per
# bui-agent
[Agent:agent1]
# bui-agent address
host: 192.168.1.1
# bui-agent port
port: 10000
# bui-agent password
password: azerty
# enable SSL
ssl: true

[Agent:agent2]
# bui-agent address
host: 192.168.2.1
# bui-agent port
port: 10000
# bui-agent password
password: ytreza
# enable SSL
ssl: true

Note

The sections must be called [Agent:<label>] (case sensitive)

To configure your agents, please refer to the bui-agent page.

Versions

Burp-UI ships with two different backends:

These backends allow you to either connect to a Burp server version 1.x.x or 2.x.x.

Note

If you are using a Burp server version 2.x.x you have to use the Burp2 backend, no matter what Burp‘s protocol you are using.

Burp1

Note

Make sure you have read and understood the requirements first.

The burp-1 backend can be enabled by setting the version option to 1 in the [Global] section of your burpui.cfg file:

[Global]
version: 1

Now you can add burp-1 backend specific options:

# burp1 backend specific options
[Burp1]
# burp status address (can only be '127.0.0.1' or '::1')
bhost: ::1
# burp status port
bport: 4972
# burp binary
burpbin: /usr/sbin/burp
# vss_strip binary
stripbin: /usr/sbin/vss_strip
# burp client configuration file used for the restoration (Default: None)
bconfcli: /etc/burp/burp.conf
# burp server configuration file used for the setting page
bconfsrv: /etc/burp/burp-server.conf
# temporary directory to use for restoration
tmpdir: /tmp

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

  • bhost: The address of the Burp server. In burp-1.x.x, it can only be 127.0.0.1 or ::1
  • bport: The port of Burp‘s status port.
  • burpbin: Path to the Burp binary (used for restorations).
  • stripbin: Path to the Burp vss_strip binary (used for restorations).
  • bconfcli: Path to the Burp client configuration file (see restoration).
  • bconfsrv: Path to the Burp server configuration file.
  • tmpdir: Path to a temporary directory where to perform restorations.

Burp2

Note

Make sure you have read and understood the requirements first.

Note

The gunicorn documentation may help you configuring your system.

The burp-2 backend can be enabled by setting the version option to 2 in the [Global] section of your burpui.cfg file:

[Global]
version: 2

Now you can add burp-2 backend specific options:

# burp2 backend specific options
[Burp2]
# burp binary
burpbin: /usr/sbin/burp
# vss_strip binary
stripbin: /usr/sbin/vss_strip
# burp client configuration file used for the restoration (Default: None)
bconfcli: /etc/burp/burp.conf
# burp server configuration file used for the setting page
bconfsrv: /etc/burp/burp-server.conf
# temporary directory to use for restoration
tmpdir: /tmp
# how many time to wait for the monitor to answer (in seconds)
timeout: 5

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

  • burpbin: Path to the Burp binary (used for restorations).
  • stripbin: Path to the Burp vss_strip binary (used for restorations).
  • bconfcli: Path to the Burp client configuration file (see restoration).
  • bconfsrv: Path to the Burp server configuration file.
  • tmpdir: Path to a temporary directory where to perform restorations.
  • timeout: Time to wait for the monitor to answer in seconds.

Authentication

Burp-UI provides some authentication backends in order to restrict access only to granted users. There are currently three different backends:

To disable the authentication backend, set the auth option of the [Global] section of your burpui.cfg file to none:

[Global]
auth: none

You can use multiple backends, they will be sorted by priority or in the order they are defined if no priority is found. If a user is present in several backends, the first one that matches both login and password will be used.

Example:

[Global]
auth: basic,ldap

LDAP

The ldap authentication backend has some dependencies, please refer to the requirements page. To enable this backend, you need to set the auth option of the [Global] section of your burpui.cfg file to ldap:

[Global]
auth: ldap

Now you can add ldap specific options:

# ldapauth specific options
[LDAP]
# Backend priority. Higher is first
priority = 1
# LDAP host
host: 127.0.0.1
# LDAP port
port: 389
# Encryption type to LDAP server (none, ssl or tls)
# - try tls if unsure, otherwise ssl on port 636
encryption: tls
# specifies if the server certificate must be validated, values can be:
#  - none (certificates are ignored)
#  - optional (not required, but validated if provided)
#  - required (required and validated)
validate: none
# SSL or TLS version to use, can be one of the following:
#  - SSLv2
#  - SSLv3
#  - SSLv23
#  - TLSv1
#  - TLSv1_1 (Available only with openssl version 1.0.1+, requires python 2.7.9 or higher)
version: TLSv1
# the file containing the certificates of the certification authorities
cafile: none
# Attribute to use when searching the LDAP repository
#searchattr: sAMAccountName
searchattr: uid
# LDAP filter to find users in the LDAP repository
#  - {0} will be replaced by the search attribute
#  - {1} will be replaced by the login name
filter: (&({0}={1})(burpui=1))
#filter: (&({0}={1})(|(userAccountControl=512)(userAccountControl=66048)))
# LDAP base
base: ou=users,dc=example,dc=com
# Binddn to list existing users
binddn: cn=admin,dc=example,dc=com
# Bindpw to list existing users
bindpw: Sup3rS3cr3tPa$$w0rd

Note

The host options accepts URI style (ex: ldap://127.0.0.1:389)

Basic

In order for the basic authentication backend to be enabled, you need to set the auth option of the [Global] section of your burpui.cfg file to basic:

[Global]
auth: basic

Now you can add basic specific options:

# basicauth specific options
# Note: in case you leave this section commented, the default login/password
# is admin/admin
[BASIC]
# Backend priority. Higher is first
priority = 2
# Allow both plain and hashed passwords
# WARNING: This will defaults to false in v0.4.0
mixed = true
admin: pbkdf2:sha1:1000$12345678$password
user1: pbkdf2:sha1:1000$87654321$otherpassword

Note

Each line defines a new user with the key as the username and the value as the password

Warning

Since v0.3.0, passwords must be hashed

Local

In order for the local authentication backend to be enabled, you need to set the auth option of the [Global] section of your burpui.cfg file to local:

[Global]
auth: local

Now you can add local specific options:

# localauth specific options
# Note: if not running as root, then burp-ui must be run as group 'shadow' to
# allow PAM to work
[LOCAL]
# Backend priority. Higher is first
priority: 3
# List of local users allowed to login. If you don't set this setting, every
# local user will be able to login
users: user1,user2

ACL

Burp-UI implements some mechanisms to restrict access on some resources only for some users. There is currently only one backend:

To disable the acl backend, set the acl option of the [Global] section of your burpui.cfg file to none:

[Global]
acl: none

Basic ACL

The basic acl backend can be enabled by setting the acl option of the [Global] section of your burpui.cfg file to basic:

[Global]
acl: basic

Now you can add basic acl specific options:

# 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]
admin: user1,user2
# 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
user3: '["client4", "client5"]'
# In case you are not in a standalone mode, you can also specify which clients
# a user can access on a specific Agent
user4: '{"agent1": ["client6", "client7"], "agent2": ["client8"]}'

Warning

The double-quotes and single-quotes are mendatory