lockfile-lint

A CLI to lint a lockfile for security policies

About

A CLI tool to lint a lockfile for security policies

Install

``bash
npm install --save lockfile-lint
`

Usage

lockfile-lint can be installed per a project scope, or globally and exposes a lockfile-lint executable that should be practiced during builds, CIs, and general static code analysis procedures to ensure that lockfiles are kept up to date with pre-defined security and usage policies.

`bash
lockfile-lint --type --path --validate-https --allowed-hosts --allowed-urls
`

Supported lockfiles:
- npm's package-lock.json and npm-shrinkwrap.json
- yarn's yarn.lock

Example

An example of running the linter with debug output for a yarn lockfile and asserting that all resources are using the official npm registry as source for packages:

`bash
DEBUG=* lockfile-lint --path yarn.lock --type yarn --allowed-hosts npm
`

Example 2: specify hostnames and enforce the use of HTTPS as a protocol

`bash
lockfile-lint --path yarn.lock --allowed-hosts registry.yarnpkg.com --validate-https
`

- --type yarn is ommitted since lockfile-lint can figure it out on it's own
- --allowed-hosts explicitly set to match yarn's mirror host

Example 3: allow the lockfile to contain packages served over github and so need to specify github.com as a host as well as the git+https: as a valid URI scheme

`bash
lockfile-lint --path yarn.lock --allowed-hosts yarn github.com --allowed-schemes "https:" "git+https:"
`

- --allowed-hosts explicitly set to match github.com as a host and specifies yarn as the alias for yarn's official mirror host
- --allowed-schemes is used instead of validate-https and it explicitly allows both https: and git+https: as the HTTP Scheme for the github URL. Note that --allowed-schemes and --validate-https are mutually exclusive.

Example 4: allow the lockfile to contain a package which resolves to a specific URL specified by the --allowed-urls option while all other packages must resolve to yarn as specified by --allowed-hosts

`bash
lockfile-lint --path yarn.lock --allowed-hosts yarn --allowed-urls https://github.com/lirantal/lockfile-lint#d30ce73a3e5977dede29450df1c79b09f02779b2
`

- --allowed-hosts allows packages from yarn only
- --allowed-urls overrides allowed-hosts and allows a specific Github URL to pass validation

CLI command options

| command line argument | description | implemented |
|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| --path, -p | path to the lockfile but you can also provide a glob matching pattern as long as it isn't expanded by a shell like bash or zsh. If that's the case, you can provide it as a string, for example: -p '/Users/lirantal/repos/**/package-lock.json' to match multiple lockfiles | ✅ |
| --type, -t | lockfile type, options are npm or yarn | ✅ |
| --format, -f | sets what type of report output is desired, one of [ pretty, plain ] with plain removing colors & status symbols from output | ✅ |
| --validate-https, -s | validates the use of HTTPS as protocol schema for all resources in the lockfile | ✅ |
| --allowed-hosts, -a | validates a list of allowed hosts to be used for all resources in the lockfile. Supported short-hands aliases are npm, yarn, and verdaccio which will match URLs https://registry.npmjs.org, https://registry.yarnpkg.com and https://registry.verdaccio.org respectively | ✅ |
| --allowed-schemes, -o | allowed URI schemes such as "https:", "http", "git+ssh:", or "git+https:" | ✅ |
| --allowed-urls, -u | allowed URLs (e.g. https://github.com/some-org/some-repo#some-hash) | ✅ |
| --empty-hostname, -e | allow empty hostnames, or set to false if you wish for a stricter policy | ✅ |
| --validate-package-names, -n | validates that the resolved URL matches the package name | ✅ |
| --validate-integrity, -i | validates the integrity field is a sha512 hash | ✅ |
| --allowed-package-name-aliases, -l | allow package name aliases to be used by specifying package name and their alias as pairs (e.g: string-width-cjs:string-width) | ✅ |
| --integrity-exclude | exclude packages from the --validate-integrity check | ✅ |

File-Based Configuration

Lockfile-lint uses cosmiconfig for configuration file support. This means you can configure the above options via (in order of precedence):

- A "lockfile-lint" key in your package.json file.
- A .lockfile-lintrc file, written in JSON or YAML, with optional extensions: .json/.yaml/.yml (without extension takes precedence).
- A .lockfile-lintrc.js, .lockfile-lintrc.cjs, or .lockfile-lintrc.mjs file that exports an object.
- A lockfile-lint.config.js, lockfile-lint.config.cjs, or lockfile-lint.config.mjs file that exports an object.

ESM syntax is supported in .mjs files. For example:

`javascript
export default {
path: 'yarn.lock',
type: 'yarn',
allowedHosts: ['npm', 'yarn'],
validateHttps: true
}
``

The configuration file will be resolved starting from the current working directory, and searching up the file tree until a config file is (or isn't) found. Command-line options take precedence over any file-based configuration.

The options accepted in the configuration file are the same as the options above in camelcase (e.g. "path", "allowedHosts").

References

- This package aliasing article explains the rational for error reporting on package aliases in lockfiles.
- Why npm lockfiles can be a security blindspot for injecting malicious modules

Contributing

Please consult CONTRIBUTING for guidelines on contributing to this project.

Author

lockfile-lint © Liran Tal, Released under the Apache-2.0 License.