Documentation update. Warn about file overwriting.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@8640 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 44 insertions, 23 deletions

diff --git a/docutils/docs/howto/security.txt b/docutils/docs/howto/security.txt
index 2088f937a..6787439cf 100644
--- a/docutils/docs/howto/security.txt
+++ b/docutils/docs/howto/security.txt
@@ -19,11 +19,10 @@ 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.  This document provides instructions to help you
-secure the Docutils software in your applications.
-
-**Docutils does not come in a through-the-web secure state**, because this
-would inconvenience ordinary users.
+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
@@ -32,25 +31,47 @@ __ ../../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 immediate document.  These
+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
+* "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
-0/false.
+"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
 
 
@@ -61,7 +82,7 @@ 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.
+be disabled by setting "raw_enabled_" to "false".
 
 .. _raw_enabled: ../user/config.html#raw-enabled
 
@@ -69,14 +90,14 @@ be disabled by setting "raw_enabled_" to 0/false.
 CPU and memory utilization
 --------------------------
 
-Parsing complex reStructuredText documents may require high processing
-ressources. This enables `Denial of Service` attacs 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.
+Parsing **complex reStructuredText documents may require high
+processing ressources**. This enables `Denial of Service` attacs using
+specially crafted input.
 
-In addition, the "line_length_limit_" can be adapted.
+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
 
@@ -91,8 +112,8 @@ 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}
+    defaults = {'file_insertion_enabled': False,
+                'raw_enabled': False}
     output = docutils.core.publish_string(
         ..., settings_overrides=defaults)
 
@@ -101,9 +122,9 @@ 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}
+    defaults = {'file_insertion_enabled': False,
+                'raw_enabled': False,
+                '_disable_config': True}
     output = docutils.core.publish_string(
         ..., settings_overrides=defaults)