As IPython notebooks become more popular for sharing and collaboration,the potential for malicious people to attempt to exploit the notebookfor their nefarious purposes increases. IPython 2.0 introduces asecurity model to prevent execution of untrusted code without explicituser input.
A Jupyter Notebook of Markdown examples given in the book can be downloaded here: jupyter-markdown.zip: the Notebook and associated media files. A static HTML version of the Notebook. Note: As of April 2015, IPython Notebook has evolved into part of the Jupyter Project. Markdown IPython Notebook. Contribute to mli/notedown development by creating an account on GitHub.
The problem¶
The whole point of IPython is arbitrary code execution. We have nodesire to limit what can be done with a notebook, which would negativelyimpact its utility.
Unlike other programs, an IPython notebook document includes output.Unlike other documents, that output exists in a context that can executecode (via Javascript).
The security problem we need to solve is that no code should executejust because a user has opened a notebook that they did notwrite. Like any other program, once a user decides to execute code ina notebook, it is considered trusted, and should be allowed to doanything.
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 byothers) is never trusted
- The central question of trust is “Did the current user do this?”
The details of trust¶
IPython notebooks store a signature in metadata, which is used to answerthe question “Did the current user do this?” Memory clean 2 vs 3.
This signature is a digest of the notebooks contents plus a secret key,known only to the user. The secret key is a user-only readable file inthe IPython profile’s security directory. By default, this is:
Note
The notebook secret being stored in the profile means thatloading a notebook in another profile results in it being untrusted,unless you copy or symlink the notebook secret to share it across profiles.
When a notebook is opened by a user, the server computes a signaturewith the user’s key, and compares it with the signature stored in thenotebook’s metadata. If the signature matches, HTML and Javascriptoutput in the notebook will be trusted at load, otherwise it will beuntrusted.
Any output generated during an interactive session is trusted.
Updating trust¶
A notebook’s trust is updated when the notebook is saved. If there areany untrusted outputs still in the notebook, the notebook will not betrusted, and no signature will be stored. If all untrusted outputs havebeen removed (either via ClearOutput or re-execution), then thenotebook will become trusted.
While trust is updated per output, this is only for the duration of asingle session. A notebook file on disk is either trusted or not in itsentirety.
Explicit trust¶
Sometimes re-executing a notebook to generate trusted output is not anoption, either because dependencies are unavailable, or it would take along time. Users can explicitly trust a notebook in two ways:
Ipython Notebook Online
At the command-line, with:
After loading the untrusted notebook, with
File/TrustNotebook
These two methods simply load the notebook, compute a new signature withthe user’s key, and then store the newly signed notebook.
Reporting security issues¶
If you find a security vulnerability in IPython, either a failure of thecode to properly implement the model described here, or a failure of themodel itself, please report it to security@ipython.org.
If you prefer to encrypt your security reports,you can use thisPGPpublickey.
Affected use cases¶
Some use cases that work in IPython 1.0 will become less convenient in2.0 as a result of the security changes. We do our best to minimizethese annoyance, but security is always at odds with convenience.
Javascript and CSS in Markdown cells¶
While never officially supported, it had become common practice to puthidden Javascript or CSS styling in Markdown cells, so that they wouldnot be visible on the page. Since Markdown cells are now sanitized (byGoogle 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 meantimestyling the notebook can only be done via either custom.css or CSSin HTML output. The latter only have an effect if the notebook istrusted, because otherwise the output will be sanitized just likeMarkdown.
Collaboration¶
When collaborating on a notebook, people probably want to see theoutputs produced by their colleagues’ most recent executions. Since eachcollaborator’s key will differ, this will result in each share startingin an untrusted state. There are three basic approaches to this:
- re-run notebooks when you get them (not always viable)
- explicitly trust notebooks via
ipythontrustor the notebook menu(annoying, but easy) - share a notebook secret, and use an IPython profile dedicated to thecollaboration while working on the project.
Multiple profiles or machines¶
Ipython Notebook Markdown Bold Text
Twiends reviews. Since the notebook secret is stored in a profile directory by default,opening a notebook with a different profile or on a different machinewill result in a different key, and thus be untrusted. The only currentway to address this is by sharing the notebook secret. This can befacilitated by setting the configurable:
Ipython
in each profile, and only sharing the secret once per machine.