cwl_utils.sandboxjs

Safe execution of CWL Expressions in a NodeJS sandbox.

Attributes

default_timeout	Default number of seconds to wait while running a javascript engine.
seg_symbol
seg_single
seg_double
seg_index
segments
segment_re
param_str
param_re

Classes

JSEngine	Helper class that provides a standard way to create an ABC using
NodeJSEngine	Helper class that provides a standard way to create an ABC using
QuickJSEngine	Evaluate CWL javascript fragments with the qjs interpreter.

Functions

code_fragment_to_js(jscript[, jslib])
linenum(fn)
stdfmt(data)
get_js_engine()	Return the process-wide JS engine, creating it on first use.
set_js_engine(js_engine)
check_js_threshold_version(*args, **kwargs)
exec_js_process(*args, **kwargs)	Run a javascript text.
new_js_proc(*args, **kwargs)

Module Contents

cwl_utils.sandboxjs.default_timeout: float = 20

Default number of seconds to wait while running a javascript engine.

cwl_utils.sandboxjs.seg_symbol = '\\w+'

cwl_utils.sandboxjs.seg_single = "\\['([^']|\\\\')+'\\]"

cwl_utils.sandboxjs.seg_double = '\\["([^"]|\\\\")+"\\]'

cwl_utils.sandboxjs.seg_index = '\\[[0-9]+\\]'

cwl_utils.sandboxjs.segments = '(\\.\\w+|\\[\'([^\']|\\\\\')+\'\\]|\\["([^"]|\\\\")+"\\]|\\[[0-9]+\\])'

cwl_utils.sandboxjs.segment_re

cwl_utils.sandboxjs.param_str = '\\((\\w+)(\\.\\w+|\\[\'([^\']|\\\\\')+\'\\]|\\["([^"]|\\\\")+"\\]|\\[[0-9]+\\])*\\)$'

cwl_utils.sandboxjs.param_re

cwl_utils.sandboxjs.code_fragment_to_js(jscript, jslib='')

Parameters:

• jscript (str)

• jslib (str)

Return type:

str

cwl_utils.sandboxjs.linenum(fn)

Parameters:

fn (str)

Return type:

str

cwl_utils.sandboxjs.stdfmt(data)

Parameters:

data (str)

Return type:

str

class cwl_utils.sandboxjs.JSEngine

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

abstractmethod eval(scan, jslib='', timeout=default_timeout, force_docker_pull=False, debug=False, js_console=False, container_engine='docker', **kwargs)

Parameters:

• scan (str)

• jslib (str)

• timeout (float)

• force_docker_pull (bool)

• debug (bool)

• js_console (bool)

• container_engine (str)

• kwargs (Any)

Return type:

cwl_utils.types.CWLOutputType | collections.abc.Awaitable[cwl_utils.types.CWLOutputType]

regex_eval(parsed_string, remaining_string, current_value, **kwargs)

Walk a parameter reference without a javascript engine (pure Python).

Parameters:

• parsed_string (str)

• remaining_string (str)

• current_value (cwl_utils.types.CWLOutputType)

• kwargs (Any)

Return type:

cwl_utils.types.CWLOutputType | collections.abc.Awaitable[cwl_utils.types.CWLOutputType]

class cwl_utils.sandboxjs.NodeJSEngine(have_node_slim=False, minimum_node_version_str='0.10.26', process_finished_str='r1cepzbhUTxtykz5XTC4\n')

Bases: JSEngine

Helper class that provides a standard way to create an ABC using inheritance.

Parameters:

• have_node_slim (bool)

• minimum_node_version_str (str)

• process_finished_str (str)

localdata

have_node_slim: bool = False

minimum_node_version_str: str = '0.10.26'

process_finished_str: str = Multiline-String

Show Value

"""r1cepzbhUTxtykz5XTC4
"""

processes_to_kill: Deque[subprocess.Popen[str]]

__del__()

Return type:

None

check_js_threshold_version(working_alias)

Check if the nodeJS engine version on the system with the allowed minimum version.

https://github.com/nodejs/node/blob/master/CHANGELOG.md#nodejs-changelog

Parameters:

working_alias (str)

Return type:

bool

exec_js_process(js_text, timeout=default_timeout, js_console=False, context=None, force_docker_pull=False, container_engine='docker')

