External Data Insertion

There are several reStructuredText directives that can insert external data (files and URLs) into the immediate document. These directives are:

• "include", by its very nature
• "raw", through its :file: and :url: options
• "csv-table", through its :file: and :url: options

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

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 0/false.

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': 0,
            'raw_enabled': 0}
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': 0,
            'raw_enabled': 0,
            '_disable_config': 1}
output = docutils.core.publish_string(
    ..., settings_overrides=defaults)

Via a Configuration File

You should 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 section below.

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 your Docutils installation, the configuration file should contain the following lines:

[general]
file-insertion-enabled:
raw-enabled:

[general]
file-insertion-enabled: off
raw-enabled: no