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 aninvestment in your application’s security posture.

How to review your policy?

The LavaMoat Policy lists all powers that a package can use; these are theglobals andbuiltin 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 verypowerful APIs is used by any suspicious packages as a dependency. SeePrinciple 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

• Checkglobals andbuiltins for new powers and investigate if you’re surprised the package would need them
• Check if new relationships inpackages are pointing to packages with verypowerful APIs (e.g. spawning child processes in Node.js)
• Be aware that the identifier may change topkgC>actual-name frompkgB>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 newpowerful APIs unexpectedly.

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

"fetch":false,
"process":false

to theglobals field for that package inpolicy-override.json.

When a new dependency shows up inpackages field ofpackageA: look up what it’s pointing to and if the dependency has access to verypowerful APIs; doublecheck whether it makes sense to you thatpackageA 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 bepkgC>actual-name,notpkgB>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 oneactual-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 theglobals andbuiltins fields of the policy file to see if any of the packages have access to unexpectedpowerful APIs.

A more advanced review would be to applyPrinciple 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: