Components.utils.Sandbox

Components.utils.Sandbox is used to create a sandbox object for use with evalInSandbox().

Creating a sandbox

To create a new sandbox, you should call Components.utils.Sandbox:

var sandbox = Components.utils.Sandbox(principal[, options]);
  • principal is a required argument, which specifies permissions for code executing in the sandbox. This can be specified as:
    • nsIDOMWindow, such as returned by the DOM window property.
    • nsIPrincipal (supported in Gecko 1.9 (Firefox 3) and later)
    • a string URI like "http://www.example.com/" (when possible, specify a window or an nsIPrincipal object instead of using a string URI)
    • an array of principals (added in bug 734891); each item of the array should have one of the types listed above.
  • options is an optional argument described below.

Using new Components.utils.Sandbox(...) to create a sandbox has the same effect as calling Sandbox(...) without new.

The created sandbox is simply an empty JavaScript object marked as having been created by the restricted privilege principal. You can then use it with evalInSandbox() to make it the global scope object for the specified script.

Sandbox principal

The sandbox principal specified the security context of the scripts executed in the sandbox. For example, creating a sandbox with a URI of http://www.example.com/ lets the code evaluated in the sandbox make AJAX requests from that domain. If the script running in the sandbox sets document.domain to change the same-origin security checks, you should use a DOM window or nsIPrincipal for the origin instead of a URI.

See also Security check basics and Same-origin policy.

Sandbox options

The constructor accepts an optional parameter. This parameter is an object with the following optional properties:

sandboxName

A string value which identifies the sandbox in about:memory (and possibly other places in the future). This property is optional, but very useful for tracking memory usage of add-ons and other JavaScript compartments. A recommended value for this property is an absolute path to the script responsible for creating the sandbox. As of Gecko 13 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10), if you don't specify a sandbox name it will default to the caller's filename.

sandboxPrototype

A prototype object for the sandbox. The sandbox will inherit the contents of this object if it's provided.

wantXrays

A Boolean value indicating whether the sandbox wants X-ray vision with respect to same-origin objects outside the sandbox. Default: true.

“X-ray vision” is exactly the same X-ray behavior that script always gets, by default, when working with DOM objects across origin boundaries. This is primarily visible for chrome code accessing content. However, it also occurs during cross-origin access between two content pages, since each page sees a "vanilla" view of the other. The protection is bidirectional: the caller sees the bonafide DOM objects without being confused by sneakily-redefined properties, and the target receives appropriate privacy from having its expandos inspected by untrusted callers. In situations where only unidirectional protection is needed, callers have the option to waive the X-ray behavior using wrappedJSObject or XPCNativeWrapper.unwrap().

In general, when accessing same-origin content, script gets a Transparent wrapper rather than an X-ray wrapper. However, sandboxes are often used when chrome wants to run script as another origin, possibly to interact with the page. In this case, same-origin X-rays are desirable, and wantXrays should be set to true. This is also the default (for historical reasons).

See Safely accessing content DOM from chrome for more details.

wantComponents

A Boolean indicating whether the Components object is available or not in the sandbox. Default: true.

wantExportHelpers Requires Gecko 29.0

A Boolean: if true, then createObjectIn(), evalInWindow(), and exportFunction() are available in the sandbox. Default: false.

wantXHRConstructor

A Boolean indicating whether the XMLHttpRequest object is available or not in the sandbox. Default: false.

Note: The syntax of this constructor changed in Gecko 2.0. Previously, the optional parameters sandboxPrototype and wantXrays were passed directly to the constructor instead of being properties of the optional parameters object; they were passed directly in the order listed above.

Methods available on the Sandbox object

dump() - Similar to window.dump().
debug()

For more information on the built-in Sandbox functions, please consult the source code.

Importing functions or objects into the sandbox

You can import functions or objects into the sandbox simply by assigning them to the sandbox object.  For example:

mysandbox.doSomething = function() { ... };

Obviously you still need to consider the security implications of the functions you import, but it is no longer necessary to use sandbox.importFunction() to securely import chrome functions into the Sandbox context - see bug 756514 for more or the Firefox socialapi code for an example. This technique isn't limited to functions - it can be used to import objects or values.

Freeing the sandbox

When you have finished using a sandbox, it should be freed to avoid memory leaks. Generally the JavaScript garbage collector will take care of this when there are no remaining references to the sandbox or the code it contains. However, in some cases it can be difficult to remove all references. For example, the code in the sandbox might be a third-party library that sets expando properties or adds event listeners to a window. In this case, Components.utils.nukeSandbox can be used to force the sandbox to be freed immediately.

See also