Start on whitelist and add docs

Author: jacobtomlinson

docs/arbitrary-ports.rst renamed to docs/arbitrary-ports-hosts.rst

@@ -1,8 +1,8 @@
 .. _arbitrary-ports:
 
-=========================
-Accessing Arbitrary Ports
-=========================
+==================================
+Accessing Arbitrary Ports or Hosts
+==================================
 
 If you already have a server running on localhost listening on
 a port, you can access it through the notebook at
@@ -15,6 +15,11 @@ URL in the request.
 
 This works for all ports listening on the local machine.
 
+You can also specify arbitrary hosts in order to proxy traffic from
+another machine on the network ``<notebook-base>/proxy/<host>:<port>``.
+
+For security reasons the host must match an entry in the whitelist in your configuration.
+
 With JupyterHub
 ===============
 
@@ -38,7 +43,7 @@ Without JupyterHub
 ==================
 
 A very similar set up works when you don't use JupyterHub. You
-can construct the URL with ``<notebook-url>/proxy/<port>``. 
+can construct the URL with ``<notebook-url>/proxy/<port>``.
 
 If your notebook url is ``http://localhost:8888`` and you have
 a process running listening on port 8080, you can access it with

docs/index.rst

@@ -20,7 +20,7 @@ The primary use cases are:
 #. Allow access from frontend javascript (in classic notebook or
    JupyterLab extensions) to access web APIs of other processes
    running locally in a safe manner. This is used by the `JupyterLab
-   extension <https://github.com/dask/dask-labextension>`_ for 
+   extension <https://github.com/dask/dask-labextension>`_ for
    `dask <https://dask.org/>`_.
 
 
@@ -33,7 +33,7 @@ Contents
    install
    server-process
    launchers
-   arbitrary-ports
+   arbitrary-ports-hosts
 
 
 Convenience packages for popular applications

jupyter_server_proxy/handlers.py

@@ -10,6 +10,7 @@
 from urllib.parse import urlunparse, urlparse
 import aiohttp
 from asyncio import Lock
+import re
 
 from tornado import gen, web, httpclient, httputil, process, websocket, ioloop, version_info
 
@@ -166,6 +167,11 @@ def _build_proxy_request(self, host, port, proxied_path, body):
             headers=headers, **self.proxy_request_options())
         return req
 
+    def _check_host_whitelist(self, host):
+        # TODO Get whitelist from config
+        whitelist = [r'localhost']
+        return any([bool(re.match(pattern, host)) for pattern in whitelist])
+
     @web.authenticated
     async def proxy(self, host, port, proxied_path):
         '''
@@ -175,6 +181,12 @@ async def proxy(self, host, port, proxied_path):
             {base_url}/{proxy_base}/{proxied_path}
         '''
 
+        if not self._check_host_whitelist(host):
+            self.set_status(403)
+            self.write("Host '{host}' is not whitelisted. "
+                       "See https://jupyter-server-proxy.readthedocs.io/en/latest/arbitrary-ports-hosts.html for info.".format(host=host))
+            return
+
         if 'Proxy-Connection' in self.request.headers:
             del self.request.headers['Proxy-Connection']
 
@@ -226,6 +238,14 @@ async def proxy_open(self, host, port, proxied_path=''):
         We establish a websocket connection to the proxied backend &
         set up a callback to relay messages through.
         """
+
+        if not self._check_host_whitelist(host):
+            self.set_status(403)
+            self.log.info("Host '{host}' is not whitelisted. "
+                          "See https://jupyter-server-proxy.readthedocs.io/en/latest/arbitrary-ports-hosts.html for info.".format(host=host))
+            self.close()
+            return
+
         if not proxied_path.startswith('/'):
             proxied_path = '/' + proxied_path