A CLI to lint a lockfile for security policies
npm install lockfile-lint
A CLI to lint a lockfile for security policies
A CLI tool to lint a lockfile for security policies
``bash`
npm install --save lockfile-lint
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
Supported lockfiles:
- npm's package-lock.json and npm-shrinkwrap.jsonyarn.lock
- yarn's
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
| 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 | ✅ |
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").
- 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
Please consult CONTRIBUTING for guidelines on contributing to this project.
lockfile-lint © Liran Tal, Released under the Apache-2.0 License.