LavaMoatLavaMoat Browserify - a Browserify Plugin for creating LavaMoat-protected builds
Warning experimental, under development, has not been audited, etc**
lavamoat-browserify is a browserify
plugin for generating app bundles protected by
LavaMoat, where modules
are defined in SES containers. It aims to reduce
the risk of malicious code in the app dependency graph, known
as "software supplychain attacks".
For an overview of LavaMoat tools see the main README.
Anatomy of a LavaMoat bundle
The lavamoat-browserify plugin replaces the last internal build step of the browserify compiler pipeline. This step takes all the modules and their metadata and outputs the final bundle content, including the LavaMoat kernel. It also generates the LavaMoat policy file.
LavaMoat builds differ from standard browserify builds in that they:
- Uses
lockdown()from SES to prevent tampering with the execution environment. Thanks to lockdown, prototype-pollution attacks are neutralized. It's also a prerequisite to code isolation. - Uses SES Compartments to isolate each package's execution.
Packages don't share references to anything unless explicitly passed in or allowed by policy. Custom LavaMoat kernel handles the
require()calls in the resulting bundle. When required, a module is initialized, usually by evaluation inside a SES container. - Enforces the app-specified LavaMoat policy. The policy specifies what execution environment each package should run with, which means: what global/builtin APIs should it be exposed to, and what other packages can it require/import.
The result is a bundle that should work just as before, but provides some protection against supplychain attacks.
Example
Create a file, index.js with some requires.
const foo = require('./foo.js');
const gamma = require('gamma');
const elem = document.getElementById('result');
const x = foo(100);
elem.textContent = x;
Now use the browserify command with lavamoat as a plugin to build a lavamoat-protected bundle starting at index.js:
$ browserify index.js --plugin [ lavamoat-browserify --autopolicy ]
All of the modules that index.js needs are included in the bundle.js as strings to be evaluated inside SES containers. A lavamoat policy object is generated from a recursive walk of the require() graph and injected into the bundle (via --autopolicy), which is also written to disk at ./lavamoat/browserify/policy.json. Commit this policy file and regenerate it when your dependencies change and you agree with them.
Note You should review the diff in regenerated policy for suspicious changes, e.g. a simple maths package getting access to
fetchordocumentWarning Do not edit the autogenerated
policy.jsondirectly. It will be overwritten if a new bundle is created using LavaMoat. Instead, edit thepolicy-override.json.See Policy file explained for details on the policy file definition.
To use this bundle, just toss a <script src="bundle.js"></script> into your html, as per the official browserify documentation.
Be sure to use the same Browserify configuration (eg. plugins and transforms like babelify) that you normally use, so that it can parse the code as it will appear in your final bundle.
Install
Before you use lavamoat runtime protections, make sure you've set up allow-scripts and install dependencies using that setup.
Use one of:
yarn add -D browserify lavamoat-browserify
npm i -D browserify lavamoat-browserify
npm i --ignore-scripts -g browserify lavamoat-browserify
Usage
Usage: browserify [entry files] {BROWSERIFY OPTIONS} --plugin [ lavamoat-browserify {OPTIONS} ]
Options:
--autopolicy, -a Generate a `policy.json` and `policy-override.json` in the current
working directory. Overwrites any existing policy files. The override policy is for making manual policy changes and always takes precedence over the automatically generated policy.
--policy, -p Pass in policy. Accepts a policy object {} or a filepath string to the existing
policy. When used in conjunction with --autopolicy, specifies where to write the policy. Default: ./lavamoat/browserify/policy.json
--override, -o Pass in override policy. Accepts a policy object {} or a filepath string to the
existing override policy. Default: ./lavamoat/browserify/policy-override.json
Advanced Options:
--prelude, -pr Omit the lavamoat prelude from the bundle.
--prunepolicy, -pp Remove redundant package entries from the policy.
--debugpolicy, -dp Generate a `policy-debug.json` in the current working directory. Used for the
lavamoat visualisation tool.
--debug, -d Turn on extra logging for debugging.
--help, -h Show this message
More Examples
Run with Policy
This uses the existing policy files to generate a bundle.
$ browserify index.js --plugin [ lavamoat-browserify ]
Automatically searches for policy files inside ./lavamoat/browserify/.
Policy Override with Relative Path
This uses the override policy specified at ./policies/policy-override.json to generate a new bundle.
$ browserify index.js --plugin [ lavamoat-browserify --override './policies/policy-override.json' ]
browserify API
Create a browserify bundle with LavaMoat directly from the API and write it to bundle.js.
const browserify = require('browserify')
const fs = require('fs')
const lavamoatOpts = {
policy: '../../policy.json',
override: '../../policy-override.json',
writeAutoPolicyDebug: true,
prunePolicy: true,
}
const bundler = browserify(['./index.js'], {
plugin: [['lavamoat-browserify', lavamoatOpts]],
})
bundler.bundle().pipe(fs.createWriteStream('./bundle.js'))
Policy Formats
Policy as an object
const lavamoatOpts = {
policy: {
resources: {
'dependency-name': {
packages: {
react: true,
},
},
},
},
}
Policy as a function, must return a file path or an object:
const lavamoatOpts = {
policy: () => './lavamoat/policy.json',
}
OR
const policyObject = {
resources: {
'dependency-name': {
packages: {
react: true,
},
},
},
}
const lavamoatOpts = {
policy: () => policyObject,
}
See lavamoat-browserify examples for more usage examples.
See Policy file explained for details on the policy file definition.