# Deploying Docutils Securely

Author:

  David Goodger

Contact:
  docutils-develop@lists.sourceforge.net
Date:
  2025-12-14
Revision:
  10272
Copyright:
  This document has been placed in the public domain.

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

## 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 (or _destination), warning_stream, or record_dependencies settings.

### External Data Insertion

There are several reStructuredText directives that can insert external data (files or content fetched from a URL) 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" through its :loading: option.

The "include" directive and the other directives' file insertion features can be disabled by setting "file_insertion_enabled" to "false".

### Raw HTML Insertion

Content of the "raw" directive is passed untouched to the Writer. Docutils standard writers insert "raw" content with matching format into the output document without any checks or changes. This can be abused to bypass site features or insert malicious script code into a web page.

A web-secure Writer must ignore or sanitize "raw" content. Alternatively, the "raw" directive can be disabled by setting "raw_enabled" to "false".

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

## 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)

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

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