diff options
Diffstat (limited to 'Doc/librexec.tex')
| -rw-r--r-- | Doc/librexec.tex | 221 |
1 files changed, 0 insertions, 221 deletions
diff --git a/Doc/librexec.tex b/Doc/librexec.tex deleted file mode 100644 index baddece..0000000 --- a/Doc/librexec.tex +++ /dev/null @@ -1,221 +0,0 @@ -\section{Standard Module \module{rexec}} -\label{module-rexec} -\stmodindex{rexec} - - -This module contains the \class{RExec} class, which supports -\method{r_exec()}, \method{r_eval()}, \method{r_execfile()}, and -\method{r_import()} methods, which are restricted versions of the standard -Python functions \method{exec()}, \method{eval()}, \method{execfile()}, and -the \keyword{import} statement. -Code executed in this restricted environment will -only have access to modules and functions that are deemed safe; you -can subclass \class{RExec} to add or remove capabilities as desired. - -\emph{Note:} The \class{RExec} class can prevent code from performing -unsafe operations like reading or writing disk files, or using TCP/IP -sockets. However, it does not protect against code using extremely -large amounts of memory or CPU time. - -\begin{classdesc}{RExec}{\optional{hooks\optional{, verbose}}} -Returns an instance of the \class{RExec} class. - -\var{hooks} is an instance of the \class{RHooks} class or a subclass of it. -If it is omitted or \code{None}, the default \class{RHooks} class is -instantiated. -Whenever the \module{RExec} module searches for a module (even a -built-in one) or reads a module's code, it doesn't actually go out to -the file system itself. Rather, it calls methods of an \class{RHooks} -instance that was passed to or created by its constructor. (Actually, -the \class{RExec} object doesn't make these calls --- they are made by -a module loader object that's part of the \class{RExec} object. This -allows another level of flexibility, e.g. using packages.) - -By providing an alternate \class{RHooks} object, we can control the -file system accesses made to import a module, without changing the -actual algorithm that controls the order in which those accesses are -made. For instance, we could substitute an \class{RHooks} object that -passes all filesystem requests to a file server elsewhere, via some -RPC mechanism such as ILU. Grail's applet loader uses this to support -importing applets from a URL for a directory. - -If \var{verbose} is true, additional debugging output may be sent to -standard output. -\end{classdesc} - -The \class{RExec} class has the following class attributes, which are -used by the \method{__init__()} method. Changing them on an existing -instance won't have any effect; instead, create a subclass of -\class{RExec} and assign them new values in the class definition. -Instances of the new class will then use those new values. All these -attributes are tuples of strings. - -\begin{memberdesc}{nok_builtin_names} -Contains the names of built-in functions which will \emph{not} be -available to programs running in the restricted environment. The -value for \class{RExec} is \code{('open',} \code{'reload',} -\code{'__import__')}. (This gives the exceptions, because by far the -majority of built-in functions are harmless. A subclass that wants to -override this variable should probably start with the value from the -base class and concatenate additional forbidden functions --- when new -dangerous built-in functions are added to Python, they will also be -added to this module.) -\end{memberdesc} - -\begin{memberdesc}{ok_builtin_modules} -Contains the names of built-in modules which can be safely imported. -The value for \class{RExec} is \code{('audioop',} \code{'array',} -\code{'binascii',} \code{'cmath',} \code{'errno',} \code{'imageop',} -\code{'marshal',} \code{'math',} \code{'md5',} \code{'operator',} -\code{'parser',} \code{'regex',} \code{'rotor',} \code{'select',} -\code{'strop',} \code{'struct',} \code{'time')}. A similar remark -about overriding this variable applies --- use the value from the base -class as a starting point. -\end{memberdesc} - -\begin{memberdesc}{ok_path} -Contains the directories which will be searched when an \keyword{import} -is performed in the restricted environment. -The value for \class{RExec} is the same as \code{sys.path} (at the time -the module is loaded) for unrestricted code. -\end{memberdesc} - -\begin{memberdesc}{ok_posix_names} -% Should this be called ok_os_names? -Contains the names of the functions in the \module{os} module which will be -available to programs running in the restricted environment. The -value for \class{RExec} is \code{('error',} \code{'fstat',} -\code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',} -\code{'times',} \code{'uname',} \code{'getpid',} \code{'getppid',} -\code{'getcwd',} \code{'getuid',} \code{'getgid',} \code{'geteuid',} -\code{'getegid')}. -\end{memberdesc} - -\begin{memberdesc}{ok_sys_names} -Contains the names of the functions and variables in the \module{sys} -module which will be available to programs running in the restricted -environment. The value for \class{RExec} is \code{('ps1',} -\code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',} -\code{'exit',} \code{'maxint')}. -\end{memberdesc} - - -\class{RExec} instances support the following methods: - -\begin{methoddesc}{r_eval}{code} -\var{code} must either be a string containing a Python expression, or -a compiled code object, which will be evaluated in the restricted -environment's \module{__main__} module. The value of the expression or -code object will be returned. -\end{methoddesc} - -\begin{methoddesc}{r_exec}{code} -\var{code} must either be a string containing one or more lines of -Python code, or a compiled code object, which will be executed in the -restricted environment's \module{__main__} module. -\end{methoddesc} - -\begin{methoddesc}{r_execfile}{filename} -Execute the Python code contained in the file \var{filename} in the -restricted environment's \module{__main__} module. -\end{methoddesc} - -Methods whose names begin with \samp{s_} are similar to the functions -beginning with \samp{r_}, but the code will be granted access to -restricted versions of the standard I/O streams \code{sys.stdin}, -\code{sys.stderr}, and \code{sys.stdout}. - -\begin{methoddesc}{s_eval}{code} -\var{code} must be a string containing a Python expression, which will -be evaluated in the restricted environment. -\end{methoddesc} - -\begin{methoddesc}{s_exec}{code} -\var{code} must be a string containing one or more lines of Python code, -which will be executed in the restricted environment. -\end{methoddesc} - -\begin{methoddesc}{s_execfile}{code} -Execute the Python code contained in the file \var{filename} in the -restricted environment. -\end{methoddesc} - -\class{RExec} objects must also support various methods which will be -implicitly called by code executing in the restricted environment. -Overriding these methods in a subclass is used to change the policies -enforced by a restricted environment. - -\begin{methoddesc}{r_import}{modulename\optional{, globals\optional{, - locals\optional{, fromlist}}}} -Import the module \var{modulename}, raising an \exception{ImportError} -exception if the module is considered unsafe. -\end{methoddesc} - -\begin{methoddesc}{r_open}{filename\optional{, mode\optional{, bufsize}}} -Method called when \function{open()} is called in the restricted -environment. The arguments are identical to those of \function{open()}, -and a file object (or a class instance compatible with file objects) -should be returned. \class{RExec}'s default behaviour is allow opening -any file for reading, but forbidding any attempt to write a file. See -the example below for an implementation of a less restrictive -\method{r_open()}. -\end{methoddesc} - -\begin{methoddesc}{r_reload}{module} -Reload the module object \var{module}, re-parsing and re-initializing it. -\end{methoddesc} - -\begin{methoddesc}{r_unload}{module} -Unload the module object \var{module} (i.e., remove it from the -restricted environment's \code{sys.modules} dictionary). -\end{methoddesc} - -And their equivalents with access to restricted standard I/O streams: - -\begin{methoddesc}{s_import}{modulename\optional{, globals\optional{, - locals\optional{, fromlist}}}} -Import the module \var{modulename}, raising an \exception{ImportError} -exception if the module is considered unsafe. -\end{methoddesc} - -\begin{methoddesc}{s_reload}{module} -Reload the module object \var{module}, re-parsing and re-initializing it. -\end{methoddesc} - -\begin{methoddesc}{s_unload}{module} -Unload the module object \var{module}. -% XXX what are the semantics of this? -\end{methoddesc} - -\subsection{An example} - -Let us say that we want a slightly more relaxed policy than the -standard \class{RExec} class. For example, if we're willing to allow -files in \file{/tmp} to be written, we can subclass the \class{RExec} -class: - -\begin{verbatim} -class TmpWriterRExec(rexec.RExec): - def r_open(self, file, mode='r', buf=-1): - if mode in ('r', 'rb'): - pass - elif mode in ('w', 'wb', 'a', 'ab'): - # check filename : must begin with /tmp/ - if file[:5]!='/tmp/': - raise IOError, "can't write outside /tmp" - elif (string.find(file, '/../') >= 0 or - file[:3] == '../' or file[-3:] == '/..'): - raise IOError, "'..' in filename forbidden" - else: raise IOError, "Illegal open() mode" - return open(file, mode, buf) -\end{verbatim} -% -Notice that the above code will occasionally forbid a perfectly valid -filename; for example, code in the restricted environment won't be -able to open a file called \file{/tmp/foo/../bar}. To fix this, the -\method{r_open()} method would have to simplify the filename to -\file{/tmp/bar}, which would require splitting apart the filename and -performing various operations on it. In cases where security is at -stake, it may be preferable to write simple code which is sometimes -overly restrictive, instead of more general code that is also more -complex and may harbor a subtle security hole. |