Merge Security Pull Request: security-doc

Document the notebook security and trust model.

docs/source/notebook/index.rst

@@ -0,0 +1,13 b''
+====================
+The IPython notebook
+====================
+
+.. toctree::
+    :maxdepth: 2
+
+    notebook
+    cm_keyboard
+    nbconvert
+    public_server
+    security
+

docs/source/notebook/ipython_security.asc

@@ -0,0 +1,52 b''
+-----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-----

docs/source/notebook/security.rst

@@ -0,0 +1,146 b''
+Security in IPython notebooks
+=============================
+
+As IPython notebooks 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 introduces a
+security model to prevent execution of untrusted code without explicit
+user input.
+
+The problem
+-----------
+
+The whole point of IPython 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, an IPython 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
+--------------------
+
+IPython notebooks store a signature in metadata, which is used to answer
+the question "Did the current user do this?"
+
+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 in
+the IPython profile's security directory. By default, this is::
+
+    ~/.ipython/profile_default/security/notebook_secret
+
+When a notebook is opened by a user, the server computes a signature
+with the user's key, and compares it with the signature stored in the
+notebook's metadata. If the signature matches, 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 notebook file on disk 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::
+
+    ipython 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 with
+the 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 the
+code to properly implement the model described here, or a failure of the
+model itself, please report it to [e-mail].
+
+If you prefer to encrypt your security reports,
+you can use :download:`this PGP public key <ipython_security.asc>`.
+
+Affected use cases
+------------------
+
+Some use cases that work in IPython 1.0 will become less convenient in
+2.0 as a result of the security changes. We do our best to minimize
+these 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 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 <https://developers.google.com/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 ``ipython trust`` or the notebook menu
+   (annoying, but easy)
+-  share a notebook secret, and use an IPython profile dedicated to the
+   collaboration while working on the project.
+
+Multiple profiles or machines
+*****************************
+
+Since the notebook secret is stored in a profile directory by default,
+opening a notebook with a different profile or on a different machine
+will result in a different key, and thus be untrusted. The only current
+way to address this is by sharing the notebook secret. This can be
+facilitated by setting the configurable:
+
+.. sourcecode:: python
+
+    c.NotebookApp.secret_file = "/path/to/notebook_secret"
+
+in each profile, and only sharing the secret once per machine.

docs/source/_templates/notebook_redirect.html

@@ -1,9 +1,9 b''
 <html>
     <head>
-        <meta http-equiv="Refresh" content="0; url=notebook.html" />
-        <title>Notebook page has move</title>
-    </head> 
+        <meta http-equiv="Refresh" content="0; url=../notebook/index.html" />
+        <title>Notebook docs have moved</title>
+    </head>
     <body>
-        <p>The notebook page has moved to  <a href="notebook.html">this link</a>.</p>
+        <p>The notebook docs have moved <a href="../notebook/index.html">here</a>.</p>
     </body>
 </html>

docs/source/conf.py

@@ -1,246 +1,249 b''
 # -*- coding: utf-8 -*-
 #
 # IPython documentation build configuration file.
 
 # NOTE: This file has been edited manually from the auto-generated one from
 # sphinx.  Do NOT delete and re-generate.  If any changes from sphinx are
 # needed, generate a scratch one and merge by hand any new fields needed.
 
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
 # The contents of this file are pickled, so don't put values in the namespace
 # that aren't pickleable (module imports are okay, they're removed automatically).
 #
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
 import sys, os
 
 ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
 
 if ON_RTD:
     # Mock the presence of matplotlib, which we don't have on RTD
     # see
     # http://read-the-docs.readthedocs.org/en/latest/faq.html
     tags.add('rtd')
     
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../sphinxext'))
 
 # We load the ipython release info into a dict by explicit execution
 iprelease = {}
 execfile('../../IPython/core/release.py',iprelease)
 
 # General configuration
 # ---------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'matplotlib.sphinxext.mathmpl',
     'matplotlib.sphinxext.only_directives',
     'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.inheritance_diagram',
     'sphinx.ext.intersphinx',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'numpydoc',  # to preprocess docstrings
     'github',  # for easy GitHub links
 ]
 
 if ON_RTD:
     # Remove extensions not currently supported on RTD
     extensions.remove('matplotlib.sphinxext.only_directives')
     extensions.remove('matplotlib.sphinxext.mathmpl')
     extensions.remove('matplotlib.sphinxext.plot_directive')
     extensions.remove('IPython.sphinxext.ipython_directive')
     extensions.remove('IPython.sphinxext.ipython_console_highlighting')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
 if iprelease['_version_extra']:
     rst_prolog = """
     .. note::
 
         This documentation is for a development version of IPython. There may be
         significant differences from the latest stable release (1.2.1).
 
     """
 
 # The master toctree document.
 master_doc = 'index'
 
 # General substitutions.
 project = 'IPython'
 copyright = '2008, The IPython Development Team'
 
 # ghissue config
 github_project_url = "https://github.com/ipython/ipython"
 
 # numpydoc config
 numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
 numpydoc_class_members_toctree = False
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
 # The full version, including alpha/beta/rc tags.
 codename = iprelease['codename']
 release = "%s: %s" % (iprelease['version'], codename)
 # Just the X.Y.Z part, no '-dev'
 version = iprelease['version'].split('-', 1)[0]
 
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
 today_fmt = '%B %d, %Y'
 
 # List of documents that shouldn't be included in the build.
 #unused_docs = []
 
 # List of directories, relative to source directories, that shouldn't be searched
 # for source files.
 exclude_dirs = ['attic']
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 
 # Options for HTML output
 # -----------------------
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
 html_style = 'default.css'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
 
 # The name of an image file (within the static path) to place at the top of
 # the sidebar.
 #html_logo = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 html_additional_pages = {
