Announcing nsp 3.0.0
The Node Security team is excited to announce version 3.0.0 of the nsp CLI tool.
Get it by running npm i nsp@next
This release marks the 3rd major iteration of the CLI. While the changes mentioned below may seem minor the entire CLI was re-written from the ground up by Nathan LaFreniere with the goal of cleaning the code up to the point that will let us implement some amazing features we have planned for Node Security.
Here are some of the notable changes.
Node 6.x and beyond
We are dropping support for Node version below 6.x. If you haven’t upgraded, stop dragging your feet and upgrade. You want all those sweet security patches the Node core team releases for you, don’t you?
Improved Exception Management
The Node Security CLI supports adding exceptions. These are advisories that you have evaluated and personally deemed unimportant or not a risk for your project.
There are two ways to leverage this capability, online or offline. To use online exceptions, register your project on our online portal at https://nodesecurity.io. From there you can manage your exceptions from a central location.
In order to inform the CLI tool that it should use these settings, you’ll have to create a settings file (and login if your project is private). You’ll need both the organization name and the UUID for your project, these can be retrieved from the URL from our portal. For example, if your project is hapi and your project URL is https://nodesecurity.io/orgs/hapi/projects/2a6e5642-b7a1-4b93-b8fb-21c1a5043f42 then your organization name is hapi and your project UUID is 2a6e5642-b7a1–4b93-b8fb-21c1a5043f42.
Using that information, create a .nsprc file with the following content:
{
"org": "hapi",
"integration": "2a6e5642-b7a1–4b93-b8fb-21c1a5043f42"
}When you next run nsp check your exceptions will be retrieved from online. If your project is a private one, you will additionally need to run nsp login which will create another .nsprc file in your home directory with an authentication token that will allow the CLI tool to look up your settings.
We would love feedback on this and will work to make it a better experience over time.
Filters & Thresholds & Exit Codes
There are a couple new flags that we are introducing for the check command: threshold and filter
For example:
nsp check --threshold 4 would show all found vulnerabilities but only have an exit code of 1 if at least one finding has a CVSS above 4
nsp check --filter 4 would entirely ignore all vulnerabilities with CVSS scores below 4
Exit code reference:
0 — Check ran and no vulnerabilities were found
1 — Check ran and vulnerabilities were found that didn’t fall below your threshold or filter.
2 — Server error (5xx)
3 — Some unknown shenanigans happened
4 — Error in the reporter
Proxy Settings
Proxy settings can now be pulled from environment variables (HTTPS_PROXY, HTTP_PROXY). This is a minor improvement but many people wanted this feature.
Improved Offline Mode
Offline mode used to be a bit painful to get setup and a bit broken. To get setup to use offline mode, you run nsp gather to collect all the advisories. This will create an advisories.json file in the current directory containing an archive of all current advisories.
Then run nsp check --offline
or optionally (if advisories.json is not in the same directory as your project) nsp check --offline --advisories /path/to/advisories.json
Output Reporters:
Output reporters used to be called formatters. They are responsible for outputting the result of a command. The structure of these have completely changed, so if you were using a custom formatter you’ll need to make some changes for it to work as a reporter.
Output reporters consist of exported error and success handlers.
For example
exports.error = function (err, args) {}
exports.success = function (result, args) {}
For error handlers, the err is an actual Error object. For success result is an object containing the following keys:
{"message": "A string summary of the command result","data": "Result of the command. Will vary from command to command.","meta": "Detailed information about behind the scenes stuffs"}
For both functions args is a copy of the command line arguments that were passed in, this is useful for checking for things like the--verbose flag.
Reporters can also specify custom output for each command that is run. For example, if you wanted output for the check command to go to slack but all other output to go to the console the reporter to do that would look something like this.
exports.error = function (err, args) { console.error(err);}exports.success = function (result, args) { console.log(result);}exports.check = {};exports.check.success = function (result, args) { return new Promise((resolve, reject) => { // Do some slack logic return resolve(); })}
As always feedback is welcome, so create an issue at https://github.com/nodesecurity/nsp/issues or drop us an email at support@nodesecurity.io and we’ll do our best to make Node Security great for you.
