1 =============================
2 Deploying Docutils Securely
3 =============================
6 :Contact: goodger@python.org
9 :Copyright: This document has been placed in the public domain.
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.
25 Docutils does not come in a through-the-web secure state, because this
26 would inconvenience ordinary users
28 __ ../../FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
29 __ ../../FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
35 External Data Insertion
36 -----------------------
38 There are several `reStructuredText directives`_ that can insert
39 external data (files and URLs) into the immediate document. These
42 * "include_", by its very nature
43 * "raw_", through its ``:file:`` and ``:url:`` options
44 * "csv-table_", through its ``:file:`` and ``:url:`` options
46 The "include_" directive and the other directives' file insertion
47 features can be disabled by setting "file_insertion_enabled_" to
50 .. _reStructuredText directives: ../ref/rst/directives.html
51 .. _include: ../ref/rst/directives.html#include
52 .. _raw: ../ref/rst/directives.html#raw
53 .. _csv-table: ../ref/rst/directives.html#csv-table
54 .. _file_insertion_enabled: ../user/config.html#file-insertion-enabled
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.
66 .. _raw_enabled: ../user/config.html#raw-enabled
72 Programmatically Via Application Default Settings
73 -------------------------------------------------
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::
79 defaults = {'file_insertion_enabled': 0,
81 output = docutils.core.publish_string(
82 ..., settings_overrides=defaults)
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``
89 defaults = {'file_insertion_enabled': 0,
92 output = docutils.core.publish_string(
93 ..., settings_overrides=defaults)
95 .. _convenience functions: ../api/publisher.html
98 Via a Configuration File
99 ------------------------
101 You should secure Docutils via a configuration file:
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.
109 If you call Docutils programmatically, it may be preferable to use the
110 methods described in section below.
112 Docutils automatically looks in three places for a configuration file:
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
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`_.
125 To fully secure your Docutils installation, the configuration file
126 should contain the following lines::
129 file-insertion-enabled:
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::
139 file-insertion-enabled: off
142 .. _Docutils front-end tools: ../user/tools.html
143 .. _"Configuration Files": ../user/config.html#configuration-files
144 .. _Docutils Configuration: ../user/config.html
147 Version Applicability
148 =====================
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
160 `Docutils Runtime Settings`_ explains the relationship between
161 component settings specifications, application settings
162 specifications, configuration files, and command-line options
164 `Docutils Configuration`_ describes configuration files (locations,
165 structure, and syntax), and lists all settings and command-line
168 .. _Docutils Runtime Settings: ../api/runtime-settings.html