Advanced usage ============== .. highlight:: ini `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. 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] # burp server version 1 or 2 version = 2 # Handle multiple bui-servers or not # If set to 'false', you will need to declare at least one 'Agent' section (see # bellow) single = 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 # list of paths to look for external plugins plugins = none Each option is commented, but here is a more detailed documentation: - *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) - *single*: `Burp-UI`_ can run in two different modes. If it runs in single 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. - *plugins*: Specify a list of paths to look for external plugins. See the `Plugins `_ page for details on how to write plugins. 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 # list of labels to ignore (you can use regex) ignore_labels = "color:.*", "custom:.*" # format label using sed-like syntax format_labels = "s/^os:\s*//" # default strip leading path value for file restorations default_strip = 0 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. - *ignore_labels*: List of labels to ignore from parsing (regex are supported). - *format_labels*: List of *sed-like* expressions to transform labels. Example: ``"s/^os:\s*//", "s/i/o/"`` will transform the label ``os: Windows`` into ``Wondows``. - *default_strip*: Number of leading paths to strip by default while restoring files. 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://:/0 # where is the host part, and 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://:/1 # where is the host part, and 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://:/2 # where is the host part, and 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 # whether to rate limit the API or not # may also be a redis url like: redis://localhost:6379/0 # if set to "true" or "redis" or "default", the url defaults to: # redis://:/3 # where is the host part, and is the port part of # the above "redis" setting # Note: the limiter only applies to the API routes limiter = false # limiter ratio # see https://flask-limiter.readthedocs.io/en/stable/#ratelimit-string ratio = 60/minute WebSocket --------- The ``[WebSocket]`` section defines specific options for the WebSocket server. You will find details on how to use this feature in the `WebSocket `_ page. :: [WebSocket] ## This section contains WebSocket server specific options. # whether to enable websocket or not enabled = true # whether to embed the websocket server or not # if set to "true", you should have only *one* gunicorn worker # see here for details: # https://flask-socketio.readthedocs.io/en/latest/#gunicorn-web-server embedded = false # what broker to use to interact between websocket servers # may be a redis url like: redis://localhost:6379/0 # if set to "true" or "redis" or "default", the url defaults to: # redis://:/4 # where is the host part, and is the port part of # the above "redis" setting # set this to none to disable the broker broker = redis # if you choose to run a dedicated websocket server (with embedded = false) # you can specify here the websocket url. You'll need to double quote your # string though. # example: # url = "document.domain + ':5001'" url = none # whether to enable verbose websocket server logs or not (for development) debug = false 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: - `Single`_ - `Multi-Agent`_ These modes allow you to either access a single `Burp`_ server or multiple `Burp`_ servers hosted on separated hosts. Single ^^^^^^ This mode is the **default** and the easiest one. It can be activated by setting the *single* parameter in the ``[Global]`` section of your `burpui.cfg`_ file to *true*: :: [Global] single = true That's all you need to do for this mode to work. Multi-Agent ^^^^^^^^^^^ This mode allows you to 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 *single* parameter of the ``[Global]`` section of your `burpui.cfg`_ file to *false*: :: [Global] single = 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 single 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: