dep-audit

NPM Dependency Audit Tool

npm install -g dep-audit

Given a path to a configuration file, this module will check that each module in the node_modules tree of the current directory satisfies the requirements established by the configuration file.

dep-audit --config config/config.json

Config file should be formatted like so:

{
    "exclusions":{
        "name":[
            {
                "version_range":"1.0.0-2.1.4", // semver range that is not allowed
                "audit_trail":"Added by admin @ 2016-1-1", // who added it and when
                "desc":"Bad module" // why module isn't allowed
            }
        ]
    },
    "inclusions":{
        "name":[
            {
                "version_range":"1.0.0-2.1.4", // semver range that is allowed
                "audit_trail":"Added by admin @ 2016-1-1", // who added it and when
                "desc":"Bad module" // why module is allowed
            }
        ]
    },
    "spdx":"(MIT OR ISC)" // spdx expression indicating which licenses are ok
}

If a module is not in exclusions or inclusions, it will be allowed if its license satisfies the SPDX expression in spdx. Modules in exclusions will not be allowed even if their license satisfies the spdx expression. Modules in inclusions will be allowed even if their license does not satisfy the spdx expression.

If an unacceptable module that does not satisfy the requirements in the config file is found, dep-audit will log the module as well as its audit trail and description. The process will then exit with exit code 1.

Alternatively, the user can provide a URL to fetch a config file from.

dep-audit --config-url http://....

Hooks

A hook can be provided that will be executed before each module is audited. In order to supply a hook, pass the file path of the module to the hook option.

--hook /path/to/hook/

The file must export a function that takes an object representing the node_modules tree as an argument and returns an object representing the modules from the node_modules tree that should be audited.

module.exports = function (json) {
  return json
}

The node_modules object will be formatted like so using a separate object for each module.

{
  "name@version": {
    "licenses": "ISC",
    "repository": "url to repo",
    "licenseFile": "/path/to/license/file"
  }
}

Options

• --config [path] Path to fetch inclusion list, exclusion list, and spdx expression
• --config-url [url] URL to fetch inclusion list, exclusion list, and spdx expression
• --allowed [list] Audit modules in node_modules tree using list of licenses
• --hook [path] Path to hook to execute before modules are audited
• --fix Attempt to fix incorrect licenses (implemented using spdx-correct)
• --guess Attempt to guess licenses from files other than package.json (implemented using license-checker)
• --version Display the current version
• --help Get help

Using dep-audit programmatically

If dep-audit is installed locally, it can be used as a library rather than a command line tool.

npm install dep-audit

Then, just require the module in your project and you can audit your dependencies programmatically.

var audit = require('dep-audit')
var opts = {
  "hook": function (json) {
    console.log(json)
    return json
  },
  "checker":
    {
      "start": "/path/to/project/",
      "production": true,
        // If true, will only audit production dependencies.
        // If false, will also audit dev dependencies,
      "unknown": false
        // If true, will only check package.json for license.
        // If false, will guess license from other files
    },
  "fix": true, // If true, will fix malformed licenses,
  "spdx": "MIT", // spdx expression indicating which licenses are allowed
  "include": {
    "name":[
        {
            "version_range":"1.0.0-2.1.4", // semver range that is allowed
            "audit_trail":"Added by admin @ 2016-1-1", // who added it and when
            "desc":"Bad module" // why module is allowed
        }
    ]
  },
  "exclude": {
    "name":[
        {
            "version_range":"1.0.0-2.1.4", // semver range that is not allowed
            "audit_trail":"Added by admin @ 2016-1-1", // who added it and when
            "desc":"Bad module" // why module isn't allowed
        }
    ]
  }
}

audit (opts, function (error, report) {
  if (error) {
    throw error
  }
  Object.keys(report.fail).forEach(function (nameVersion) {
    console.log('FAILED', nameVersion, 'because', report.fail[nameVersion])
  })
})

opts.include and opts.exclude should be formatted like the inclusions and exclusions fields of a config file used in the command line tool. That is, opts.include and opts.exclude should be objects where the keys are module names and the values are lists containing objects with version_range, audit_trail, and desc fields.

License

See LICENSE.txt