-                         'interactive/htmlnotebook': 'htmlnotebook.html',
+    'interactive/htmlnotebook': 'notebook_redirect.html',
+    'interactive/notebook': 'notebook_redirect.html',
+    'interactive/nbconvert': 'notebook_redirect.html',
+    'interactive/public_server': 'notebook_redirect.html',
 }
 
 # If false, no module index is generated.
 #html_use_modindex = True
 
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ipythondoc'
 
 intersphinx_mapping = {'python': ('http://docs.python.org/2/', None)}
 
 # Options for LaTeX output
 # ------------------------
 
 # The paper size ('letter' or 'a4').
 latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
 latex_font_size = '11pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 
 latex_documents = [
     ('index', 'ipython.tex', 'IPython Documentation',
      ur"""The IPython Development Team""", 'manual', True),
     ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
      'Using IPython on Windows HPC Server 2008',
      ur"Brian E. Granger", 'manual', True)
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
 #latex_use_parts = False
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
 # If false, no module index is generated.
 latex_use_modindex = True
 
 
 # Options for texinfo output
 # --------------------------
 
 texinfo_documents = [
   (master_doc, 'ipython', 'IPython Documentation',
    'The IPython Development Team',
    'IPython',
    'IPython Documentation',
    'Programming',
    1),
 ]
 
 modindex_common_prefix = ['IPython.']
 
 
 # Cleanup
 # -------
 # delete release info to avoid pickling errors from sphinx
 
 del iprelease

docs/source/index.rst

@@ -1,38 +1,39 b''
 =====================
 IPython Documentation
 =====================
 
 .. htmlonly::
 
    :Release: |release|
    :Date: |today|
 
 .. only:: not rtd
 
     Welcome to the official IPython documentation.
 
 .. only:: rtd
 
     This is a partial copy of IPython documentation, please visit `IPython official documentation <http://ipython.org/documentation.html>`_.
 
 Contents
 ========
 
 .. toctree::
    :maxdepth: 1
 
    overview
    whatsnew/index
    install/index
    interactive/index
+   notebook/index
    parallel/index
    config/index
    development/index
    api/index
    about/index
 
 .. htmlonly::
    * :ref:`genindex`
    * :ref:`modindex`
    * :ref:`search`
 

docs/source/interactive/index.rst

@@ -1,18 +1,16 b''
 ==================================
 Using IPython for interactive work
 ==================================
 
 .. toctree::
    :maxdepth: 2
 
    tutorial
    tips
    reference
    shell
    qtconsole
-   notebook
-   cm_keyboard
-   nbconvert
-   public_server
 
+.. seealso::
 
+    :doc:`/notebook/index`

docs/source/notebook/public_server.rst

