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 backend to load either one of 'burp1', 'burp2', 'parallel' or 'multi'. # If you choose 'multi', you will have to declare at lease one 'Agent' section. # If you choose 'parallel', you need to configure the [Parallel] section. # If you choose either 'burp1' or 'burp2', you need to configure the [Burp] # section. # The [Burp] section is also used with the 'parallel' backend for the restoration # process. # You can also use whatever custom backend you like if it is located in the # 'plugins' directory and if it implements the right interface. backend = burp2 # 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 (chainable, see 'auth' plugin option) # list misc/acl directory to see the available backends # default is no ACL acl = basic # audit logger plugin (chainable, see 'auth' plugin option) # list the misc/audit directory to see the available backends # default is no audit log audit = basic # list of paths to look for external plugins plugins = none Each option is commented, but here is a more detailed documentation: - *backend*: What `Burp`_ backend to load. Can either be one of *burp1*, *burp2*, *parallel* or *multi*, or can be whatever custom backend you like as long as it implements the proper interface. If providing a custom backend name, it must be located in the *plugins* directory. You can also specify a custom external module by providing the *dot-string* notation (example: *my.custom.backend*). (see `Backends`_ for more details) - *auth*: What `Authentication`_ backend to use. - *acl*: What `ACL`_ module to use. - *audit*: What `Audit`_ module to use. - *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 # redis server to connect to redis = localhost:6379 # 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 # 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 # 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 # 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 # 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 # ProxyFix # number of reverse-proxy to trust in order to retrieve some HTTP headers # All the details can be found here: # https://werkzeug.palletsprojects.com/en/0.15.x/middleware/proxy_fix/#module-werkzeug.middleware.proxy_fix num_proxies = 0 # alternatively, you can specify your own ProxyFix args. # The default is: "{'x_proto': {num_proxies}, 'x_for': {num_proxies}, 'x_host': {num_proxies}, 'x_prefix': {num_proxies}}" # if num_proxies > 0, else it defaults to ProxyFix defaults proxy_fix_args = "{'x_proto': {num_proxies}, 'x_for': {num_proxies}, 'x_host': {num_proxies}, 'x_prefix': {num_proxies}}" - *storage*: What storage engine should be used for sessions, cache, etc. Can only be one of: ``default`` or ``redis``. - *redis*: redis server to use. - *session*: redis database to use, by default (if set to ``redis``) we use database **0** on the server provided in *redis*. - *cache*: redis database to use, by default (if set to ``redis``) we use database **1** on the server provided in *redis*. - *celery*: redis database to use as broker and message queue for Celery, by default (if set to ``true``) we use database **2** on the server provided in *redis*. You can also set it to ``false`` to disable Celery support. - *limiter*: redis database to use, by default (if set to ``redis``) we use database **3** on the server provided in *redis*. - *ratio*: Limiter ratio. See `Limiter `_ documentation for details. - *database*: Enable SQL persistent storage. Can be ``none`` (to disable SQL) or any valid `SQLAlchemy `_ connect string. - *prefix*: You can host `Burp-UI`_ behind a sub-root path. See the `gunicorn `__ page for details. - *num_proxies*: This is useful only if you host `Burp-UI`_ behind a `reverse-proxy `__. - *proxy_fix_args*: Same as above. Please refer to `Werkzeug's documentation `_ for details. 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 = true 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. Backends -------- `Burp-UI`_ ships with four different backends: - `Burp1`_ - `Burp2`_ - `Multi`_ - `Parallel`_ 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 *backend* option to *burp1* in the ``[Global]`` section of your `burpui.cfg`_ file: :: [Global] backend = burp1 Now you can refer to the `Options`_ section for further setup. 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 *backend* option to *burp2* in the ``[Global]`` section of your `burpui.cfg`_ file: :: [Global] backend = burp2 Now you can refer to the `Options`_ section for further setup. Multi ^^^^^ The *multi* backend allows you to connect to different *bui-agents*. It can be enabled by setting the *backend* option to *multi* in the ``[Global]`` section of your `burpui.cfg`_ file: :: [Global] backend = multi This backend allows you to access multiple `Burp`_ servers through the `bui-agent`_. The architecture is available on the bui-agent `page `__. Once this backend is enabled, you have to create **one** ``[Agent]`` section **per** agent you want to connect to in your `burpui.cfg`_ file: :: # If you set backend to 'multi', 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: