| Server IP : 82.148.16.210 / Your IP : 216.73.216.19 Web Server : nginx/1.29.5 System : Linux mail.sarafai.ru 6.1.0-43-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.162-1 (2026-02-08) x86_64 User : root ( 0) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : OFF Directory : /proc/746/root/usr/share/doc/python3-docutils/docs/howto/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Deploying Docutils Securely</title>
<meta name="author" content="David Goodger" />
<meta name="date" content="2022-04-02" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="header">
<a class="reference external" href="https://docutils.sourceforge.io">Docutils</a> | <a class="reference external" href="../index.html">Overview</a> | <a class="reference external" href="../index.html#project-fundamentals">About</a> | <a class="reference external" href="../index.html#user">Users</a> | <a class="reference external" href="../index.html#ref">Reference</a> | <a class="reference external" href="../index.html#howto">Developers</a>
<hr class="header"/>
</div>
<div class="document" id="deploying-docutils-securely">
<h1 class="title">Deploying Docutils Securely</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Goodger</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2022-04-02</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>9051</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<!-- Minimal menu bar for inclusion in documentation sources
in ``docutils/docs/*/`` sub-diretories.
Attention: this is not a standalone document. -->
<div class="contents topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="toc-entry-1">Introduction</a></li>
<li><a class="reference internal" href="#the-issues" id="toc-entry-2">The Issues</a><ul>
<li><a class="reference internal" href="#file-creation" id="toc-entry-3">File Creation</a></li>
<li><a class="reference internal" href="#external-data-insertion" id="toc-entry-4">External Data Insertion</a></li>
<li><a class="reference internal" href="#raw-html-insertion" id="toc-entry-5">Raw HTML Insertion</a></li>
<li><a class="reference internal" href="#cpu-and-memory-utilization" id="toc-entry-6">CPU and memory utilization</a></li>
</ul>
</li>
<li><a class="reference internal" href="#securing-docutils" id="toc-entry-7">Securing Docutils</a><ul>
<li><a class="reference internal" href="#programmatically-via-application-default-settings" id="toc-entry-8">Programmatically Via Application Default Settings</a></li>
<li><a class="reference internal" href="#via-a-configuration-file" id="toc-entry-9">Via a Configuration File</a></li>
</ul>
</li>
<li><a class="reference internal" href="#version-applicability" id="toc-entry-10">Version Applicability</a></li>
<li><a class="reference internal" href="#related-documents" id="toc-entry-11">Related Documents</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#toc-entry-1">Introduction</a></h1>
<p>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 (<a class="reference external" href="../../FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax">blogs</a>, <a class="reference external" href="../../FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax">wikis</a>, content
management systems, and others), several security issues arose and
have been addressed. Still, <strong>Docutils does not come in a
through-the-web secure state</strong>, because this would inconvenience
ordinary users. This document provides pointers to help you secure
the Docutils software in your applications.</p>
</div>
<div class="section" id="the-issues">
<h1><a class="toc-backref" href="#toc-entry-2">The Issues</a></h1>
<div class="section" id="file-creation">
<h2><a class="toc-backref" href="#toc-entry-3">File Creation</a></h2>
<p>Docutils does not do any checks before writing to a file:</p>
<ul class="simple">
<li>Existing <strong>files are overwritten</strong> without asking!</li>
<li>Files may be <strong>written to any location</strong> accessible to the process.</li>
<li>There are <strong>no restrictions to</strong> the <strong>file names</strong>.</li>
</ul>
<p>Special care must be taken when allowing users to configure the <em>output
destination</em> or the <a class="reference external" href="../user/config.html#warning-stream">warning_stream</a>, <a class="reference external" href="../user/config.html#record-dependencies">record_dependencies</a>, or
<a class="reference external" href="../user/config.html#destination">_destination</a> settings.</p>
</div>
<div class="section" id="external-data-insertion">
<h2><a class="toc-backref" href="#toc-entry-4">External Data Insertion</a></h2>
<p>There are several <a class="reference external" href="../ref/rst/directives.html">reStructuredText directives</a> that can insert
external data (files and URLs) into the output document. These
directives are:</p>
<ul class="simple">
<li>"<a class="reference external" href="../ref/rst/directives.html#include">include</a>", by its very nature,</li>
<li>"<a class="reference external" href="../ref/rst/directives.html#raw-directive">raw</a>", through its <tt class="docutils literal">:file:</tt> and <tt class="docutils literal">:url:</tt> options,</li>
<li>"<a class="reference external" href="../ref/rst/directives.html#csv-table">csv-table</a>", through its <tt class="docutils literal">:file:</tt> and <tt class="docutils literal">:url:</tt> options,</li>
<li>"<a class="reference external" href="../ref/rst/directives.html#image">image</a>", if <a class="reference external" href="../user/config.html#embed-images">embed_images</a> is true.</li>
</ul>
<p>The "<a class="reference external" href="../ref/rst/directives.html#include">include</a>" directive and the other directives' file insertion
features can be disabled by setting "<a class="reference external" href="../user/config.html#file-insertion-enabled">file_insertion_enabled</a>" to
"<a class="reference external" href="../user/config.html#configuration-file-syntax">false</a>".</p>
</div>
<div class="section" id="raw-html-insertion">
<h2><a class="toc-backref" href="#toc-entry-5">Raw HTML Insertion</a></h2>
<p>The "<a class="reference external" href="../ref/rst/directives.html#raw-directive">raw</a>" 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 "<a class="reference external" href="../ref/rst/directives.html#raw-directive">raw</a>" directive can
be disabled by setting "<a class="reference external" href="../user/config.html#raw-enabled">raw_enabled</a>" to "false".</p>
</div>
<div class="section" id="cpu-and-memory-utilization">
<h2><a class="toc-backref" href="#toc-entry-6">CPU and memory utilization</a></h2>
<p>Parsing <strong>complex reStructuredText documents may require high
processing resources</strong>. This enables <cite>Denial of Service</cite> attacks using
specially crafted input.</p>
<p>It is recommended to enforce limits for the computation time and
resource utilization of the Docutils process when processing
untrusted input. In addition, the "<a class="reference external" href="../user/config.html#line-length-limit">line_length_limit</a>" can be
adapted.</p>
</div>
</div>
<div class="section" id="securing-docutils">
<h1><a class="toc-backref" href="#toc-entry-7">Securing Docutils</a></h1>
<div class="section" id="programmatically-via-application-default-settings">
<h2><a class="toc-backref" href="#toc-entry-8">Programmatically Via Application Default Settings</a></h2>
<p>If your application calls Docutils via one of the <a class="reference external" href="../api/publisher.html">convenience
functions</a>, you can pass a dictionary of default settings that
override the component defaults:</p>
<pre class="literal-block">
defaults = {'file_insertion_enabled': False,
'raw_enabled': False}
output = docutils.core.publish_string(
..., settings_overrides=defaults)
</pre>
<p>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 <tt class="docutils literal">_disable_config</tt>
setting:</p>
<pre class="literal-block">
defaults = {'file_insertion_enabled': False,
'raw_enabled': False,
'_disable_config': True}
output = docutils.core.publish_string(
..., settings_overrides=defaults)
</pre>
</div>
<div class="section" id="via-a-configuration-file">
<h2><a class="toc-backref" href="#toc-entry-9">Via a Configuration File</a></h2>
<p>You may secure Docutils via a configuration file:</p>
<ul class="simple">
<li>if your application executes one of the <a class="reference external" href="../user/tools.html">Docutils front-end tools</a>
as a separate process;</li>
<li>if you cannot or choose not to alter the source code of your
application or the component that calls Docutils; or</li>
<li>if you want to secure all Docutils deployments system-wide.</li>
</ul>
<p>If you call Docutils programmatically, it may be preferable to use the
methods described in the section above.</p>
<p>Docutils automatically looks in three places for a configuration file:</p>
<ul class="simple">
<li><tt class="docutils literal">/etc/docutils.conf</tt>, for system-wide configuration,</li>
<li><tt class="docutils literal">./docutils.conf</tt> (in the current working directory), for
project-specific configuration, and</li>
<li><tt class="docutils literal"><span class="pre">~/.docutils</span></tt> (in the user's home directory), for user-specific
configuration.</li>
</ul>
<p>These locations can be overridden by the <tt class="docutils literal">DOCUTILSCONFIG</tt>
environment variable. Details about configuration files, the purpose
of the various locations, and <tt class="docutils literal">DOCUTILSCONFIG</tt> are available in the
<a class="reference external" href="../user/config.html#configuration-files">"Configuration Files"</a> section of <a class="reference external" href="../user/config.html">Docutils Configuration</a>.</p>
<p>To fully secure a recent Docutils installation, the configuration file
should contain the following lines</p>
<pre class="literal-block">
[general]
file-insertion-enabled: off
raw-enabled: no
</pre>
<p>and untrusted users must be prevented to modify or create local
configuration files that overwrite these settings.</p>
</div>
</div>
<div class="section" id="version-applicability">
<h1><a class="toc-backref" href="#toc-entry-10">Version Applicability</a></h1>
<p>The "<a class="reference external" href="../user/config.html#file-insertion-enabled">file_insertion_enabled</a>" and "<a class="reference external" href="../user/config.html#raw-enabled">raw_enabled</a>" settings were added
to Docutils 0.3.9; previous versions will ignore these settings.</p>
<p>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):</p>
<pre class="literal-block">
[general]
file-insertion-enabled:
raw-enabled:
</pre>
<p>The bug was fixed with the 0.4.1 release on 2006-11-12.</p>
<p>The "<a class="reference external" href="../user/config.html#line-length-limit">line_length_limit</a>" is new in Docutils 0.17.</p>
</div>
<div class="section" id="related-documents">
<h1><a class="toc-backref" href="#toc-entry-11">Related Documents</a></h1>
<p><a class="reference external" href="../api/runtime-settings.html">Docutils Runtime Settings</a> explains the relationship between
component settings specifications, application settings
specifications, configuration files, and command-line options</p>
<p><a class="reference external" href="../user/config.html">Docutils Configuration</a> describes configuration files (locations,
structure, and syntax), and lists all settings and command-line
options.</p>
</div>
</div>
</body>
</html>