evalREX
Evaluating Expressions in Restricted Execution Mode
Description
evalREX evaluates an expression in "Restricted Execution" mode, where
attempting to execute certain operations defined as restricted (such as I/O)
generates an error. The other functions are related to evalREX.
Usage
evalREX(expr, envir=NULL, restoreEnv=FALSE, restoreOptions=FALSE, trace=FALSE)
getREX()
stopIfREX(msg)
Arguments
expr |
any expression or object to evaluate in restricted execution mode.
Note that this argument is evaluated like the first argument to
eval, before evaluating the result in restricted execution mode.
Thus, normally this argument is given as a call to the quote
function, wrapping an expression.
|
envir |
the environment in which to do the evaluation in restricted execution
mode. By default, it is the current environment, where the function is called.
|
restoreEnv |
specifies how to handle the envir on exit. Can be one of the following.
| FALSE | | On exit, do not restore envir. |
| TRUE | | On exit, restore envir. |
| An environment | | On exit, save the contents of envir in restoreEnv, and then restore
envir). |
|
restoreOptions |
a logical value. If TRUE, then evalREX restores the options
upon exit. If FALSE (the default), then evalREX leaves the options as
they are.
|
trace |
a logical value. If TRUE, then executing a "restricted" operation
prints a message to stderr and continues, rather than generating an
error. The default is FALSE.
|
msg |
a character string.
|
Details
The function evalREX evaluates an expression in restricted
execution mode, where attempting to execute certain restricted operations
generates an error.
The function getREX returns whether restricted
execution mode and tracing mode are enabled.
The function
stopIfREX is similar to
stop, except
that it checks whether restricted execution mode is enabled, and only
generates an error if it is enabled (and tracing mode is not enabled).
Restricted execution mode allows executing arbitrary
scripts without worrying that the script could do malicious things, such
as deleting files or uploading confidential data to a server over the
internet. evalREX is fairly conservative, preventing many
operations, while still allowing some useful exceptions. The following shows a
non-exhaustive list of operations disallowed in restricted execution
mode.
- Calling evalREX itself.
- Performing any I/O to the file system or the internet.
- Loading new packages, except for the libraries included with TIBCO Enterprise Runtime for R (stats, terrUtils, and so on).
- Spawning new OS processes (calling 'system').
- Calling .Call, which is used to call Rapi code in CRAN packages.
- Calling .C or .Fortran.
- Calling into Java using the terrJava package (which allows executing
arbitrary Java methods).
- Calling any functions in the 'parallel' package (which uses
terrJava).
- Accessing any function environments in the stack above the call to
evalREX using sys.frame or parent.frame. This
prevents malicious code from installing functions or expressions that
could be executed after leaving restricted execution mode.
- Changing the variable lookup path by setting parent.env of
an environment, or reading or setting the environment of a closure.
- Defining S4 classes and methods using setClass or setMethod.
It is possible for malicious code to set functions or expressions in the
global environment or the options list. You can use the restoreEnv
and restoreOptions arguments of evalREX to
automatically restore the execution environment or options when
evalREX exits normally, or because of an error. Setting
restoreEnv to another empty environment copies the variables
in envir to this environment before restoring the original
contents of envir.
Warning: A common mistake when calling evalREX is to pass it an
expression not wrapped in quote. In this case, evalREX evaluates
its expr argument outside of the restricted expression mode, and
then evaluates the result in restricted expression mode. Thus,
evalREX(dir()) evaluates dir(), producing a character
vector, and then evaluates the result in restricted mode, which
succeeds.
Value
evalREX | returns the result of evaluating expr. |
getREX | returns a logical value, which is TRUE if
it is executed with restricted execution mode enabled; otherwise,
it is FALSE. This value has an attribute "trace", whose value is
TRUE if restricted execution mode is enabled, and if tracing is
enabled. |
stopIfREX | if stopIfREX is executed when restricted execution mode
is disabled, or if restricted execution mode is enabled with tracing enabled,
then stopIfREX returns NULL. Otherwise, stopIfREX generates
an error, so it does not have a return value. |
See Also
Examples
evalREX(quote(1:10)) ## returns the vector without an error
evalREX(quote(dir())) ## gives an error, because dir() is restricted
evalREX(dir())
## this is a common mistake: this executes dir(),
## and passes the result vector to evalREX,
## which just returns this result.
evalREX(quote(dir()), trace=TRUE)
## prints "evalREX trace: restricted call to Native[dir]...",
## and evaluates it
getREX() ## structure(FALSE, trace=FALSE)
evalREX(quote(getREX())) ## structure(TRUE, trace=FALSE)
stopIfREX("foo") ## no error
evalREX(quote(stopIfREX("foo"))) ## error
evalREX(quote(stopIfREX("foo")), trace=TRUE)
## prints "evalREX trace:...", but no error.