bui-agent

The bui-agent is a kind of proxy between a Burp server and your Burp-UI server.

It is useful when you have several servers to monitor and/or when you don’t want (or can’t) install the full Burp-UI on your server.

Architecture

The architecture is described bellow:

+--------------------+       +--------------------+       +--------------------+       +--------------------+
|                    |       |                    |       |                    |       |                    |
|  burp-server 1     |       |  burp-server 2     |       |        ...         |       |  burp-server n     |
|                    |       |                    |       |                    |       |                    |
+--------------------+       +--------------------+       +--------------------+       +--------------------+
|                    |       |                    |       |                    |       |                    |
|                    |       |                    |       |                    |       |                    |
|                    |       |                    |       |                    |       |                    |
|                    |       |                    |       |                    |       |                    |
| +----------------+ |       | +----------------+ |       | +----------------+ |       | +----------------+ |
| |                | |       | |                | |       | |                | |       | |                | |
| |  bui-agent 1   | |       | |  bui-agent 2   | |       | |      ...       | |       | |  bui-agent n   | |
| |                | |       | |                | |       | |                | |       | |                | |
| +-------^--------+ |       | +-------^--------+ |       | +--------^-------+ |       | +-------^--------+ |
+---------|----------+       +---------|----------+       +----------|---------+       +---------|----------+
          |                            |                             |                           |
          |                            |                             |                           |
          |                            |                             |                           |
          |                            |                             |                           |
          |                            |                             |                           |
          |                            |                             |                           |
          |                            |                             |                           |
          |                            |                             |                           |
          |                            |      +--------------------+ |                           |
          |                            |      |                    | |                           |
          |                            |      |   front-server     | |                           |
          |                            |      |                    | |                           |
          |                            |      +--------------------+ |                           |
          |                            |      |                    | |                           |
          |                            |      |                    | |                           |
          |                            |      |                    | |                           |
          |                            |      |                    | |                           |
          |                            |      | +----------------+ | |                           |
          |                            |      | |                | | |                           |
          |                            +--------+  burp-ui front +---+                           |
          +-------------------------------------+                +-------------------------------+
                                              | +--------^-------+ |
                                              +----------|---------+
                                                         |
                                                         |
                                              +----------+---------+
                                              |                    |
                                              |      client        |
                                              |                    |
                                              +--------------------+
                                              |                    |
                                              |                    |
                                              |                    |
                                              |                    |
                                              |                    |
                                              |                    |
                                              |                    |
                                              |                    |
                                              |                    |
                                              +--------------------+

Requirements

The agent is powered by gevent. In order to install it, you can run the following command:

pip install "burp-ui[agent]"

Configuration

These agents must be launched on every server hosting a Burp instance you’d like to monitor.

They have a specific buiagent.cfg configuration file with a [Global] section as below:

[Global]
# On which port is the application listening
port: 10000
# 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: true
# ssl cert
sslcert: /etc/burp/ssl_cert-server.pem
# ssl key
sslkey: /etc/burp/ssl_cert-server.key
# burp server version (currently only burp 1.x is implemented)
version: 1
# agent password
password: password

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

  • port: On which port is bui-agent listening.
  • bind: On which address is bui-agent listening.
  • 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.
  • version: What version of Burp this bui-agent instance manages. (see Burp-UI versions for more details)
  • password: The shared secret between the Burp-UI server and bui-agent.

As with Burp-UI, you need a specific section depending on the version value. Please refer to the Burp-UI versions section for more details.

Example

Here is a full usage example:

# On the server called 'agent1'
agent1:~$ bui-agent -c path/to/buiagent.cfg

# On the server called 'agent2'
agent2:~$ bui-agent -c path/to/buiagent.cfg

# On the server called 'front'
front:~$ burp-ui -c path/to/burpui.cfg

This example uses three servers. You then only need to point your browser to http://front:5000/ for instance, and the Burp-UI instance (front) will proxify the requests to the two agents for you.