GitLab parser for NPM Audit

Usage: gitlab-npm-audit-parser [options]

Input: Stdin via pipe
  npm audit --json | gitlab-npm-audit-parser ...
  cat <file> | gitlab-npm-audit-parser ...

Options:

  -V, --version     output the version number
  -o, --out <path>  output filename, defaults to gl-dependency-scanning-report.json
  -h, --help        output usage information

Package Objective

Perform the data translation from an npm audit --json report output to the GitLab.com standardized JSON schema format specifically for ingest of dependency scanning reports of a project.

Why?

GitLab requires a common schema to ingest scanning reports from multiple different dependency auditing tools across different languages. In the JavaScript/TypeScript ecosystem, most of us use npm audit to verify project dependencies but the JSON report is not ingestable by GitLab.com. It requires this package as middleware to translate an npm audit --json report into the standard dependency audit schema before it can be uploaded and ingested as a dependency_scanning artifact. Ingested artifacts can then be used as data sources to generate interactive content embedded in a pipeline results view or Merge Request (MR) webpage.

Why this library? Because it's fast! We used Webpack to generate a self-contained bundle which means we have 0 dependencies to download for production! With NPX you can use this library direct from the cloud with minimal delay at 15.7KB package size. We use Gitlab's published schema repository directly to help construct the output code. For Developers, we also employ linting & automated testing on the codebase to improve the development experience.

Compatibility

INGEST	SUPPORTED?	OUTPUT
npm-audit-report@^1.0.0	yes	JSON file (dependency-scanning-report-format@v14.0.3)
npm-audit-report@^2.0.0	yes	JSON file (dependency-scanning-report-format@v14.0.3)

GitLab.org publishes their security report format to their own Package Repository which is attached to their schema generation repository: gitlab-org/security-report-schemas. This project targets the currently released report-format for Dependency Scanning.

How to use

Install this package into your devDependencies or use npx directly to download the package at runtime. If you opt to download for use at run time, make sure to include the correct scope name for the package since there are multiple versions of this package on npmjs.com.

I recommend the runtime option since this package is only needed in a GitLab specific pipeline and not necessary to be locally installed for developer use.

1# 1. Downloads at runtime use
2npm audit --json | npx @dshbuilds/gitlab-npm-audit-parser -o gl-dependency-scanning.json
3
4# 2. Install in devDependencies
5npm install --save-dev @dshbuilds/gitlab-npm-audit-parser

Add the following job to .gitlab-ci.yml. If you used #2 and it is in your devDependencies you may remove the @<scope> prefix from the following.

1dependency scanning:
2  image: node:10-alpine
3  script:
4    - npm ci
5    - npm audit --json | npx @dshbuilds/gitlab-npm-audit-parser -o
6      gl-dependency-scanning.json
7  artifacts:
8    reports:
9      dependency_scanning: gl-dependency-scanning.json

NOTE: If you use a npm run-script to call npm audit due to set project parameters, this library will ignore any prefixed stdout data prior to the first open bracket for the JSON output. This way npm run --silent is no longer required.

Vulnerability Report

Vulnerability	PKG	Category	In Production Pkg?	Notes
RegExp DoS	trim@<0.0.3	High	No (DevDependency/Linter)	waiting for remark-parse@^9.x.x release, owner will not patch v8.0.3

Contributors

Development Environment

• Use nvm for node version management (see .nvmrc for version requirement)
• Use latest npm version via nvm install-latest-npm

Guidelines

• Code (including Markdown) must pass a linting checks
• Developmental repository must be compatible with NodeJS v12 LTS & npm@^7.0.0
• Distribution build must be compatible with v10
• Must have successful build & pass all test cases in both Node.js v10 LTS, v12 LTS, & v14 LTS
• Releases will have all non-breaking changes in dependencies up-to-date

Test

1# Production build (CLI bundle) & Executes all test cases
2npm run test:prod
3
4# Verifies build process once, then runs tests against local files
5npm test
6npm run test:dev   # enable test watch mode
7
8# Monitor build process & interactive lint
9npm run build-watch

Examples

#	INGEST FILE		OUTPUT FILE
1.	./test/v1_report.json	=>	./test/snapshots/GL-report.1.json
2.	./test/v2_report.json	=>	./test/snapshots/GL-report.2.json

Future Features

• Add -i|--in|--input <file> option for handling file input

• Add support for input redirector <(cat file.txt).

• Add testing, dependency, & closer integration with npm-audit-report library

• Configure a bot to monitor changes/updates to schema & audit reporter repository

Extras

COMING SOON! gitlab-depscan-merger: a solution to create 1 ingestable dependency_scanning report from multiple audit reports overcoming the GitLab pipeline limitation.

Check out my other projects at @dshbuilds on GitHub.com