| .. _rexec-objects: |
| |
| RExec Objects |
| ------------- |
| |
| :class:`RExec` instances support the following methods: |
| |
| |
n | .. method:: XXX Class.r_eval(code) |
n | .. method:: RExec.r_eval(code) |
| |
| *code* must either be a string containing a Python expression, or a compiled |
| code object, which will be evaluated in the restricted environment's |
| :mod:`__main__` module. The value of the expression or code object will be |
| returned. |
| |
| |
n | .. method:: XXX Class.r_exec(code) |
n | .. method:: RExec.r_exec(code) |
| |
| *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 |
| :mod:`__main__` module. |
| |
| |
n | .. method:: XXX Class.r_execfile(filename) |
n | .. method:: RExec.r_execfile(filename) |
| |
| Execute the Python code contained in the file *filename* in the restricted |
| environment's :mod:`__main__` module. |
| |
| Methods whose names begin with ``s_`` are similar to the functions beginning |
| with ``r_``, but the code will be granted access to restricted versions of the |
| standard I/O streams ``sys.stdin``, ``sys.stderr``, and ``sys.stdout``. |
| |
| |
n | .. method:: XXX Class.s_eval(code) |
n | .. method:: RExec.s_eval(code) |
| |
| *code* must be a string containing a Python expression, which will be evaluated |
| in the restricted environment. |
| |
| |
n | .. method:: XXX Class.s_exec(code) |
n | .. method:: RExec.s_exec(code) |
| |
| *code* must be a string containing one or more lines of Python code, which will |
| be executed in the restricted environment. |
| |
| |
n | .. method:: XXX Class.s_execfile(code) |
n | .. method:: RExec.s_execfile(code) |
| |
| Execute the Python code contained in the file *filename* in the restricted |
| environment. |
| |
| :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. |
| |
| |
n | .. method:: XXX Class.r_import(modulename[, globals[, locals[, fromlist]]]) |
n | .. method:: RExec.r_import(modulename[, globals[, locals[, fromlist]]]) |
| |
| Import the module *modulename*, raising an :exc:`ImportError` exception if the |
| module is considered unsafe. |
| |
| |
n | .. method:: XXX Class.r_open(filename[, mode[, bufsize]]) |
n | .. method:: RExec.r_open(filename[, mode[, bufsize]]) |
| |
| Method called when :func:`open` is called in the restricted environment. The |
| arguments are identical to those of :func:`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 :meth:`r_open`. |
| |
| |
n | .. method:: XXX Class.r_reload(module) |
n | .. method:: RExec.r_reload(module) |
| |
| Reload the module object *module*, re-parsing and re-initializing it. |
| |
| |
n | .. method:: XXX Class.r_unload(module) |
n | .. method:: RExec.r_unload(module) |
| |
| Unload the module object *module* (remove it from the restricted environment's |
| ``sys.modules`` dictionary). |
| |
| And their equivalents with access to restricted standard I/O streams: |
| |
| |
n | .. method:: XXX Class.s_import(modulename[, globals[, locals[, fromlist]]]) |
n | .. method:: RExec.s_import(modulename[, globals[, locals[, fromlist]]]) |
| |
| Import the module *modulename*, raising an :exc:`ImportError` exception if the |
| module is considered unsafe. |
| |
| |
n | .. method:: XXX Class.s_reload(module) |
n | .. method:: RExec.s_reload(module) |
| |
| Reload the module object *module*, re-parsing and re-initializing it. |
| |
| |
n | .. method:: XXX Class.s_unload(module) |
n | .. method:: RExec.s_unload(module) |
| |
| Unload the module object *module*. |
| |
n | .. % XXX what are the semantics of this? |
n | .. XXX what are the semantics of this? |
| |
| |
| .. _rexec-extension: |
| |
| Defining restricted environments |
| -------------------------------- |
| |
| The :class:`RExec` class has the following class attributes, which are used by |
| the :meth:`__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. |
| |
| |
n | .. attribute:: XXX Class.nok_builtin_names |
n | .. attribute:: RExec.nok_builtin_names |
| |
| Contains the names of built-in functions which will *not* be available to |
| programs running in the restricted environment. The value for :class:`RExec` is |
| ``('open', 'reload', '__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.) |
| |
| |
n | .. attribute:: XXX Class.ok_builtin_modules |
n | .. attribute:: RExec.ok_builtin_modules |
| |
| Contains the names of built-in modules which can be safely imported. The value |
| for :class:`RExec` is ``('audioop', 'array', 'binascii', 'cmath', 'errno', |
| 'imageop', 'marshal', 'math', 'md5', 'operator', 'parser', 'regex', 'select', |
| 'sha', '_sre', 'strop', 'struct', 'time')``. A similar remark about overriding |
| this variable applies --- use the value from the base class as a starting point. |
| |
| |
n | .. attribute:: XXX Class.ok_path |
n | .. attribute:: RExec.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 ``sys.path`` (at the time the module is loaded) for unrestricted code. |
| |
| |
n | .. attribute:: XXX Class.ok_posix_names |
n | .. attribute:: RExec.ok_posix_names |
| |
| Contains the names of the functions in the :mod:`os` module which will be |
| available to programs running in the restricted environment. The value for |
| :class:`RExec` is ``('error', 'fstat', 'listdir', 'lstat', 'readlink', 'stat', |
| 'times', 'uname', 'getpid', 'getppid', 'getcwd', 'getuid', 'getgid', 'geteuid', |
| 'getegid')``. |
| |
n | .. % Should this be called ok_os_names? |
n | .. Should this be called ok_os_names? |
| |
| |
n | .. attribute:: XXX Class.ok_sys_names |
n | .. attribute:: RExec.ok_sys_names |
| |
| Contains the names of the functions and variables in the :mod:`sys` module which |
| will be available to programs running in the restricted environment. The value |
| for :class:`RExec` is ``('ps1', 'ps2', 'copyright', 'version', 'platform', |
| 'exit', 'maxint')``. |
| |
| |
n | .. attribute:: XXX Class.ok_file_types |
n | .. attribute:: RExec.ok_file_types |
| |
| Contains the file types from which modules are allowed to be loaded. Each file |
| type is an integer constant defined in the :mod:`imp` module. The meaningful |
| values are :const:`PY_SOURCE`, :const:`PY_COMPILED`, and :const:`C_EXTENSION`. |
| The value for :class:`RExec` is ``(C_EXTENSION, PY_SOURCE)``. Adding |
| :const:`PY_COMPILED` in subclasses is not recommended; an attacker could exit |
| the restricted execution mode by putting a forged byte-compiled file |
| (:file:`.pyc`) anywhere in your file system, for example by writing it to |