diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..e1c6ebf551 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# Jupyter Server Docs Sources + +Read [this page](https://jupyter-server.readthedocs.io/en/latest/contributors/contributing.html#building-the-docs) to build the docs. diff --git a/docs/source/developers/dependency.rst b/docs/source/developers/dependency.rst index a145e4ce8c..d2efb82b24 100644 --- a/docs/source/developers/dependency.rst +++ b/docs/source/developers/dependency.rst @@ -18,4 +18,4 @@ To pin your jupyter_server install to a specific version: .. code-block:: console - > pip install jupyter_server==1.0 + > pip install jupyter_server==1.0.0 diff --git a/docs/source/developers/extensions.rst b/docs/source/developers/extensions.rst index 65c5b90f80..1bcdb74870 100644 --- a/docs/source/developers/extensions.rst +++ b/docs/source/developers/extensions.rst @@ -4,6 +4,9 @@ Server Extensions A Jupyter Server extension is typically a module or package that extends to Server’s REST API/endpoints—i.e. adds extra request handlers to Server’s Tornado Web Application. +You can check some simple examples on the `examples folder +`_ in the GitHub jupyter_server repository. + Authoring a basic server extension ================================== @@ -376,12 +379,6 @@ Putting it all together, authors can distribute their extension following this s ) -Example Server Extension -======================== - -You can check some simple example on the `GitHub jupyter_server repository -`_. - .. links diff --git a/docs/source/index.rst b/docs/source/index.rst index 1e0cb10bb6..67172cf077 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,9 +3,9 @@ Welcome! You've landed on the documentation pages for the **Jupyter Server** Project. Some other pages you may have been looking for: -* `Jupyter Server Github Repo `_ -* `JupyterLab Github Repo `_ -* `Jupyter Notebook Github Repo `_ +* `Jupyter Server Github Repo `_, the source code we describe in this code. +* `Jupyter Notebook Github Repo `_ , the source code for the classic Notebook. +* `JupyterLab Github Repo `_, the JupyterLab server wich runs on the Jupyter Server. Introduction @@ -15,7 +15,7 @@ Jupyter Server is the backend—the core services, APIs, and `REST endpoints`_ .. note:: - Jupyter Server is a replacement for the Tornado Web Server in `Jupyter Notebook`_. Jupyter web applications should move to using Jupyter Server. For help, see `this page `_. + Jupyter Server is a replacement for the Tornado Web Server in `Jupyter Notebook`_. Jupyter web applications should move to using Jupyter Server. For help, see the :ref:`migrate_from_notebook` page. .. _Tornado: https://www.tornadoweb.org/en/stable/ .. _Jupyter Notebook: https://github.com/jupyter/notebook diff --git a/docs/source/operators/ipython_security.asc b/docs/source/operators/ipython_security.asc new file mode 100644 index 0000000000..95436812a4 --- /dev/null +++ b/docs/source/operators/ipython_security.asc @@ -0,0 +1,52 @@ +-----BEGIN PGP PUBLIC KEY BLOCK----- +Version: GnuPG v2.0.22 (GNU/Linux) + +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 +5vmLc+Ibz+eT+rM= +=XVDe +-----END PGP PUBLIC KEY BLOCK----- diff --git a/docs/source/operators/migrate-from-nbserver.rst b/docs/source/operators/migrate-from-nbserver.rst index 2ee6ffa50a..087ed90f63 100644 --- a/docs/source/operators/migrate-from-nbserver.rst +++ b/docs/source/operators/migrate-from-nbserver.rst @@ -29,7 +29,7 @@ You will have to create the following ``jupyter_server_config.py`` file. Running Jupyter Notebook on Jupyter Server ========================================== -If you want to switch to Jupyter Server, but you still want to serve `Jupyter Notebook `_ to users, you can try `NBClassic `_. +If you want to switch to Jupyter Server, but you still want to serve `Jupyter Notebook `_ to users, you can try `NBClassic `_. NBClassic is a Jupyter Server extension that serves the Notebook frontend (i.e. all static assets) on top of Jupyter Server. It even loads Jupyter Notebook's config files. diff --git a/docs/source/operators/security.rst b/docs/source/operators/security.rst index e5727421b9..6479fb3a9c 100644 --- a/docs/source/operators/security.rst +++ b/docs/source/operators/security.rst @@ -77,3 +77,144 @@ but this is **NOT RECOMMENDED**, unless authentication or access restrictions ar c.ServerApp.token = '' c.ServerApp.password = '' +Security in notebook documents +============================== + +As Jupyter Server become more popular for sharing and collaboration, +the potential for malicious people to attempt to exploit the notebook +for their nefarious purposes increases. IPython 2.0 introduced a +security model to prevent execution of untrusted code without explicit +user input. + +The problem +----------- + +The whole point of Jupyter is arbitrary code execution. We have no +desire to limit what can be done with a notebook, which would negatively +impact its utility. + +Unlike other programs, a Jupyter notebook document includes output. +Unlike other documents, that output exists in a context that can execute +code (via Javascript). + +The security problem we need to solve is that no code should execute +just because a user has **opened** a notebook that **they did not +write**. Like any other program, once a user decides to execute code in +a notebook, it is considered trusted, and should be allowed to do +anything. + +Our security model +------------------ + +- Untrusted HTML is always sanitized +- Untrusted Javascript is never executed +- HTML and Javascript in Markdown cells are never trusted +- **Outputs** generated by the user are trusted +- Any other HTML or Javascript (in Markdown cells, output generated by + others) is never trusted +- The central question of trust is "Did the current user do this?" + +The details of trust +-------------------- + +When a notebook is executed and saved, a signature is computed from a +digest of the notebook's contents plus a secret key. This is stored in a +database, writable only by the current user. By default, this is located at:: + + ~/.local/share/jupyter/nbsignatures.db # Linux + ~/Library/Jupyter/nbsignatures.db # OS X + %APPDATA%/jupyter/nbsignatures.db # Windows + +Each signature represents a series of outputs which were produced by code the +current user executed, and are therefore trusted. + +When you open a notebook, the server computes its signature, and checks if it's +in the database. If a match is found, HTML and Javascript +output in the notebook will be trusted at load, otherwise it will be +untrusted. + +Any output generated during an interactive session is trusted. + +Updating trust +************** + +A notebook's trust is updated when the notebook is saved. If there are +any untrusted outputs still in the notebook, the notebook will not be +trusted, and no signature will be stored. If all untrusted outputs have +been removed (either via ``Clear Output`` or re-execution), then the +notebook will become trusted. + +While trust is updated per output, this is only for the duration of a +single session. A newly loaded notebook file is either trusted or not in its +entirety. + +Explicit trust +************** + +Sometimes re-executing a notebook to generate trusted output is not an +option, either because dependencies are unavailable, or it would take a +long time. Users can explicitly trust a notebook in two ways: + +- At the command-line, with:: + + jupyter trust /path/to/notebook.ipynb + +- After loading the untrusted notebook, with ``File / Trust Notebook`` + +These two methods simply load the notebook, compute a new signature, and add +that signature to the user's database. + +Reporting security issues +------------------------- + +If you find a security vulnerability in Jupyter, either a failure of the +code to properly implement the model described here, or a failure of the +model itself, please report it to security@ipython.org. + +If you prefer to encrypt your security reports, +you can use :download:`this PGP public key `. + +Affected use cases +------------------ + +Some use cases that work in Jupyter 1.0 became less convenient in +2.0 as a result of the security changes. We do our best to minimize +these annoyances, but security is always at odds with convenience. + +Javascript and CSS in Markdown cells +************************************ + +While never officially supported, it had become common practice to put +hidden Javascript or CSS styling in Markdown cells, so that they would +not be visible on the page. Since Markdown cells are now sanitized (by +`Google Caja `__), all Javascript +(including click event handlers, etc.) and CSS will be stripped. + +We plan to provide a mechanism for notebook themes, but in the meantime +styling the notebook can only be done via either ``custom.css`` or CSS +in HTML output. The latter only have an effect if the notebook is +trusted, because otherwise the output will be sanitized just like +Markdown. + +Collaboration +************* + +When collaborating on a notebook, people probably want to see the +outputs produced by their colleagues' most recent executions. Since each +collaborator's key will differ, this will result in each share starting +in an untrusted state. There are three basic approaches to this: + +- re-run notebooks when you get them (not always viable) +- explicitly trust notebooks via ``jupyter trust`` or the notebook menu + (annoying, but easy) +- share a notebook signatures database, and use configuration dedicated to the + collaboration while working on the project. + +To share a signatures database among users, you can configure: + +.. code-block:: python + + c.NotebookNotary.data_dir = "/path/to/signature_dir" + +to specify a non-default path to the SQLite database (of notebook hashes, +essentially). \ No newline at end of file diff --git a/docs/source/other/changelog.rst b/docs/source/other/changelog.rst index 246b61a5d9..0043e19905 100644 --- a/docs/source/other/changelog.rst +++ b/docs/source/other/changelog.rst @@ -21,6 +21,17 @@ We strongly recommend that you upgrade to version 9+ of pip before upgrading ``j Use ``pip install pip --upgrade`` to upgrade pip. Check pip version with ``pip --version``. +.. _release-1.0.0: + +1.0.0 +----- + +- Extension discovery +- Classic server extension discovery and support +- Bug fixes +- Ready for users +- JupyterLab is the first server running on top of Jupyter Server + .. _release-0.0.2: 0.0.2 diff --git a/docs/source/other/full-config.rst b/docs/source/other/full-config.rst index f7f0cab4ba..10ddf72cc4 100644 --- a/docs/source/other/full-config.rst +++ b/docs/source/other/full-config.rst @@ -669,7 +669,7 @@ Session.unpacker : DottedObjectName Only used with custom functions for `packer`. Session.username : Unicode - Default: ``'zsailer'`` + Default: ``'echar4'`` Username for the Session. Default is your system username. @@ -685,6 +685,11 @@ MultiKernelManager.kernel_manager_class : DottedObjectName subclassing of the KernelManager for customized behavior. +MultiKernelManager.shared_context : Bool + Default: ``True`` + + Share a single zmq.Context to talk to all my kernels + MappingKernelManager.allowed_message_types : List Default: ``[]`` @@ -897,7 +902,7 @@ FileContentsManager.root_dir : Unicode No description -NotebookNotary.algorithm : 'md5'|'sha3_384'|'sha3_512'|'sha256'|'sha1'|'blake2s'|'sha3_256'|'sha3_224'|'sha384'|'sha512'|'blake2b'|'sha224' +NotebookNotary.algorithm : 'md5'|'sha3_512'|'blake2b'|'sha3_384'|'sha3_256'|'sha224'|'sha3_224'|'sha384'|'sha512'|'blake2s'|'sha1'|'sha256' Default: ``'sha256'`` The hashing algorithm used to sign notebooks. diff --git a/docs/source/users/index.rst b/docs/source/users/index.rst index 62675c2748..9abfe2f194 100644 --- a/docs/source/users/index.rst +++ b/docs/source/users/index.rst @@ -5,6 +5,7 @@ The Jupyter Server is a highly technical piece of the Jupyter Stack, so users pr .. toctree:: + :caption: Users :maxdepth: 1 :name: users