sandblaster.js

A client-side JavaScript library to detect if your code is running inside of a sandboxed iframe... and, if desired, might just be able to change that fact!

Background

What is a sandboxed iframe?

The sandbox attribute of the iframe element (new in HTML5, supported in IE10+ and all other evergreen browsers) provides web developers with a way tighten the restrictions on framed content beyond what Content Security Policy (CSP) provides for unsandboxed cross-origin iframes. With the sandbox attribute, you can instruct the browser to load a specific frame's content in a low-privilege environment, starting with the least privilege possible and then whitelisting the necessary subset of capabilities.

It is also very important to note, however, that the sandbox attribute takes away some privileges from the framed content that CANNOT be whitelisted "back in". For example, any framed page running in a sandbox absolutely cannot run native plugins (e.g. Flash, Silverlight, Java, etc.). This decision was made because native plugins run unmanaged code that the browser cannot offer any further security verifications on, and are frequently sourced from third parties.

See Also

• HTML5 Rocks 🤘 article on sandboxed iframes
• HTML spec: iframe sandbox attribute
• Screen Orientation API spec — Adds the allow-orientation-lock token
• HTML spec: Browser sandboxing
• HTML5 Rocks 🤘 article on Content Security Policy (CSP)

Getting Started

Install

Sandblaster.js is published to NPM for ease of installation:

npm install sandblaster

Please keep in mind, however, that it only works in browser contexts, not in Node.js.

Load

Then, load up the "sandblaster.js" script on your HTML page:

<script src="node_modules/sandblaster/dist/sandblaster.min.js"></script>

Usage

Analysis

Detect and analyze, as best as possible, the state of the current window as it relates to being within a frame, sandboxed, and/or cross-origin:

var result = sandblaster.detect();

For full details on this analysis result object, see The Analysis Result below.

Action

Rebellion: Unsandboxing

If it is possible for your window state, you can also attempt to remove the sandboxing:

var succeeded = sandblaster.unsandbox();  // {true|false}

NOTE: Executing this function will also return true if the window is not within a frame at all. The basic concept of its return value is that it should be true if the window is not sandboxed at the end of the call.

Submission: Resandboxing & sandboxing

If you unsandboxed the window and later decide you want to resandbox it exactly as it was before:

var succeeded = sandblaster.resandbox();  // {true|false}

Or, if the existing window state will allow it, you can also add and/or update the sandbox configuration to whatever acceptable value you want:

var succeeded = sandblaster.sandbox({
  scripts: true,
  sameDomain: true,
  forms: false,
  pointerLock: false,
  popups: false,
  topNavigation: false
});

If the window is already in a sandboxed iframe, any non-Boolean values in the allowances object will defer to their current value in the DOM.

Resetting: Reloading the iframe

If it is possible for your window state, you can also attempt to reload the iframe with its current attributes:

var succeeded = sandblaster.reload();  // {true|false}

This is useful for those who want to make native plugins work after removing sandboxing (e.g. on JSFiddle, CodePen, etc.):

var result = sandblaster.detect();
if (result.sandboxed && sandblaster.unsandbox()) {
  sandblaster.reload();
}

NOTE: If this function succeeds, your following code may never get a chance to execute as the framed page will begin reloading.

The Analysis Result

A live visualization of every known possible analysis result can be seen at jamesmgreene.github.io/sandblaster/test-iframes.html.

The result object structure is as follows:

var result = sandblaster.detect();
 
/*
 
// `null` == uncertain
// `undefined` == not applicable
 
result = {
  framed: true|false,
  crossOrigin: true|false|null|undefined,
  sandboxed: true|false|null|undefined,
  sandboxAllowances: undefined|{
    forms: true|false|null,
    modals: true|false|null,
    orientationLock: true|false|null,
    pointerLock: true|false|null,
    popups: true|false|null,
    popupsToEscapeSandbox: true|false|null,
    presentation: true|false|null,
    sameOrigin: true|false|null,
    scripts: true|false|null,
    topNavigation: true|false|null,
    topNavigationByUserActivation: true|false|null
  },
  unsandboxable: true|false|undefined,
  resandboxable: true|false|undefined,
  sandboxable: true|false|undefined,
  errors: [
    // Any Errors that occurred during all of the various security probing. Just because there
    // were Errors does NOT mean that something actually went wrong unexpectedly.
    // Errors are provided as plain objects with `name`, `message`, and `stack` properties.
  ]
};
 
*/