package.json vs. package-lock.json

Working in DevSecOps, I often encounter developers that are certain they have patched a vulnerability, but since they do not fully understand the `package*.json` files the vulnerability is still being flagged.

Although `package.json` is automatically generated and updated by npm, it can also be edited manually. This allows you to change the metadata and npm module dependencies for your NodeJS project with ease.

In general, `package.json` doesn’t specify exact version numbers for dependencies (although it can if you want it to). Instead, `package.json` generally sets the minimum version for each dependency, and it can also set a range of versions. In addition, `package.json` only tracks top-level dependencies for the project. You don’t need to specify dependencies of dependencies; that’s handled automatically for you. This makes `package.json` smaller in size, more accurate, and much more human-readable.

The problem with `package.json` is that you and your vulnerability scanner can end up seeing different versions of dependencies. Yet worse, you could be running different versions compared to what is running in production. That’s because `package.json` usually doesn’t specify exact versions, so depending on when/where you invoke npm install, you can see different versions than a vulnerability scanner. This is a recipe for disaster and lots of unneeded work.

The `package-lock.json` file was introduced in npm version 5 to solve this problem. It is a generated file and is not designed to be manually edited. Its purpose is to track the entire tree of dependencies (including dependencies of dependencies) and the exact version of each dependency.

You should commit package-lock.json to your code repository. Sharing this file with teammates and the production environment is the best way to make sure that everyone has the same configuration for their copy of the project.