clarify

[git.ikiwiki.info.git] / doc / plugins / contrib / compile.mdwn

diff --git a/doc/plugins/contrib/compile.mdwn b/doc/plugins/contrib/compile.mdwn
index 564f7f68c8a3320a101f861bf14bcbc233188326..d3139e9008899ecbd6d913f282cc6839651ea752 100644 (file)
--- a/doc/plugins/contrib/compile.mdwn
+++ b/doc/plugins/contrib/compile.mdwn
@@ -21,7 +21,9 @@ Some important security notice.
 - This plugins allows user to execute arbitrary commands when compiling the
   wiki.  Use at your own risk. If you use Ikiwiki as a static web site compiler
   (and not a wiki), and you are the only one to compile the wiki, there is no
-  risk.
+  risk. If you *do* allow untrusted users to edit or comment on the wiki, they
+  can use the `compile` directives to execute completely arbitrary code, regardless
+  of configuration safeguards you may put.
 
 - Source files are published, wheter option `source` is true or not. If
   `source` is false, source may not be *advertised*, but it is still available
@@ -30,6 +32,19 @@ Some important security notice.
   do not use this plugin if you do not want to publish your source files
     (sorry: I designed this plugin to publish free stuff).
 
+The plugin could be modified to only allow commands to be modified from the
+configuration and it would be safer to use. However, it would still be vulnerable
+to command injection attacks because it uses `qx()` command expansion, which
+runs commands through `/bin/sh -c`. A thorough security review would be in order
+before this should be considered secure running on untrusted input.
+
+A simpler implementation, that only runs a predefined set of commands, may be
+simpler to implement than auditing this whole plugin. For example, the
+[[bibtex2html]] module performs a similar task than the compile module, but
+hardcodes the command used and doesn't call it with `/bin/sh -c`. It could be
+expanded to cover more commands. See this
+[[plugins/contrib/bibtex2html/discussion/]] for a followup on this idea.
+
 ## Rationale
 
 I want to publish some latex files, both source (`.tex`) and compiled (`.pdf`)
@@ -91,6 +106,7 @@ using python-like string formatting, and described in the setup options section.
   advertised).
 - `template`: Name of the template to use (if set, the `source` option is
   irrelevant).
+- `var_*`: Any argument with a name starting with ``var_`` is transmitted to the command and template. For instance, if directive has argument ``var_foo=bar``, then string ``%{foo}s`` in the command will be replaced by ``bar``, and the template will have a variable named ``foo``, and ``<TMPL_VAR FOO>`` will be replaced by ``bar``.
 
 ### Extensions