lockfile-lint

A CLI to lint a lockfile for security policies

About

A CLI tool to lint a lockfile for security policies

Install

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.

lockfile-lint --type <yarn|npm> --path <path-to-lockfile> --validate-https --allowed-hosts <host-to-match> --allowed-urls <urls-to-match>

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:

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

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

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

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

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 or lockfile-lint.config.js file that exports an object.

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.