policy review document #8

naugtur · 2024-09-04T13:30:42Z

No description provided.

src/content/docs/guides/policy-diff.md

Co-authored-by: LeoTM <[email protected]>

leotm

ah formatting remaining, i'll fix

fix ci

- markdownlint: specify json in fenced code block - prettier: format doc, except powerful APIs table

leotm

lgtm

boneskull

I had a couple questions about intent and terminology that I think should be addressed (this and that).
Everything else is mostly just grammar & style. Honestly, I'm wondering if you should just merge this and I'll play copy editor after. 😄

src/content/docs/guides/policy-diff.md

boneskull · 2024-09-16T19:47:05Z

src/content/docs/guides/policy-diff.md

+
+The Policy File generated by LavaMoat is based on a scan of your codebase, identifying all the powers it uses. The initial policy 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 you go lets you spot suspicious packages or limit the powers you wish newly added packages can use.


Suggested change

Reviewing diffs as you go lets you spot suspicious packages or limit the powers you wish newly added packages can use.

Reviewing diffs as dependencies change lets you spot suspicious packages and/or limit the powers granted to new dependencies.

again unsure about "powers"

"granted" may not be the right/consistent terminology

src/content/docs/guides/policy-diff.md

boneskull · 2024-09-16T19:53:33Z

src/content/docs/guides/policy-diff.md

+Reviewing diffs as you go lets you spot suspicious packages or limit the powers you wish newly added packages can use.
+
+The review of your initial policy may seem like a lot of effort, but it's an investment in a good starting point for your application.  
+If you generate the initial policy from a known uncompromised version of your application, the main purpose of the initial review is to potentially take away some of the excessive powers from packages you don't use in their full capacity.


this is kind of a run-on sentence. maybe break up into something like

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 (assuming it does not break your app)

boneskull · 2024-09-16T19:56:53Z

src/content/docs/guides/policy-diff.md

+
+The goal of reviewing the diff is to spot a malicious package being added.
+
+#### TL;DR


this usually comes first 😄

It's a TLDR of this paragraph - what to look for.

boneskull · 2024-09-16T19:59:14Z

src/content/docs/guides/policy-diff.md

+- 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](#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.


I'd capitalize the first letter of each list item

remove periods at the end of the last two items

he fourth item is unclear to me. you mean: identify the powers my app uses? (how do I do this?) I want to disallow anything that isn't in that my list of powers?

src/content/docs/guides/policy-diff.md

naugtur · 2024-09-17T07:42:04Z

* Everything else is mostly just grammar & style.  Honestly, I'm wondering if you should just merge this and I'll play copy editor after. 😄

I hereby give you the explicit (altho not new) permission to add a commit with grammar/style edits to a branch where I write prose without asking first.

Co-authored-by: Christopher Hiller <[email protected]>

initial draft of policy review document

ac592fe