doc: new websocket feature

docs/advanced_usage.rst

@@ -153,6 +153,40 @@ follow:
     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 <websocket.html>`_ page.
+
+::
+
+    [WebSocket]
+    ## This section contains WebSocket server specific options.
+    # 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://<redis_host>:<redis_port>/4
+    # where <redis_host> is the host part, and <redis_port> 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
 ------------
 

docs/index.rst

@@ -27,6 +27,7 @@ Documentation
    advanced_usage
    manage
    celery
+   websocket
    gunicorn
    docker
    buiagent

docs/manage.rst

@@ -59,14 +59,18 @@ The tool provides some inline help too:
       --help  Show this message and exit.
 
     Commands:
-      compile_translation  Compile translations.
+    compile_translation  Compile translations.
       create_user          Create a new user.
       db                   Perform database migrations.
+      diag                 Check Burp-UI is correctly setup.
       init_translation     Initialize a new translation for the given...
-      run                  Runs a development server.
+      legacy               Legacy server for backward compatibility.
+      run                  Runs a local development server for the...
       setup_burp           Setup burp client for burp-ui.
       shell                Runs a shell in the app context.
+      sysinfo              Returns a couple of system informations to...
       update_translation   Update translation files.
+      websocket            Start a new websocket server.
 
 
 Database
@@ -193,11 +197,36 @@ The docker image uses this script like this:
         -r $REDIS_SERVER -d $DATABASE_URL
 
 
+WebSocket
+---------
+
+.. note::
+    This tool first appeared with `Burp-UI`_ *v0.6.0*.
+
+Launch a dedicated websocket server so you can have more than one worker.
+You may need a dedicated reverse-proxy though.
+
+Example:
+
+::
+
+	bui-manage websocket --help
+	Usage: flask websocket [OPTIONS]
+
+	  Start a new websocket server.
+
+	Options:
+	  -b, --bind TEXT     Which address to bind to for the websocket server
+	  -p, --port INTEGER  Which port to listen on for the websocket server
+	  -d, --debug         Whether to start the websocket server in debug mode
+	  --help              Show this message and exit.
+
+
 Sysinfo
 -------
 
 .. note::
-    This tool first appeard with `Burp-UI`_ *v0.5.0*.
+    This tool first appeared with `Burp-UI`_ *v0.5.0*.
 
 This tool will help you to gather system informations in order to make a
 detailed bug report.

docs/upgrading.rst

@@ -17,6 +17,7 @@ v0.6.0
   granted on both clients on the two agents. You can disable this behavior with
   the `legacy` option. See the `BASIC ACL <advanced_usage.html#basic-acl>`_
   documentation for details.
+- **New** - WebSocket support for better/smarter notifications.
 
 v0.5.0
 ------

docs/websocket.rst

+WebSocket
+=========
+
+Since *v0.6.0*, `Burp-UI`_ supports WebSockets for better/smarter notifications.
+In order to use this feature, you need some extra requirements:
+
+::
+
+    pip install "burp-ui[websocket]"
+
+
+It is highly recommended to use a `Redis`_ *Broker* for the websocket server to
+ interact with the celery workers and other pieces of the code.
+It is also advised to run one or several dedicated WebSocket servers behind a 
+reverse-proxy because *gunicorn* does not play well with it.
+
+The details of the configuration may be found in the `WebSocket
+<advanced_usage.html#websocket>`__ section.
+
+Dedicated Server
+----------------
+
+You can choose to either run an embedded WebSocket server though this is not
+recommended in production or you can run one or several dedicated WebSocket
+ servers through the ``bui-manage`` command like this:
+
+::
+
+    bui-manage websocket --bind 0.0.0.0 --port 5001
+
+
+If you are running the above command, you'll need to set the ``url`` option
+under the ``[WebSocket]`` section to ``"document.domain + ':5001'"``.
+
+.. warning:: The quotes are **MANDATORY** in this case.
+
+Alternatively, you can setup a reverse-proxy as explained bellow.
+
+.. note:: A systemd service example file is shiped in the *contrib* directory
+
+Reverse-proxy
+-------------
+
+Running one or several dedicated WebSocket server is the recommended setup in
+production.
+You will find more details on this in the
+`Flask-SocketIO <https://flask-socketio.readthedocs.io/en/latest/#deployment>`_
+documentation.
+
+Running a dedicated server on a dedicated port and/or IP may be a pain. That's
+the reason why you can/should setup a reverse-proxy in front of this using a
+configuration like:
+
+::
+
+	server {
+		listen 80;
+		server_name _;
+
+		location / {
+			proxy_pass http://127.0.0.1:5000;
+		}
+
+		location /socket.io {
+			proxy_http_version 1.1;
+			proxy_buffering off;
+			proxy_set_header Upgrade $http_upgrade;
+			proxy_set_header Connection "Upgrade";
+			proxy_pass http://127.0.0.1:5001/socket.io;
+		}
+	}
+
+
+If you ran several servers, you can use this config:
+
+::
+
+	upstream socketio_nodes {
+		ip_hash;
+
+		server 127.0.0.1:5001;
+		server 127.0.0.1:5002;
+		# to scale the app, just add more nodes here!
+	}
+
+	server {
+		listen 80;
+		server_name _;
+
+		location / {
+			proxy_pass http://127.0.0.1:5000;
+		}
+
+		location /socket.io {
+			proxy_http_version 1.1;
+			proxy_buffering off;
+			proxy_set_header Upgrade $http_upgrade;
+			proxy_set_header Connection "Upgrade";
+			proxy_pass http://socketio_nodes/socket.io;
+		}
+	}
+
+
+.. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui
+.. _Redis: http://redis.io/

share/burpui/etc/burpui.sample.cfg

@@ -90,7 +90,16 @@ embedded = false
 # redis://<redis_host>:<redis_port>/4
 # where <redis_host> is the host part, and <redis_port> is the port part of
 # the above "redis" setting
-broker = none
+# 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
 
 [Security]
 ## This section contains some security options. Make sure you understand the