GitHub NPM Report

Objective

Provide a simple report on the NPM packages used in a repository. Provide details on

Current package version
Latest version within the same semantic version number
Latest overall released version
Any known security issues with currently used version

We have a number of different nodejs based projects worked on by different teams. One requirement we have is to be easily able to get a snapshot of all the currently used NPM packages. This would help standardise which packages are being used across projects e.g. all projects use the same package to process command line arguments. We also wanted an easy way of viewing package versions across projects to identify which projects may need to be updated.

In addition to obtaining an overview of what packages are being used within our projects, we need an easy way of getting a snapshot across our projects regarding where we may want to focus update/upgrade processes. This includes being able to see which packages we are using that may have security issues.

Approach

For various reasons, our projects have different layouts with package.json files in different locations. We also have a mix of node versions, so some projects include a package-lock.json file and some do not. We needed an approach which did not care about the repository layout or rely on package-lock.json files (especially with respect to security audits).

The proposed solution is to use the GitHub API to find all package.json and package-lock.json files which is independent of any assumption regarding repository layout. The theory is to use the API to retrieve the relevant blobs, parse them to get the relevant information and then use the npmjs.com API to get additional information from the public registry. At this time, there is no requirement to support queries to other registries. This may be added later.

Finding any relevant API documentation for npmjs.com’s security information has proven difficult. Therefore, the Open source Security Index at https://ossindex.sonatype.org has been used to lookup known security vulnerabilities for NPM packages in the npmjs.com public repository.

Status

This is really an experiment. A number of assumptions have been made which may not hold. At this point, basic reports in org file format are generated. The long-term plan is to have the information recorded in a database and provide a simple web front-end to query and search this information.

Usage

To install and run do the following:

Clone the repository
Run npm install
Create a .github-npm-report.json file in your home directory with the following properties

{
  "username": "github user name",
  "oauthTOken": "github oauth token",
  "ossUser": "ossindex user - it is free to register",
  "ossToken": "ossindex auth token - see oss site for details",
   "ossHost": "ossindex.sonatype.org"
}

Run the script with arguments of github user/organisation name, repostitory name and repository branch e.g.

$ node src/index theophilusx github-npm-report master

Sample Output

Running the command on this repository gives the following output. Note that as there are no vulnerabilities in the current repository, none are shown in the output below. If there were any, an additional Vulnerabilities section would also be included.

Core Dependencies