1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
.. include:: ../header.txt
=============================
Deploying Docutils Securely
=============================
:Author: David Goodger
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date: 2022-04-02 23:59:06 +0200 (Sa, 02. Apr 2022) $
:Revision: $Revision: 9051 $
:Copyright: This document has been placed in the public domain.
.. contents::
Introduction
============
Initially, Docutils was intended for command-line tools and
single-user applications. Through-the-web editing and processing was
not envisaged, therefore web security was not a consideration. Once
Docutils/reStructuredText started being incorporated into an
ever-increasing number of web applications (blogs__, wikis__, content
management systems, and others), several security issues arose and
have been addressed. Still, **Docutils does not come in a
through-the-web secure state**, because this would inconvenience
ordinary users. This document provides pointers to help you secure
the Docutils software in your applications.
__ ../../FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
__ ../../FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
The Issues
==========
File Creation
-------------
Docutils does not do any checks before writing to a file:
* Existing **files are overwritten** without asking!
* Files may be **written to any location** accessible to the process.
* There are **no restrictions to** the **file names**.
Special care must be taken when allowing users to configure the *output
destination* or the `warning_stream`_, `record_dependencies`_, or
`_destination`_ settings.
.. _warning_stream: ../user/config.html#warning-stream
.. _record_dependencies: ../user/config.html#record-dependencies
.. _`_destination`: ../user/config.html#destination
External Data Insertion
-----------------------
There are several `reStructuredText directives`_ that can insert
external data (files and URLs) into the output document. These
directives are:
* "include_", by its very nature,
* "raw_", through its ``:file:`` and ``:url:`` options,
* "csv-table_", through its ``:file:`` and ``:url:`` options,
* "image_", if `embed_images`_ is true.
The "include_" directive and the other directives' file insertion
features can be disabled by setting "file_insertion_enabled_" to
"false__".
__ ../user/config.html#configuration-file-syntax
.. _reStructuredText directives: ../ref/rst/directives.html
.. _include: ../ref/rst/directives.html#include
.. _raw: ../ref/rst/directives.html#raw-directive
.. _csv-table: ../ref/rst/directives.html#csv-table
.. _image: ../ref/rst/directives.html#image
.. _embed_images: ../user/config.html#embed-images
.. _file_insertion_enabled: ../user/config.html#file-insertion-enabled
Raw HTML Insertion
------------------
The "raw_" directive is intended for the insertion of
non-reStructuredText data that is passed untouched to the Writer.
This directive can be abused to bypass site features or insert
malicious JavaScript code into a web page. The "raw_" directive can
be disabled by setting "raw_enabled_" to "false".
.. _raw_enabled: ../user/config.html#raw-enabled
CPU and memory utilization
--------------------------
Parsing **complex reStructuredText documents may require high
processing resources**. This enables `Denial of Service` attacks using
specially crafted input.
It is recommended to enforce limits for the computation time and
resource utilization of the Docutils process when processing
untrusted input. In addition, the "line_length_limit_" can be
adapted.
.. _line_length_limit: ../user/config.html#line-length-limit
Securing Docutils
=================
Programmatically Via Application Default Settings
-------------------------------------------------
If your application calls Docutils via one of the `convenience
functions`_, you can pass a dictionary of default settings that
override the component defaults::
defaults = {'file_insertion_enabled': False,
'raw_enabled': False}
output = docutils.core.publish_string(
..., settings_overrides=defaults)
Note that these defaults can be overridden by configuration files (and
command-line options if applicable). If this is not desired, you can
disable configuration file processing with the ``_disable_config``
setting::
defaults = {'file_insertion_enabled': False,
'raw_enabled': False,
'_disable_config': True}
output = docutils.core.publish_string(
..., settings_overrides=defaults)
.. _convenience functions: ../api/publisher.html
Via a Configuration File
------------------------
You may secure Docutils via a configuration file:
* if your application executes one of the `Docutils front-end tools`_
as a separate process;
* if you cannot or choose not to alter the source code of your
application or the component that calls Docutils; or
* if you want to secure all Docutils deployments system-wide.
If you call Docutils programmatically, it may be preferable to use the
methods described in the section above.
Docutils automatically looks in three places for a configuration file:
* ``/etc/docutils.conf``, for system-wide configuration,
* ``./docutils.conf`` (in the current working directory), for
project-specific configuration, and
* ``~/.docutils`` (in the user's home directory), for user-specific
configuration.
These locations can be overridden by the ``DOCUTILSCONFIG``
environment variable. Details about configuration files, the purpose
of the various locations, and ``DOCUTILSCONFIG`` are available in the
`"Configuration Files"`_ section of `Docutils Configuration`_.
To fully secure a recent Docutils installation, the configuration file
should contain the following lines ::
[general]
file-insertion-enabled: off
raw-enabled: no
and untrusted users must be prevented to modify or create local
configuration files that overwrite these settings.
.. _Docutils front-end tools: ../user/tools.html
.. _"Configuration Files": ../user/config.html#configuration-files
.. _Docutils Configuration: ../user/config.html
Version Applicability
=====================
The "file_insertion_enabled_" and "raw_enabled_" settings were added
to Docutils 0.3.9; previous versions will ignore these settings.
A bug existed in the configuration file handling of these settings in
Docutils 0.4 and earlier: the right-hand-side needed to be left blank
(no values)::
[general]
file-insertion-enabled:
raw-enabled:
The bug was fixed with the 0.4.1 release on 2006-11-12.
The "line_length_limit_" is new in Docutils 0.17.
Related Documents
=================
`Docutils Runtime Settings`_ explains the relationship between
component settings specifications, application settings
specifications, configuration files, and command-line options
`Docutils Configuration`_ describes configuration files (locations,
structure, and syntax), and lists all settings and command-line
options.
.. _Docutils Runtime Settings: ../api/runtime-settings.html
|
