isolated-vm

[](https://www.npmjs.com/package/isolated-vm) [](https://github.com/laverdet/isolated-vm/blob/main/LICENSE) [](https://app.travis-ci.com/github/laverdet/isolated-vm) [](https://www.npmjs.com/package/isolated-vm) isolated-vm -- Access to multiple isolates in nodejs ==================================================== [](https://www.npmjs.com/package/isolated-vm) `isolated-vm` is a library for nodejs which gives you access to v8's `Isolate` interface. This allows you to create JavaScript environments which are completely *isolated* from each other. This can be a powerful tool to run code in a fresh JavaScript environment completely free of extraneous capabilities provided by the nodejs runtime. * [Requirements](#requirements) * [Who Is Using isolated-vm](#who-is-using-isolated-vm) * [Security](#security) * [API Documentation](#api-documentation) * [Isolate](#class-isolate-transferable) * [Context](#class-context-transferable) * [Script](#class-script-transferable) * [Module](#class-module-transferable) * [Callback](#class-callback-transferable) * [Reference](#class-reference-transferable) * [ExternalCopy](#class-externalcopy-transferable) * [Examples](#examples) * [Alternatives](#alternatives) REQUIREMENTS ------------ This project requires nodejs version 10.4.0 (or later). Furthermore, to install this module you will need a compiler installed. If you run into errors while running `npm install isolated-vm` it is likely you don't have a compiler set up, or your compiler is too old. * Windows + OS X users should follow the instructions here: [node-gyp](https://github.com/nodejs/node-gyp) * Ubuntu users should run: `sudo apt-get install python g++ build-essential` * Alpine users should run: `sudo apk add python make g++` * Amazon Linux AMI users should run: `sudo yum install gcc72 gcc72-c++` * Arch Linux users should run: `sudo pacman -S make gcc python` WHO IS USING ISOLATED-VM ------------------------ * [Screeps](https://screeps.com/) - Screeps is an online JavaScript-based MMO+RPG game. They are using isolated-vm to run arbitrary player-supplied code in secure environments which can persistent for several days at a time. * [Fly](https://fly.io/) - Fly is a programmable CDN which hosts dynamic endpoints as opposed to just static resources. They are using isolated-vm to run globally distributed applications, where each application may have wildly different traffic patterns. * [Algolia](https://www.algolia.com) - Algolia is a Search as a Service provider. They use `isolated-vm` to power their [Custom Crawler](https://www.algolia.com/products/crawler/) product, which allows them to safely execute user-provided code for content extraction. * [Tripadvisor](https://www.tripadvisor.com) - Tripadvisor is the world’s largest travel platform. They use `isolated-vm` to server-side render thousands of React pages per second. SECURITY -------- Running untrusted code is an extraordinarily difficult problem which must be approached with great care. Use of `isolated-vm` to run untrusted code does not automatically make your application safe. Through carelessness or misuse of the library it can be possible to leak sensitive data or grant undesired privileges to an isolate. At a minimum you should take care not to leak any instances of `isolated-vm` objects (`Reference`, `ExternalCopy`, etc) to untrusted code. It is usually trivial for an attacker to use these instances as a springboard back into the nodejs isolate which will yield complete control over a process. Additionally, it is wise to keep nodejs up to date through point releases which affect v8. You can find these on the [nodejs changelog](https://github.com/nodejs/node/blob/master/CHANGELOG.md) by looking for entries such as "update V8 to 9.1.269.36 (Michaël Zasso) #38273". Historically there have usually been 3-5 of these updates within a single nodejs LTS release cycle. It is *not* recommended to use odd-numbered nodejs releases since these frequently break ABI and API compatibility and isolated-vm doesn't aim to be compatible with bleeding edge v8. Against potentially hostile code you should also consider turning on [v8 untrusted code mitigations](https://v8.dev/docs/untrusted-code-mitigations), which helps address the class of speculative execution attacks known as Spectre and Meltdown. You can enable this feature by running `node` with the `--untrusted-code-mitigations` flag. This feature comes with a slight performance cost and must be enabled per-process, therefore nodejs disables it by default. v8 is a relatively robust runtime, but there are always new and exciting ways to crash, hang, exploit, or otherwise disrupt a process with plain old JavaScript. Your application must be resilient to these kinds of issues and attacks. It's a good idea to keep instances of `isolated-vm` in a different nodejs process than other critical infrastructure. If [advanced persistent threats](https://en.wikipedia.org/wiki/Advanced_persistent_threat) are within your threat model it's a very good idea to architect your application using a foundation similar to Chromium's [site isolation](https://www.chromium.org/Home/chromium-security/site-isolation). You'll also need to make sure to keep your system kernel up to date against [local privilege escalation](https://en.wikipedia.org/wiki/Privilege_escalation) attacks. Running your service in a container such as a Docker may be a good idea but it is important to research container escape attacks as well. API DOCUMENTATION ----------------- Since isolates share no resources with each other, most of this API is built to provide primitives which make marshalling data between many isolates quick and easy. The only way to pass data from one isolate to another is to first make that data *transferable*. Primitives (except for `Symbol`) are always transferable. This means if you invoke a function in a different isolate with a number or string as the argument, it will work fine. If you need to pass more complex information you will have to first make the data transferable with one of the methods here. Most methods will provide both a synchronous and an asynchronous version. Calling the synchronous functions will block your thread while the method runs and eventually returns a value. The asynchronous functions will return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) while the work runs in a separate thread pool. There are some rules about which functions may be called from certain contexts: 1. Asynchronous functions may be called at any time 2. Synchronous functions usually may not be called from an asynchronous function 3. You may call a synchronous function from an asynchronous function as long as that function belongs to current isolate 4. You may call a synchronous function belonging to the default nodejs isolate at any time Additionally, some methods will provide an "ignored" version which runs asynchronously but returns no promise. This can be a good option when the calling isolate would ignore the promise anyway, since the ignored versions can skip an extra thread synchronization. Just be careful because this swallows any thrown exceptions which might make problems hard to track down. It's also worth noting that all asynchronous invocations will run in the order they were queued, regardless of whether or not you wait on them. So, for instance, you could call several "ignored" methods in a row and then `await` on a final async method to observe some side-effect of the ignored methods. ### Class: `Isolate` *[transferable]* This is the main reference to an isolate. Every handle to an isolate is transfera