nsp-api/README.md

Node.js module wrapper for the Node Security Project API

# nsp-api

`nsp-api` is a simple node wrapper for the Node Security Project API.

## Badgers

[![NPM](https://nodei.co/npm/nsp-api.png?downloads=true&stars=true)](https://nodei.co/npm/nsp-api/)

[![Build Status](https://travis-ci.org/nodesecurity/nsp-api.svg?branch=master)](https://travis-ci.org/nodesecurity/nsp-api)[![Dependency Status](https://david-dm.org/nodesecurity/nsp-api.svg)](https://david-dm.org/nodesecurity/nsp-api)![Codecov](https://img.shields.io/codecov/c/github/codecov/example-python.svg)[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/nodesecurity/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
## Usage

```
// require it as a normal node.js module
var nspAPI = require('nsp-api');

// validate a module against Node Security Project database
nspAPI.validateModule(module, version, function (err, results){..});

// validate a full shrinkwrap against Node Security Project database
nspAPI.validateShrinkwrap(shrinkwrap, function (err, results){..});
```

### `validateModule(module, version, callback)`

Retrieve known vulnerabilities for a module from the NSP API.
- `module` a string containing the modules name.
- `version` a string containing the modules version.
- `callback` callback function using the signature `function (err, results)` where:
    - `err` An error generated from the underlying request.
    - `results` An array containing any vulnerabilities.

### `validateShrinkwrap(shrinkwrap, callback)`
Retrieve known vulnerabilities from dependencies in a npm-shrinkwrap object from the NSP API.
- `shrinkwrap` an object generated by parsing a npm-shrinkwrap.json file.
- `callback` callback function using the signature `function (err, results)` where:
    - `err` An error generated from the underlying request.
    - `results` An array containing any vulnerabilities.

## Example

```
var nspAPI = require('nsp-api');

nspAPI.validateModule('tunnel-agent', '0.4.0', function(err, results) {
    console.log(results);
    // undefined // (no vulnerabilities that we know, yet)
});

nspAPI.validateModule('yar', '0.1.0', function(err, results) {
    console.log(results);
    // [{
    //    title: 'Yar Denial-of-Service',
    //    author: 'Reid Burke',
    //    module_name: 'yar',
    //    publish_date: 'Mon Jun 16 2014 12:29:10 GMT-0700 (PDT)',
    //    cves: [ [Object] ],
    //    vulnerable_versions: '<2.2.0',
    //    patched_versions: '>=2.2.0',
    //    url: 'yar-DoS'
    // }]
});

```