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

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:

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.