Run a javascript text.

Parameters:

• timeout (float) – Max number of seconds to wait.

• js_text (str)

• js_console (bool)

• context (str | None)

• force_docker_pull (bool)

• container_engine (str)

Returns:

A tuple of the return code, stdout, and stderr of the javascript engine invocation.

Return type:

tuple[int, str, str]

new_js_proc(js_text, force_docker_pull=False, container_engine='docker')

Return a subprocess ready to submit javascript to.

Parameters:

• js_text (str)

• force_docker_pull (bool)

• container_engine (str)

Return type:

subprocess.Popen[str]

eval(scan, jslib='', timeout=default_timeout, force_docker_pull=False, debug=False, js_console=False, container_engine='docker', **kwargs)

Parameters:

• scan (str)

• jslib (str)

• timeout (float)

• force_docker_pull (bool)

• debug (bool)

• js_console (bool)

• container_engine (str)

• kwargs (Any)

Return type:

cwl_utils.types.CWLOutputType

class cwl_utils.sandboxjs.QuickJSEngine(qjs_path='qjs')

Bases: JSEngine

Evaluate CWL javascript fragments with the qjs interpreter.

QuickJS starts in about a millisecond, so unlike NodeJSEngine no persistent process or wire protocol is needed: each evaluation runs in one short-lived qjs subprocess. The container fallback keyword arguments accepted by the NodeJS engine (force_docker_pull, container_engine) are accepted and ignored; js_console is not supported.

Parameters:

qjs_path (str)

qjs_path = 'qjs'

check_js_threshold_version(working_alias=None)

Check that the qjs interpreter supports the features this engine needs.

QuickJS distributions do not share a version scheme (the original QuickJS uses dates while quickjs-ng uses semantic versions), so rather than parsing version strings this probes the interpreter with a small script exercising the features the engine relies on: eval() completion values, globalThis, Object.assign, JSON, and print. A missing or broken interpreter fails the probe.

Parameters:

working_alias (str | None)

Return type:

bool

eval(scan, jslib='', timeout=default_timeout, force_docker_pull=False, debug=False, js_console=False, container_engine='docker', **kwargs)

Parameters:

• scan (str)

• jslib (str)

• timeout (float)

• force_docker_pull (bool)

• debug (bool)

• js_console (bool)

• container_engine (str)

• kwargs (Any)

Return type:

cwl_utils.types.CWLOutputType

exec_js_process(js_text, timeout=default_timeout, js_console=False, context=None, force_docker_pull=False, container_engine='docker')

Run a javascript text in a fresh qjs subprocess.

The context script, when given, is evaluated first and the properties of its completion value become global variables for js_text, mirroring how cwlNodeEngineWithContext.js applies vm.runInNewContext(js_text, context).

Parameters:

• timeout (float) – Max number of seconds to wait.

• js_text (str)

• js_console (bool)

• context (str | None)

• force_docker_pull (bool)

• container_engine (str)

Returns:

A tuple of the return code, stdout, and stderr of the javascript engine invocation. A timeout is reported as return code -1.

Return type:

tuple[int, str, str]

cwl_utils.sandboxjs.get_js_engine()

Return the process-wide JS engine, creating it on first use.

The engine is chosen by the CWL_JS_ENGINE environment variable (node or quickjs); when it is unset, QuickJS is preferred if a usable qjs executable is found on the PATH, NodeJS otherwise. Engines installed with set_js_engine() take precedence.

Return type:

JSEngine

cwl_utils.sandboxjs.set_js_engine(js_engine)

Parameters:

js_engine (JSEngine)

Return type:

None

cwl_utils.sandboxjs.check_js_threshold_version(*args, **kwargs)

Parameters:

• args (Any)

• kwargs (Any)

Return type:

bool

cwl_utils.sandboxjs.exec_js_process(*args, **kwargs)

Run a javascript text.

Parameters:

• timeout – Max number of seconds to wait.

• args (Any)

• kwargs (Any)

Returns:

A tuple of the return code, stdout, and stderr of the javascript engine invocation.

Return type:

tuple[int, str, str]

cwl_utils.sandboxjs.new_js_proc(*args, **kwargs)

Parameters:

• args (Any)

• kwargs (Any)

Return type:

subprocess.Popen[str]