In certain circumstances, you may want to evaluate JavaScript code with restricted privileges. In Firefox 1.5 (Gecko 1.8) or later, an API exists to allow you to do this. It contains the notion of a "sandbox" that you can create and evaluate code in its context. Code evaluated using this method will always execute with restricted privileges, as on a normal web page.

Note: It's not safe to use evalInSandbox() to evaluate JSON strings; instead, use the techniques discussed in the article on JSON. You can also find Firefox 3.5 specific information in Using JSON in Firefox.


To use evalInSandbox(), you must first create a sandbox object using its constructor, Components.utils.Sandbox.

Note: The syntax of the Components.utils.Sandbox constructor changed in Gecko 2.0. Previously, the optional parameters were passed directly to the constructor instead of being properties of the optional parameters object. See that article for details on this change.

The sandbox is just an empty JavaScript object marked as being created by the restricted privilege principal. It will become the global scope object when you pass it to evalInSandbox(text, sandbox). You may want to add objects to this scope. For example:

// create new sandbox instance
var mySandbox = new Components.utils.Sandbox("");
mySandbox.y = 5;  // insert property 'y' with value 5 into global scope.
var result = Components.utils.evalInSandbox("x = y + 2; x + 3", mySandbox);
// result is 10, mySandbox.x is now 7

Operations on objects you insert into this sandbox global scope do not carry privileges into the sandbox: = Components;
// this will give a "Permission Denied" error
Components.utils.evalInSandbox("foo.classes", mySandbox);

On the other hand, any function that comes out of the sandbox executes with the privileges of chrome code. This can happen in a surprising number of ways as you can see in the next section.


Security warning: There is potential for security problems to arise when using evalInSandbox() if you rely on the properties of an object resulting from the code executed in the sandbox.

Some examples:

<script src="prototype.js"></script>

var s = new Components.utils.Sandbox(url);
var x = Components.utils.evalInSandbox(untrusted_code, s);
if (x == 1) {
  /* this code is unsafe; calls x.valueOf() */

if (x === 1) {
  /* this code is safe */

var y = x.y; /* this is unsafe */
var z = sandbox.z; /* unsafe */

if (typeof x == "number") {
  /* safe */

To understand how the security risk arises, let's take the example of (x == 1). When this is evaluated, the x.valueOf() method gets called by chrome code. When this happens, unsafe code can create a String object in the chrome code's global scope.

If the chrome code has added a function that has chrome privileges to String.prototype, Object.prototype, or Function.prototype, then unsafe code can abuse that function. What the unsafe code can do depends on what that function is, but the unsafe code can wind up being executed with chrome privileges.

To avoid this potential security risk, you should either carefully avoid using objects resulting from evalInSandbox() in any way that might result in a function in that object being called, or you should make sure that untrusted JSON strings don't contain any functions or expressions before using evalInSandbox() to evaluate them.

See also: PiggyBank analysis of sandbox

Optional Arguments

As of Firefox 3.5/Gecko 1.9.1, it's possible to optionally specify the JS version, filename, and line number of the code being evaluated. For instance:

var x = Components.utils.evalInSandbox("let x = 1;", sandbox, "1.8", "", 25);

The above will execute code using JavaScript 1.8.  Any exceptions raised by the evaluated code will show as originating from the above URL.  The evaluated code is assumed to start at line 25 of the document at that URL.

This functionality was added as a result of #445873

Importing Chrome Function into Sandbox Context

Note: Using the method importFunction() is no longer necessary. See using Importing functions or objects into the Sandbox.


Document Tags and Contributors

Last updated by: kscarfone,