@lavamoat/node NPM

@lavamoat/node

Warning: This software is alpha quality. Expect bugs and breaking changes!

@lavamoat/node is a Hardened JavaScript runtime for Node.js v18.0.0+ that provides per-package security policy enforcement.

@lavamoat/node:

Uses lockdown to prevent tampering with the execution environment:
- User code cannot meddle with JavaScript's global objects or shared intrinsics (i.e. "the stuff in the prototype chain")
- Neutralizes most prototype pollution attacks
Isolates dependencies within the same process:
- By default, packages do not share references to any global objects
- Access to resources (global objects, other packages, Node.js builtins, native modules) is controlled by user-defined policy
Provides tooling to generate and maintain the policy

LavaMoat can protect your Node.js application, but it can also protect your development environment (e.g., build scripts) — you can run your tools with the lavamoat CLI.

Supply Chain Security

Over time, your application's dependencies will need updating. How can you ensure a new version of a package—or newly-added dependencies—aren't doing something malicious?

@lavamoat/node provides a runtime that should work just as before, but with protection against most supply chain attacks.

Nodes.js provides powerful global APIs and builtins without restriction—but most of your app's dependencies don't need them. LavaMoat can stop packages from abusing these resources without blocking legitimate use.

Each package can only access resources that are explicitly allowed by the policy. If a package disallows access to a resource, the environment will behave as if that resource does not exist. This is a powerful way to prevent malicious packages from doing harm.

Runtime Security

If a package obfuscates its intentions to the degree that LavaMoat's own policy generation cannot detect what resources it needs, the generated policy will still prevent naughty behavior. This is because LavaMoat operates using the principle of least privilege. Resources not explicitly allowed by the policy do not exist in the package's execution scope—thanks to the Compartment provided by Hardened JavaScript.

LavaMoat parses code only during policy generation—never at runtime. Policy generation provides a starting point for customization by creating a policy which allows every resource it detects. While reviewing the policy, you can choose to create policy overrides to restrict or grant access to resources.

!TIP
Read more about reviewing policy files in the LavaMoat docs.

Differences from lavamoat

@lavamoat/node is intended to be a replacement for lavamoat.

Leverages @endo/compartment-mapper instead of a custom kernel, and thus supports ECMAScript modules out-of-the-box
The lavamoat CLI differs in its commands and options

Installation

@lavamoat/node requires Node.js v18.0.0 or newer.

npm install @lavamoat/node

Usage

!IMPORTANT
Before proceeding, it's recommended to check out LavaMoat's docs. Understanding LavaMoat's concepts will help you cross the LavaMoat Drawbridge of Success™.

Setup

Install @lavamoat/node
Generate a policy file:
```
npx exec lavamoat generate <your-app-entrypoint>
```
This will create a lavamoat/node/policy.json file in your project root.
Run your application with @lavamoat/node:
```
npx exec lavamoat <your-app-entrypoint>
```
This will run your application with the generated policy.
If step 3 failed, you may need to manually override policy.
If you're still having trouble, the LavaMoat docs can help.

`lavamoat` CLI Usage

lavamoat has two commands: run (the default) and generate.

lavamoat <entrypoint>

Run a Node.js application safely

Commands:
  lavamoat run <entrypoint>       Run a Node.js application safely     [default]
  lavamoat generate <entrypoint>  Generate a policy               [aliases: gen]

Path Options:
  -p, --policy           Filepath to a policy file
                                 [string] [default: "lavamoat/node/policy.json"]
  -o, --policy-override  Filepath to a policy override file
                        [string] [default: "lavamoat/node/policy-override.json"]
      --policy-debug     Filepath to a policy debug file
                           [string] [default: "lavamoat/node/policy-debug.json"]
      --root             Path to application root directory
                                         [string] [default: (current directory)]

Behavior Options:
      --dev  Include development dependencies          [boolean]

Positionals:
  entrypoint  Path to the application entry point; relative to --root   [string]

Options:
      --help     Show help                                             [boolean]
      --version  Show version number                                   [boolean]

Resources:

  🌋 LavaMoat on GitHub (https://github.com/LavaMoat/LavaMoat)
  🐛 Bugs? Issue tracker (https://github.com/LavaMoat/LavaMoat/issues)
  📖 Read the LavaMoat docs (https://lavamoat.github.io)

To print the above text, execute:

npx exec lavamoat --help

To see help for the generate command, execute:

npx exec lavamoat generate --help

Known Issues

The following issues (or missing features) are intended to be resolved:

await import() is not yet supported in CommonJS scripts
Scuttling (i.e. "deletion" of unused objects from the execution environment) is not yet supported