44387, edited: describe some problems with restricted mode

1 files changed, 45 insertions, 0 deletions

diff --git a/Doc/Zsh/restricted.yo b/Doc/Zsh/restricted.yo
index 6cf9b36b5..33dfc96c6 100644
--- a/Doc/Zsh/restricted.yo
+++ b/Doc/Zsh/restricted.yo
@@ -37,3 +37,48 @@ Restricted mode can also be activated any time by setting the
 tt(RESTRICTED) option.  This immediately enables all the restrictions
 described above even if the shell still has not processed all startup
 files.
+
+A shell em(Restricted Mode) is an outdated way to restrict what users may
+do:  modern systems have better, safer and more reliable ways to
+confine user actions, such as em(chroot jails), em(containers) and
+em(zones).
+
+A restricted shell is very difficult to implement safely.  The feature
+may be removed in a future version of zsh.
+
+It is important to realise that the restrictions only apply to the shell,
+not to the commands it runs (except for some shell builtins).  While a
+restricted shell can only run the restricted list of commands accessible
+via the predefined `tt(PATH)' variable, it does not prevent those
+commands from running any other command.
+
+As an example, if `tt(env)' is among the list of em(allowed) commands,
+then it allows the user to run any command as `tt(env)' is not a shell
+builtin command and can run arbitrary executables.
+
+So when implementing a restricted shell framework it is important to be
+fully aware of what actions each of the em(allowed) commands or features
+(which may be regarded as em(modules)) can perform.
+
+Many commands can have their behaviour affected by environment
+variables.  Except for the few listed above, zsh does not restrict
+the setting of environment variables.
+
+If a `tt(perl)', `tt(python)', `tt(bash)', or other general purpose
+interpreted script it treated as a restricted
+command, the user can work around the restriction by
+setting specially crafted `tt(PERL5LIB)', `tt(PYTHONPATH)',
+`tt(BASHENV)' (etc.) environment variables. On GNU systems, any
+command can be made to run arbitrary code when performing character set
+conversion (including zsh itself) by setting a `tt(GCONV_PATH)'
+environment variable.  Those are only a few examples.
+
+Bear in mind that, contrary to some other shells, `tt(readonly)' is not a
+security feature in zsh as it can be undone and so cannot be used to
+mitigate the above.
+
+A restricted shell only works if the allowed commands are few
+and carefully written so as not to grant more access to users than
+intended.  It is also important to restrict what zsh module the user may
+load as some of them, such as `tt(zsh/system)', `tt(zsh/mapfile)' and
+`tt(zsh/files)', allow bypassing most of the restrictions.