Author: | David Goodger |
---|---|
Contact: | docutils-develop@lists.sourceforge.net |
Date: | 2022-04-02 |
Revision: | 9051 |
Copyright: | This document has been placed in the public domain. |
Contents
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.
Docutils does not do any checks before writing to a file:
Special care must be taken when allowing users to configure the output destination or the warning_stream, record_dependencies, or _destination settings.
There are several reStructuredText directives that can insert external data (files and URLs) into the output document. These directives are:
The "include" directive and the other directives' file insertion features can be disabled by setting "file_insertion_enabled" to "false".
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".
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.
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)
You may secure Docutils via a configuration file:
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:
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.
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.