@@ -1,159 +1,159 b''
 .. _working_remotely:
 
 Running a notebook server
 =========================
 
 
 The  :ref:`IPython notebook <htmlnotebook>` web-application is based on a
 server-client structure.  This server uses a :ref:`two-process kernel
 architecture <ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
 HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
 and is accessible only from `localhost`. This document describes how you can
 :ref:`secure a notebook server <notebook_security>` and how to :ref:`run it on
 a public interface <notebook_public_server>`.
 
 .. _ZeroMQ: http://zeromq.org
 
 .. _Tornado: http://www.tornadoweb.org
 
 
 .. _notebook_security:
 
-Notebook security
------------------
+Securing a notebook server
+--------------------------
 
 You can protect your notebook server with a simple single password by
 setting the :attr:`NotebookApp.password` configurable. You can prepare a
 hashed password using the function :func:`IPython.lib.security.passwd`:
 
 .. sourcecode:: ipython
 
     In [1]: from IPython.lib import passwd
     In [2]: passwd()
     Enter password: 
     Verify password: 
     Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
     
 .. note::
 
   :func:`~IPython.lib.security.passwd` can also take the password as a string
   argument. **Do not** pass it as an argument inside an IPython session, as it
   will be saved in your input history.
 
 You can then add this to your :file:`ipython_notebook_config.py`, e.g.::
 
     # Password to use for web authentication
     c = get_config()
     c.NotebookApp.password = 
     u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
 
 When using a password, it is a good idea to also use SSL, so that your 
 password is not sent unencrypted by your browser. You can start the notebook 
 to communicate via a secure protocol mode using a self-signed certificate with 
 the command::
 
     $ ipython notebook --certfile=mycert.pem
 
 .. note::
 
     A self-signed certificate can be generated with ``openssl``.  For example, 
     the following command will create a certificate valid for 365 days with 
     both the key and certificate data written to the same file::
 
         $ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
 
 Your browser will warn you of a dangerous certificate because it is
 self-signed.  If you want to have a fully compliant certificate that will not
 raise warnings, it is possible (but rather involved) to obtain one,
 as explained in detail in `this tutorial`__.
 
 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
 	
 Keep in mind that when you enable SSL support, you will need to access the
 notebook server over ``https://``, not over plain ``http://``.  The startup
 message from the server prints this, but it is easy to overlook and think the
 server is for some reason non-responsive.
 
 
 .. _notebook_public_server:
 
 Running a public notebook server
 --------------------------------
 
 If you want to access your notebook server remotely via a web browser,
 you can do the following.  
 
 Start by creating a certificate file and a hashed password, as explained 
 above.  Then create a custom profile for the notebook, with the following 
 command line, type::
 
   $ ipython profile create nbserver
 
 In the profile directory just created, edit the file 
 ``ipython_notebook_config.py``.  By default, the file has all fields 
 commented; the minimum set you need to uncomment and edit is the following::
 
      c = get_config()
 
      # Kernel config
      c.IPKernelApp.pylab = 'inline'  # if you want plotting support always
 
      # Notebook config
      c.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem'
      c.NotebookApp.ip = '*'
      c.NotebookApp.open_browser = False
      c.NotebookApp.password = u'sha1:bcd259ccf...[your hashed password here]'
      # It is a good idea to put it on a known, fixed port
      c.NotebookApp.port = 9999
 
 You can then start the notebook and access it later by pointing your browser 
 to ``https://your.host.com:9999`` with ``ipython notebook 
 --profile=nbserver``.
 
 Running with a different URL prefix
 -----------------------------------
 
 The notebook dashboard (the landing page with an overview
 of the notebooks in your working directory) typically lives at the URL
 ``http://localhost:8888/``. If you prefer that it lives, together with the 
 rest of the notebook, under a sub-directory,
 e.g. ``http://localhost:8888/ipython/``, you can do so with
 configuration options like the following (see above for instructions about
 modifying ``ipython_notebook_config.py``)::
 
     c.NotebookApp.base_url = '/ipython/'
     c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}
 
 Using a different notebook store
 --------------------------------
 
 By default, the notebook server stores the notebook documents that it saves as 
 files in the working directory of the notebook server, also known as the
 ``notebook_dir``. This  logic is implemented in the 
 :class:`FileNotebookManager` class. However, the server can be configured to 
 use a different notebook manager class, which can 
 store the notebooks in a different format. 
 
 The bookstore_ package currently allows users to store notebooks on Rackspace
 CloudFiles or OpenStack Swift based object stores.
 
 Writing a notebook manager is as simple as extending the base class
 :class:`NotebookManager`. The simple_notebook_manager_ provides a great example
 of an in memory notebook manager, created solely for the purpose of
 illustrating the notebook manager API.
 
 .. _bookstore: https://github.com/rgbkrk/bookstore
 
 .. _simple_notebook_manager: https://github.com/khinsen/simple_notebook_manager
 
 Known issues
 ------------
 
 When behind a proxy, especially if your system or browser is set to autodetect
 the proxy, the notebook web application might fail to connect to the server's
 websockets, and present you with a warning at startup. In this case, you need
 to configure your system not to use the proxy for the server's address.
 
 For example, in Firefox, go to the Preferences panel, Advanced section,
 Network tab, click 'Settings...', and add the address of the notebook server
 to the 'No proxy for' field.