diff --git a/README.rst b/README.rst index c429e98..2cdc982 100644 --- a/README.rst +++ b/README.rst @@ -28,6 +28,7 @@ Development Status ================== This project is currently in **pre-alpha**, and things will break all the time. +There is no supported upgrade pathway, and security issues most likely exist. However, feedback at this time is extremely valuble, so you should still try it out! diff --git a/docs/index.rst b/docs/index.rst index 2991e22..64ee031 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,14 @@ The Littlest JupyterHub A simple `JupyterHub `_ distribution for a small (0-50) number of users on a single server. +Development Status +================== + +This project is currently in **pre-alpha**, and things will break all the time. +There is no supported upgrade pathway, and security issues most likely exist. +However, feedback at this time is extremely valuble, so you should still try +it out! + Installation ============ @@ -37,16 +45,18 @@ How-To guides answer the question 'How do I...?' for a lot of topics. howto/user-environment howto/notebook-interfaces -Guides -====== +Topic Guides +============ -Guides provide in-depth explanations of specific topics. +Topic guides provide in-depth explanations of specific topics. .. toctree:: :titlesonly: guides/requirements guides/admin + topic/security + Troubleshooting =============== diff --git a/docs/topic/security.rst b/docs/topic/security.rst new file mode 100644 index 0000000..0d5f004 --- /dev/null +++ b/docs/topic/security.rst @@ -0,0 +1,67 @@ +======================= +Security Considerations +======================= + +The Littlest JupyterHub is in pre-alpha state & should not be used in +security critical situations. We will try to keep things as secure as possible, +but sometimes trade security for massive gains in convenience. This page contains +information about the security model of The Littlest JupyterHub. + +System user accounts +==================== + +Each JupyterHub user gets their own unix user account created when they +first start their server. This protects users from each other, gives them a +home directory at a well known location, and allows sharing based on file system +permissions. + +#. The unix user account created for a JupyterHub user named ```` is + ``jupyter-``. This prefix helps prevent clashes with users that + already exist - otherwise a user named ``root`` can trivially gain full root + access to your server. + +#. A home directory is created for the user under ``/home/jupyter-``. + +#. No password is set for this unix system user by default. The password used + to log in to JupyterHub (if using an authenticator that requires a password) + is not related to the unix user's password in any form. + +#. All users created by The Littlest JupyterHub are added to the user group + ``jupyterhub-users``. + +``sudo`` access for admins +========================== + +JupyterHub admin users are added to the user group ``jupyterhub-admins``, +which is granted complete root access to the whole server with the ``sudo`` +command on the terminal. No password required. + +This is a **lot** of power, and they can do pretty much anything they want to +the server - look at other people's work, modify it, break the server in cool & +funky ways, etc. This also means if an admin's credentials are compromised ( +easy to guess password, password re-use, etc) the entire JupyterHub is compromised. + +Off-boarding users securely +=========================== + +When you delete users from the JupyterHub admin console, their unix user accounts +are **not** removed. This means they might continue to have access to the server +even after you remove them from JupyterHub. Admins should manually remove the user +from the server & archive their home directories as needed. If the user removed +from the server is an admin, extra care must be taken since they could have +modified the system earlier to continue giving them access. + +Per-user ``/tmp`` +================= + +``/tmp`` is shared by all users in most computing systems, and this has been +a consistent source of security issues. The Littlest JupyterHub gives each +user their own ephemeral ``/tmp`` using the `PrivateTmp `_ +feature of systemd. + +HTTPS +===== + +The Littlest JupyterHub does not currently support HTTPS. Follow `this issue +`_ for progress +on HTTPS support.