| 1 | <p align="center"><h1 align="center">
|
| 2 | lockfile-lint
|
| 3 |
|
| 4 | </h1>
|
| 5 |
|
| 6 | <p align="center">
|
| 7 | A CLI to lint a lockfile for security policies
|
| 8 | </p>
|
| 9 |
|
| 10 | <p align="center">
|
| 11 | <a href="https://www.npmjs.org/package/lockfile-lint"><img src="https://badgen.net/npm/v/lockfile-lint" alt="npm version"/></a>
|
| 12 | <a href="https://www.npmjs.org/package/lockfile-lint"><img src="https://badgen.net/npm/license/lockfile-lint" alt="license"/></a>
|
| 13 | <a href="https://www.npmjs.org/package/lockfile-lint"><img src="https://badgen.net/npm/dt/lockfile-lint" alt="downloads"/></a>
|
| 14 | <a href="https://travis-ci.org/lirantal/lockfile-lint"><img src="https://badgen.net/travis/lirantal/lockfile-lint" alt="build"/></a>
|
| 15 | <a href="https://codecov.io/gh/lirantal/lockfile-lint"><img src="https://badgen.net/codecov/c/github/lirantal/lockfile-lint" alt="codecov"/></a>
|
| 16 | <a href="https://snyk.io/test/npm/lockfile-lint"><img src="https://snyk.io/test/npm/lockfile-lint/badge.svg" alt="Known Vulnerabilities" data-canonical-src="https://snyk.io/test/npm/lockfile-lint" style="max-width:100%;"></a>
|
| 17 | <a href="https://github.com/nodejs/security-wg/blob/master/processes/responsible_disclosure_template.md"><img src="https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg" alt="Security Responsible Disclosure" /></a>
|
| 18 | </p>
|
| 19 |
|
| 20 | # About
|
| 21 |
|
| 22 | A CLI tool to lint a lockfile for security policies
|
| 23 |
|
| 24 | # Install
|
| 25 |
|
| 26 | ```bash
|
| 27 | npm install --save lockfile-lint
|
| 28 | ```
|
| 29 |
|
| 30 | # Usage
|
| 31 |
|
| 32 | `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.
|
| 33 |
|
| 34 | ```bash
|
| 35 | lockfile-lint --type <yarn|npm> --path <path-to-lockfile> --validate-https --allowed-hosts <host-to-match> --allowed-urls <urls-to-match>
|
| 36 | ```
|
| 37 |
|
| 38 | Supported lockfiles:
|
| 39 | - npm's `package-lock.json` and `npm-shrinkwrap.json`
|
| 40 | - yarn's `yarn.lock`
|
| 41 |
|
| 42 | # Example
|
| 43 |
|
| 44 | 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:
|
| 45 |
|
| 46 | ```bash
|
| 47 | DEBUG=* lockfile-lint --path yarn.lock --type yarn --allowed-hosts npm
|
| 48 | ```
|
| 49 |
|
| 50 | **Example 2**: specify hostnames and enforce the use of HTTPS as a protocol
|
| 51 |
|
| 52 | ```bash
|
| 53 | lockfile-lint --path yarn.lock --allowed-hosts registry.yarnpkg.com --validate-https
|
| 54 | ```
|
| 55 |
|
| 56 | - `--type yarn` is ommitted since lockfile-lint can figure it out on it's own
|
| 57 | - `--allowed-hosts` explicitly set to match yarn's mirror host
|
| 58 |
|
| 59 | **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
|
| 60 |
|
| 61 | ```bash
|
| 62 | lockfile-lint --path yarn.lock --allowed-hosts yarn github.com --allowed-schemes "https:" "git+https:"
|
| 63 | ```
|
| 64 |
|
| 65 | - `--allowed-hosts` explicitly set to match github.com as a host and specifies `yarn` as the alias for yarn's official mirror host
|
| 66 | - `--allowed-schemes` overrides `validate-https` and so it explicitly allows both `https:` and `git+https:` for the github URL
|
| 67 |
|
| 68 | **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`
|
| 69 |
|
| 70 | ```bash
|
| 71 | lockfile-lint --path yarn.lock --allowed-hosts yarn --allowed-urls https://github.com/lirantal/lockfile-lint#d30ce73a3e5977dede29450df1c79b09f02779b2
|
| 72 | ```
|
| 73 |
|
| 74 | - `--allowed-hosts` allows packages from yarn only
|
| 75 | - `--allowed-urls` overrides `allowed-hosts` and allows a specific Github URL to pass validation
|
| 76 |
|
| 77 | # CLI command options
|
| 78 |
|
| 79 | | command line argument | description | implemented |
|
| 80 | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
|
| 81 | | `--path`, `-p` | path to the lockfile | ✅ |
|
| 82 | | `--type`, `-t` | lockfile type, options are `npm` or `yarn` | ✅ |
|
| 83 | | `--validate-https`, `-s` | validates the use of HTTPS as protocol schema for all resources in the lockfile | ✅ |
|
| 84 | | `--allowed-hosts`, `-a` | validates a whitelist 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 | ✅ |
|
| 85 | | `--allowed-schemes`, `-o` | allowed [URI schemes](https://tools.ietf.org/html/rfc2396#section-3.1) such as "https:", "http", "git+ssh:", or "git+https:" | ✅ |
|
| 86 | | `--allowed-urls`, `-u` | allowed URLs (e.g. `https://github.com/some-org/some-repo#some-hash`) | ✅ |
|
| 87 | | `--empty-hostname`, `-e` | allow empty hostnames, or set to false if you wish for a stricter policy | ✅ |
|
| 88 | | `--validate-checksum`, `-c` | check that all resources include a checksum | ❌ PRs welcome |
|
| 89 | | `--validate-integrity`, `-i` | check that all resources include an integrity field | ❌ PRs welcome |
|
| 90 |
|
| 91 | # File-Based Configuration
|
| 92 |
|
| 93 | Lockfile-lint uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for configuration file support. This means you can configure the above options via (in order of precedence):
|
| 94 |
|
| 95 | - A "lockfile-lint" key in your package.json file.
|
| 96 | - A .lockfile-lintrc file, written in JSON or YAML, with optional extensions: .json/.yaml/.yml (without extension takes precedence).
|
| 97 | - A .lockfile-lint.js or lockfilelint.config.js file that exports an object.
|
| 98 | - A .lockfile-lint.toml file, written in TOML (the .toml extension is required).
|
| 99 |
|
| 100 | 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.
|
| 101 |
|
| 102 | The options accepted in the configuration file are the same as the options above in camelcase (e.g. "path", "allowedHosts").
|
| 103 |
|
| 104 | # Contributing
|
| 105 |
|
| 106 | Please consult [CONTIRBUTING](../../CONTRIBUTING.md) for guidelines on contributing to this project.
|
| 107 |
|
| 108 | # Author
|
| 109 |
|
| 110 | **lockfile-lint** © [Liran Tal](https://github.com/lirantal), Released under the [Apache-2.0](./LICENSE) License.
|