.. 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