| Server IP : 127.0.0.2 / Your IP : 18.222.48.95 Web Server : Apache/2.4.18 (Ubuntu) System : User : www-data ( ) PHP Version : 7.0.33-0ubuntu0.16.04.16 Disable Function : disk_free_space,disk_total_space,diskfreespace,dl,exec,fpaththru,getmyuid,getmypid,highlight_file,ignore_user_abord,leak,listen,link,opcache_get_configuration,opcache_get_status,passthru,pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,php_uname,phpinfo,posix_ctermid,posix_getcwd,posix_getegid,posix_geteuid,posix_getgid,posix_getgrgid,posix_getgrnam,posix_getgroups,posix_getlogin,posix_getpgid,posix_getpgrp,posix_getpid,posix,_getppid,posix_getpwnam,posix_getpwuid,posix_getrlimit,posix_getsid,posix_getuid,posix_isatty,posix_kill,posix_mkfifo,posix_setegid,posix_seteuid,posix_setgid,posix_setpgid,posix_setsid,posix_setuid,posix_times,posix_ttyname,posix_uname,pclose,popen,proc_open,proc_close,proc_get_status,proc_nice,proc_terminate,shell_exec,source,show_source,system,virtual MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/docutils-doc/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.12: http://docutils.sourceforge.net/" />
<title>Deploying Docutils Securely</title>
<meta name="author" content="David Goodger" />
<meta name="date" content="2012-01-03" />
<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="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>2012-01-03</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>7302</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li>
<li><a class="reference internal" href="#the-issues" id="id4">The Issues</a><ul>
<li><a class="reference internal" href="#external-data-insertion" id="id5">External Data Insertion</a></li>
<li><a class="reference internal" href="#raw-html-insertion" id="id6">Raw HTML Insertion</a></li>
</ul>
</li>
<li><a class="reference internal" href="#securing-docutils" id="id7">Securing Docutils</a><ul>
<li><a class="reference internal" href="#programmatically-via-application-default-settings" id="id8">Programmatically Via Application Default Settings</a></li>
<li><a class="reference internal" href="#via-a-configuration-file" id="id9">Via a Configuration File</a></li>
</ul>
</li>
<li><a class="reference internal" href="#version-applicability" id="id10">Version Applicability</a></li>
<li><a class="reference internal" href="#related-documents" id="id11">Related Documents</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id3">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. This document provides instructions to help you
secure the Docutils software in your applications.</p>
<p>Docutils does not come in a through-the-web secure state, because this
would inconvenience ordinary users</p>
</div>
<div class="section" id="the-issues">
<h1><a class="toc-backref" href="#id4">The Issues</a></h1>
<div class="section" id="external-data-insertion">
<h2><a class="toc-backref" href="#id5">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 immediate 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>
</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
0/false.</p>
</div>
<div class="section" id="raw-html-insertion">
<h2><a class="toc-backref" href="#id6">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 0/false.</p>
</div>
</div>
<div class="section" id="securing-docutils">
<h1><a class="toc-backref" href="#id7">Securing Docutils</a></h1>
<div class="section" id="programmatically-via-application-default-settings">
<h2><a class="toc-backref" href="#id8">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': 0,
'raw_enabled': 0}
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': 0,
'raw_enabled': 0,
'_disable_config': 1}
output = docutils.core.publish_string(
..., settings_overrides=defaults)
</pre>
</div>
<div class="section" id="via-a-configuration-file">
<h2><a class="toc-backref" href="#id9">Via a Configuration File</a></h2>
<p>You should 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 section below.</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 your Docutils installation, the configuration file
should contain the following lines:</p>
<pre class="literal-block">
[general]
file-insertion-enabled:
raw-enabled:
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p>Due to a bug in the definitions of these security-related
settings, the right-hand-side of the above lines (the values)
should be left blank, as shown. The bug was corrected on
2006-11-12 and is reflected in Docutils releases 0.4.1 and higher.
In these versions, more verbose forms may be used, such as:</p>
<pre class="last literal-block">
[general]
file-insertion-enabled: off
raw-enabled: no
</pre>
</div>
</div>
</div>
<div class="section" id="version-applicability">
<h1><a class="toc-backref" href="#id10">Version Applicability</a></h1>
<p>The <tt class="docutils literal">file_insertion_enabled</tt> & <tt class="docutils literal">raw_enabled</tt> 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 bug was fixed with the 0.4.1 release on
2006-11-12.</p>
</div>
<div class="section" id="related-documents">
<h1><a class="toc-backref" href="#id11">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>