docutils/docs/howto/security.txt

   1 =============================
   2  Deploying Docutils Securely
   3 =============================
   4
   5 :Author: David Goodger
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Date: $Date$
   8 :Revision: $Revision$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. contents::
  12
  13 Introduction
  14 ============
  15
  16 Initially, Docutils was intended for command-line tools and
  17 single-user applications.  Through-the-web editing and processing was
  18 not envisaged, therefore web security was not a consideration.  Once
  19 Docutils/reStructuredText started being incorporated into an
  20 ever-increasing number of web applications (blogs__, wikis__, content
  21 management systems, and others), several security issues arose and
  22 have been addressed.  This document provides instructions to help you
  23 secure the Docutils software in your applications.
  24
  25 Docutils does not come in a through-the-web secure state, because this
  26 would inconvenience ordinary users
  27
  28 __ ../../FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
  29 __ ../../FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
  30
  31
  32 The Issues
  33 ==========
  34
  35 External Data Insertion
  36 -----------------------
  37
  38 There are several `reStructuredText directives`_ that can insert
  39 external data (files and URLs) into the immediate document.  These
  40 directives are:
  41
  42 * "include_", by its very nature
  43 * "raw_", through its ``:file:`` and ``:url:`` options
  44 * "csv-table_", through its ``:file:`` and ``:url:`` options
  45
  46 The "include_" directive and the other directives' file insertion
  47 features can be disabled by setting "file_insertion_enabled_" to
  48 0/false.
  49
  50 .. _reStructuredText directives: ../ref/rst/directives.html
  51 .. _include: ../ref/rst/directives.html#include
  52 .. _raw: ../ref/rst/directives.html#raw-directive
  53 .. _csv-table: ../ref/rst/directives.html#csv-table
  54 .. _file_insertion_enabled: ../user/config.html#file-insertion-enabled
  55
  56
  57 Raw HTML Insertion
  58 ------------------
  59
  60 The "raw_" directive is intended for the insertion of
  61 non-reStructuredText data that is passed untouched to the Writer.
  62 This directive can be abused to bypass site features or insert
  63 malicious JavaScript code into a web page.  The "raw_" directive can
  64 be disabled by setting "raw_enabled_" to 0/false.
  65
  66 .. _raw_enabled: ../user/config.html#raw-enabled
  67
  68
  69 Securing Docutils
  70 =================
  71
  72 Programmatically Via Application Default Settings
  73 -------------------------------------------------
  74
  75 If your application calls Docutils via one of the `convenience
  76 functions`_, you can pass a dictionary of default settings that
  77 override the component defaults::
  78
  79     defaults = {'file_insertion_enabled': 0,
  80                 'raw_enabled': 0}
  81     output = docutils.core.publish_string(
  82         ..., settings_overrides=defaults)
  83
  84 Note that these defaults can be overridden by configuration files (and
  85 command-line options if applicable).  If this is not desired, you can
  86 disable configuration file processing with the ``_disable_config``
  87 setting::
  88
  89     defaults = {'file_insertion_enabled': 0,
  90                 'raw_enabled': 0,
  91                 '_disable_config': 1}
  92     output = docutils.core.publish_string(
  93         ..., settings_overrides=defaults)
  94
  95 .. _convenience functions: ../api/publisher.html
  96
  97
  98 Via a Configuration File
  99 ------------------------
 100
 101 You should secure Docutils via a configuration file:
 102
 103 * if your application executes one of the `Docutils front-end tools`_
 104   as a separate process;
 105 * if you cannot or choose not to alter the source code of your
 106   application or the component that calls Docutils; or
 107 * if you want to secure all Docutils deployments system-wide.
 108
 109 If you call Docutils programmatically, it may be preferable to use the
 110 methods described in section below.
 111
 112 Docutils automatically looks in three places for a configuration file:
 113
 114 * ``/etc/docutils.conf``, for system-wide configuration,
 115 * ``./docutils.conf`` (in the current working directory), for
 116   project-specific configuration, and
 117 * ``~/.docutils`` (in the user's home directory), for user-specific
 118   configuration.
 119
 120 These locations can be overridden by the ``DOCUTILSCONFIG``
 121 environment variable.  Details about configuration files, the purpose
 122 of the various locations, and ``DOCUTILSCONFIG`` are available in the
 123 `"Configuration Files"`_ section of `Docutils Configuration`_.
 124
 125 To fully secure your Docutils installation, the configuration file
 126 should contain the following lines::
 127
 128     [general]
 129     file-insertion-enabled:
 130     raw-enabled:
 131
 132 .. Note:: Due to a bug in the definitions of these security-related
 133    settings, the right-hand-side of the above lines (the values)
 134    should be left blank, as shown.  The bug was corrected on
 135    2006-11-12 and is reflected in Docutils releases 0.4.1 and higher.
 136    In these versions, more verbose forms may be used, such as::
 137
 138        [general]
 139        file-insertion-enabled: off
 140        raw-enabled: no
 141
 142 .. _Docutils front-end tools: ../user/tools.html
 143 .. _"Configuration Files": ../user/config.html#configuration-files
 144 .. _Docutils Configuration: ../user/config.html
 145
 146
 147 Version Applicability
 148 =====================
 149
 150 The ``file_insertion_enabled`` & ``raw_enabled`` settings were added
 151 to Docutils 0.3.9; previous versions will ignore these settings.  A
 152 bug existed in the configuration file handling of these settings in
 153 Docutils 0.4 and earlier.  The bug was fixed with the 0.4.1 release on
 154 2006-11-12.
 155
 156
 157 Related Documents
 158 =================
 159
 160 `Docutils Runtime Settings`_ explains the relationship between
 161 component settings specifications, application settings
 162 specifications, configuration files, and command-line options
 163
 164 `Docutils Configuration`_ describes configuration files (locations,
 165 structure, and syntax), and lists all settings and command-line
 166 options.
 167
 168 .. _Docutils Runtime Settings: ../api/runtime-settings.html