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
Note
Starting with v0.5.0, the agent now has its own package.
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 1 or 2
version = 1
# agent password
password = password
# time to wait at startup
# the burp server must be started before your agent
init_wait = 15
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.
init_wait: The time to wait for the backend to be alive (this is useful in case you start every services at the same time).
As with Burp-UI, you need a specific [Burp] section.
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.
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-agent as a service, a systemd file is provided. You can use it like this:
cp /usr/local/share/burpui/contrib/systemd/bui-agent.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable bui-agent.service
systemctl start bui-agent.service
