[latex3-commits] [git/LaTeX3-latex3-latex3] master: Add security warning to l3sys-shell (see #472) (9e6aaa678)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/9e6aaa6780cbdf2bea38b11b81e7c5ed808ffa41

>---------------------------------------------------------------

commit 9e6aaa6780cbdf2bea38b11b81e7c5ed808ffa41
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Thu Feb 25 18:26:00 2021 +0000

    Add security warning to l3sys-shell (see #472)


>---------------------------------------------------------------

9e6aaa6780cbdf2bea38b11b81e7c5ed808ffa41
 l3experimental/l3sys-shell/l3sys-shell.dtx | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/l3experimental/l3sys-shell/l3sys-shell.dtx b/l3experimental/l3sys-shell/l3sys-shell.dtx
index 9a7920fe3..a07efa8b1 100644
--- a/l3experimental/l3sys-shell/l3sys-shell.dtx
+++ b/l3experimental/l3sys-shell/l3sys-shell.dtx
@@ -52,6 +52,22 @@
 %
 % \begin{documentation}
 %
+% This module provides platform-neutral interfaces to system shell commands.
+% These functions can only access the shell if a document is proceeded using
+% \texttt{--shell-escape}, which allows \emph{unrestricted} access to command
+% line functions.
+%
+% In general, arbitrary documents should \emph{not} be processed in this way,
+% as shell escape could either accidentally or deliberately lead to unexpected
+% side-effects. In that sense, they should be treated like any other arbitrary
+% script: with caution. No attempt is made by the functions here to avoid
+% injection of additional commands into the arguments.
+%
+% With the above security caveats in mind, these functions are provided for
+% authors where a workflow scripting \emph{within} a \LaTeX{} document is
+% preferable to using an external script. The latter would of course also have
+% the ability to run arbitrary code.
+%
 % \begin{function}[added = 2018-07-28]{\sys_shell_cp:nn}
 %   \begin{syntax}
 %     \cs{sys_shell_cp:nn} \Arg{source} \Arg{dest}