myndzi / node-license-validator

Validate the licenses of your dependencies against a list

Node-license-validator

This module is a programmatic and command line tool to help you validate the licenses of your dependencies against an allowed list. It is suitable for use in a build process. It utilizes nlf, semver, and spdx.

Installation

Global command

npm install -g node-license-validator

Package local

npm install --save node-license-validator

For easy access, modify package.json to include it as a script:

{
  "scripts": {
    "nlv": "node-license-validator"
  }
}

And run it with npm run nlv -- --allow-licenses [etc]. Note that you need npm >= 2.0 to pass arguments in this way to scripts.

Command line usage

Courtesy of yargs:

Usage: node-license-validator [dirname] [options]

Options:
  -h, --help        Show help.                                                                                                     [boolean]
  -q, --quiet       Don't output anything.                                                                                         [boolean]
  -v, --verbose     Detailed list of package licenses.                                                                             [boolean]
  --dir             Base directory of package to validate. Defaults to current working directory.
  --list-licenses   Don't validate; just list the licenses in use.                                                                 [boolean]
  --warn            Only print invalid licenses, don't exit with error                                            [boolean] [default: false]
  --allow-licenses  A list of licenses to allow. Validation will fail if a package is present that is not licensed under any of the licenses
                    in this list.                                                                                                    [array]
  --allow-packages  A list of packages to allow. Can be used to allow packages for which the license is not detected correctly (can happen
                    with old package.json formats). Optionally may use package.json-style semver directives to match a version or range of
                    versions.                                                                                                        [array]
  -d, --deep        Perform a deep search against all sub-dependencies.                                           [boolean] [default: false]
  -p, --production  Only traverse dependencies, no dev-dependencies                                               [boolean] [default: false]

Examples:
  node-license-validator ~/project --allow-licenses WTFPL ISC MIT  Allow the WTFPL, ISC, and MIT licenses.
  node-license-validator ~/project --allow-packages convict        Allow the package 'convict'.
  node-license-validator ~/project --allow-packages pg@^3.6.0      Allow the package 'pg' (3.6.0 and up, but not 4.0.0 or higher).

Sample successful output:

$ node-license-validator --allow-licenses ISC MIT BSD-3-Clause
Identified licenses: BSD-3-Clause,ISC,MIT
All licenses ok.

Verbose output:

$ node-license-validator -v --allow-licenses ISC MIT BSD-3-Clause
Identified licenses: BSD-3-Clause,ISC,MIT
- [email protected]: BSD-3-Clause
- [email protected]: MIT
- [email protected]: MIT
- [email protected]: MIT
- [email protected]: ISC
- [email protected]: ISC
- [email protected]: ISC
- [email protected]: MIT
- [email protected]: MIT
- [email protected]: MIT
All licenses ok.

Failure output:

$ node-license-validator -v --allow-licenses ISC MIT
Invalid license: [email protected]: BSD-3-Clause

Exit codes

node-license-validator exits with a 0 on success, a 1 on license failure, and a 2 on an error.

Programmatic usage

All arguments are required (including the licenses and packages arrays, even if empty)

var nlv = require('node-license-validator');
nlv(packageDir, {
    licenses: [ 'MIT', 'ISC' ],
    packages: [ ]
}, function (err, data) {
    // ...
});

data will contain an object that looks like this:

{
    packages: {
        '[email protected]': 'BSD-3-Clause, Apache-2.0',
        '[email protected]': 'MIT',
        '[email protected]': 'ISC'
    },
    licenses: [ 'MIT', 'ISC' ],
    invalids: [ '[email protected]' ]
}

packages contains an object mapping the exact module names and versions that are installed to the licenses they specify. If node-license-validator was unable to validate a module's license(s), the license string will include any and all possible licenses that could be found (by nlf) for that module. If a module was valid, the license string will be the first license or spdx rule that was acceptable.

licenses is just a convenience that collects the set of distinct licenses represented by the target module's dependencies.

invalids contains a list of module references for all dependencies that failed to validate.

Specifying licenses

