Security in Doppio

Warning

Doppio versions before v1.0.1 were insecure and could allow an attacker to run arbitrary code on your computer. If you are using an older version we recommend you update to v1.0.1 or later as soon as possible.

Overview

Doppio can run arbitrary code with the permissions of the user who launched the server. This could allow an attacker to run malicious code or bypass file system permissions, so it’s important to make sure that only the user who started Doppio is able to access it.

To ensure this, Doppio uses a token-based authentication system. The design borrows heavily from the approach used by Jupyter Server.

From a user’s perspective, the authentication will happen automatically when you start Doppio and you shouldn’t need to worry about it. But if something goes wrong or you’d like to understand more, please refer to the information below.

Details

When it starts, Doppio generates a secure token that must be supplied with all requests to authenticate the user. The token can be supplied in a URL query parameter, like this:

http://127.0.0.1:1430/?token=123abc...

The token is the only thing that authenticates the request, so you should treat it as securely as you treat your login password. If you want to work cooperatively with other users on the same project, we suggest that you use file permissions to make the project available to all users who need to access it, and then each user can run their own Doppio session to access the project.

Warning

If you share the access token, anyone who has it will be able to run arbitrary code on your computer with the privileges and permissions of the user who started Doppio.

After the first authenticated request is made, a browser cookie will be set which is used to authenticate all subsequent requests. The cookie will expire 24 hours after the last request, so if you leave a Doppio server running without a browser connected to it and then try to open the browser again more than a day later, you will have to re-authenticate the session.

Note

To avoid the token being visible in plain text on the network, the cookie that is used to authenticate a Doppio session can only be set on a secure connection, which means either a local loopback connection to an address like localhost or 127.0.0.1, or a secure connection over https. To use Doppio remotely, you will need to use port forwarding so that Doppio can still run on a local host address (rather than a public address). In principle you could also secure your connection by running Doppio at an https:// address, but we do not currently make this available as an option. If you would like this, please contact us so we know there is demand for this feature and we can provide you with an experimental version of Doppio to test with.

When you start Doppio, the server prints the token to the log, so if you need the token you can always go back to the terminal where you launched it, find the start of the log and look for the token message. For example, you can see it in green here:

When you start the Doppio desktop application, the app should open and authenticate automatically. Similarly, when you start the web application by running doppio-web, it should open your browser to view Doppio and the initial authentication should be automatic.

If you do ever try to connect to Doppio without a valid authentication token, you will see a login form like this:

If this happens, find your token from the server start-up message (make sure it’s the right server, if you could be running more than one), copy and paste it into the form and click Submit.

The redirection file

The automatic authentication in the web app works by writing the full server URL, including the access token in a query parameter, to a temporary redirection file that will be written to a suitable location in your user home directory. It then opens your browser to view the local file, which will immediately redirect to the true server URL with the access token included.

The reason for this redirection is to avoid leaking the access token to other users on your system. If Doppio opened your browser by just pointing immediately to the server URL with the access token, the token would be visible to all users because it would be included verbatim in the arguments to the command used to launch the browser (which can be seen by any user, for example with the ps command). With the redirection approach, the token does not appear in a command argument and is only written to the file on disk, where access can be restricted only to the current user using normal file system permissions.

If the redirection does not work properly for any reason, you can always connect to Doppio by going to the server URL and then copy-pasting the token into the login form, as described above.

Setting your own token

If you really need to, and if you are confident you understand the security implications, you can force Doppio to use a specific authentication token by setting the DOPPIO_TOKEN environment variable. Be aware that if you set a token value which could easily be guessed, you could open your system up to attack.