Reviewing Policy

This guide will show you how to review changes to your LavaMoat Policy File.

Why review Policy?

The Policy File generated by LavaMoat is based on a scan of your codebase, identifying all the powers it uses. The initial policy, resulting from the first time you run policy generation, doesn’t provide security on its own. Instead, it’s your review of the initial policy and the subsequent updates (with new or updated dependencies) that makes your application secure.

Reviewing diffs as dependencies change lets you spot suspicious packages or limit the powers you wish to allow newly added packages to use.

The purpose of the initial review is twofold:

1. It helps you build confidence that the current state of your app is not compromised
2. You may deny powers to dependencies if you determine they are excessive - not needed for the subset of functionality your app uses.

Reviewing your initial policy may seem like a lot of effort - but think of it as an investment in your application’s security posture.

How to review your policy?

The LavaMoat Policy lists all powers that a package can use; these are the globals and builtin fields. It also lists which other packages are allowed for the current package to import. You can follow those relations to see whether a package with access to very powerful APIs is used by any suspicious packages as a dependency. See Principle of Least Authority

What to look for when reviewing a Policy diff?

The goal of reviewing the diff is to spot a malicious package being added.

TL;DR

• Check globals and builtins for new powers and investigate if you’re surprised the package would need them
• Check if new relationships in packages are pointing to packages with very powerful APIs (e.g. spawning child processes in Node.js)
• Be aware that the identifier may change to pkgC>actual-name from pkgB>pkgA>actual-name BUT! If the package now also has totally different powers, it’s likely a different package of the same name. Investigate! npm ls actual-name should help
• When a new package is added, consider limiting its powers to what you actually use

Best Practices for Finding Suspicious Changes

First of all - you need to check if any of the packages get access to new powerful APIs unexpectedly.

If a package that was supposed to only be doing basic string operations is suddenly also using fetch and process.env in your build system, you should give it a closer look or add

"fetch": false,
"process": false

to the globals field for that package in policy-override.json.

When a new dependency shows up in packages field of packageA: look up what it’s pointing to and if the dependency has access to very powerful APIs; doublecheck whether it makes sense to you that packageA would need to use it.

When dependency tree changes, it’s possible that the dependency nesting might change - so the shortest identifier for one of the resources may now be pkgC>actual-name, not pkgB>pkgA>actual-name. But there are other more nefarious reasons why that could happen. If the package now also has totally different powers or dependencies listed it’s likely a different package of the same name. There can be more than one actual-name named package in this case. It could have been introduced as a different version or a totally different package installed from git or as a bundled dependency.

Whn a new package is added, consider limiting its powers to what you actually use.

What to look for in initial review?

The goal of reviewing the initial policy is to spot where packages are given powers that allow them escaping LavaMoat protections or abusing the application.

The minimal viable review is to look at the globals and builtins fields of the policy file to see if any of the packages have access to unexpected powerful APIs.

A more advanced review would be to apply Principle of Least Authority and add entries to policy-override.json to limit the powers of packages to what they actually need to serve your usecase.

Powerful APIs

Examples of powerful APIs - not an exhaustive list:

global	builtin	description
	child_process and any form of exec or spawn	Allows running arbitrary commands on the host machine and is not covered
	fs	Allows reading and writing files on the host machine
fetch, XMLHttpRequest, WebSocket, EventSource	http, https, net	Allows making network requests
document		contains a lot of powerful APIs that can be used to manipulate the DOM, including creating iframes with unprotected globals
open		window.open allows opening new windows/tabs and accessing clean globals there
navigator		contains a lot of powerful APIs that can be used to fingerprint the user or control the browser
chrome or browser		extension APIs - should only be accessed by a package that is a helper library for cross-browser extensions
process		Allows reading and writing environment variables and other process-related operations
	vm	Allows running arbitrary code in a new context