This is fairly straightforward but there are some details. node-license-validator first attempts to interpret allowed licenses as spdx license IDs, as expected by the latest package.json documentation. When the inspected dependency's license specification is a valid SPDX license expression, and at least one of the allowed licenses is a valid SPDX license ID, they are compared to determine compatibility.

If the SPDX check fails, a plain string comparison is attempted between the dependency's specified license(s) and the complete list of allowed licenses.

If both license checks fail, the dependency is checked against the exceptions (below); if this check also fails, the dependency fails validation.

Caveat: if nlv cannot determine any license for a package, it will specify the license as Unknown. It is valid to add this as an acceptable license, but not advisable.

Specifying exceptions

If for some reason nlv is unable to parse a module's package.json, or if you want to allow a specific module without allowing its license globally, you may specify allowed packages individually. You do this with the --allow-packages command line switch or the packages options key. Allowed packages are strings that contain either a package name or an npm install-compatible package specification. For example, you can specify pg@^3.6.0 or convict or @scope/private-module.

node-license-validator's Issues

Crashes on licenses with spaces in it

Someone uses "Apache 2.0" as license identifier. When I try to pass it in the --allow-licenses argument, `node-license-validator crashes:

/path/to/node-license-validator/index.js:63
        acc[cur.toLowerCase()] = cur;
                ^

Multiple versions of the same package

I'm running into an issue where my package has deep dependencies on multiple versions of the same package with different license string. I can't seem to permit more than one using --allow-packages.

Abbreviated example of the relevant data:

# Specify multiple versions of the same package as exceptions
> cat node-license-validator.json
{
  "deep": true,
  "production": true,
  "licenses": [ "MIT" ],
  "allow-packages": [
    "[email protected]",
    "[email protected]"
  ]
}

# Both versions exist within the dependency tree.
# Top level dependencies are [email protected] and [email protected] (to reproduce this problem)
> npm ls
...
├─┬ [email protected]
...
│ ├─┬ [email protected]
│ │ └─┬ [email protected]
│ │   └── [email protected]
...
├─┬ [email protected]
...
│ ├─┬ [email protected]
...
│ │ ├─┬ [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ ├─┬ [email protected]
...

# Blows up! Note that v0.6.1 is exempted correctly.
> node-license-validator
Invalid license: [email protected]: MIT/X11

It looks like the problem lies in the mapping by package name which drops the version. Multiple versions will simply override each other.
See:

node-license-validator/index.js

Line 60 in 72df7bf

acc[cur.toLowerCase()] = cur;

Any ideas on how to write a test case and fix for this? I looked but couldn't crack it just yet.

In the mean time my workaround is to have an exception for the package name without any version or use a semver range that includes both.

NPM 3 support for production

@myndzi Seems like since I upgraded to NPM 3 the --production flag is ignored. I get warnings for all dependencies. Is it because they are now installed in a flat directory structure?

Standalone configuration

I love this tool. Thanks for creating it!

I'm finding that the list of exceptions grows too big for a reasonable single line in package.json.

Example:

{
  "scripts": {
    "audit": "node-license-validator --deep --production --allow-licenses ISC MIT BSD WTFPL BSD-2-Clause BSD-3-Clause Apache-2.0 CC-BY-3.0 Unlicense --allow-packages [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected]",

Is it possible to specify allowed licenses and allowed packages in a standalone file? E.g. .nlvrc or nlv.json perhaps. Alternatively they could be specified in package.json under a unique property like nlv (similar to how browserify works).

If you like the idea let me know. Happy to take a shot at this.

Ignore/warn on unknown license for the package being inspected

Don't include the license of the package we're inspecting in the list; if it is unknown, display a warning pointing that out.

Doesn't work with spdx 0.4.2

Because of kemitchell/spdx.js#16, node-license-validator doesn't work with spdx 0.4.2.
Have to specific spdx version to 0.4.1 in package.json:

"spdx": "0.4.1",

Display unknown packages when listing licenses

node-license-validator -l will display 'Unknown' when there are dependent packages it was unable to determine the license of -- but it won't tell you which or how many. Expand on this a little.