@whittjs/better-npm-audit 3.12.0

package/README.md

@@ -0,0 +1,182 @@
+# Better NPM Audit
+
+The goal of this project is to provide additional features on top of the existing npm audit options. We hope to encourage more people to do security audits for their projects.
+
+[![NPM](https://nodei.co/npm/better-npm-audit.png)](https://npmjs.org/package/better-npm-audit)
+
+![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square) ![npm downloads](https://img.shields.io/npm/d18m/better-npm-audit) ![node current](https://img.shields.io/node/v/better-npm-audit) ![node support](https://img.shields.io/badge/node-up_to_v22-brightgreen) ![npm vulnerability](https://snyk.io/test/github/jeemok/better-npm-audit/badge.svg?targetFile=package.json) ![GitHub issues](https://img.shields.io/github/issues/jeemok/better-npm-audit?style=flat-square) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/better-npm-audit?style=flat-square) ![Languages](https://img.shields.io/github/languages/top/jeemok/better-npm-audit?style=flat-square)
+
+## Looking for Collaborators
+
+Hi there! 👋
+
+I’m currently looking for collaborators to help maintain and develop this project. Due to time constraints, I haven’t been able to give it the attention it deserves, but I believe it has great potential to grow with the help of passionate contributors.
+
+Become a Collaborator
+If you’re interested in contributing on a regular basis, I’d love to have you on board as a collaborator. Whether you’re interested in fixing bugs, adding new features, or improving documentation, your contributions will be highly valued.
+
+As a collaborator, you’ll have push access to the repository and play a key role in shaping the future of the project. If this sounds like something you’d be interested in, please reach out! You can open an issue titled “Interested in Collaborating” or contact me directly via email.
+
+Let’s work together to make this project even better!
+
+## NPM version 6 and 7, and 8
+
+NPM has upgraded to version 7 in late 2020 and has breaking changes on the `npm audit`. The output of npm audit has significantly changed both in the human-readable and `--json` output styles. Even more unfortunately, when NPM changed the JSON output in npm v7, they removed many of the other useful identifiers (`cves`, `cwe`, `github_advisory_id`) and the only thing left is the URL. We are trying our best to handle each version and provide consistent functionality to all of them. Related docs on v6 and v7 changes:
+
+| Docs                       | Link                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| NPM v6 & v7 changes        | https://github.blog/2020-10-13-presenting-v7-0-0-of-the-npm-cli/                           |
+| NPM v7 blog post           | https://blog.npmjs.org/post/626173315965468672/npm-v7-series-beta-release-and-semver-major |
+| Official NPM v6 audit docs | https://docs.npmjs.com/cli/v6/commands/npm-audit                                           |
+| Official NPM v7 audit docs | https://docs.npmjs.com/cli/v7/commands/npm-audit                                           |
+| Dealing with new npm audit | https://uko.codes/dealing-with-npm-v7-audit-changes                                        |
+
+You may find the sample JSON outputs for each NPM versions in our codebase: [v6](https://github.com/jeemok/better-npm-audit/blob/master/test/__mocks__/v6-json-buffer.json), [v7](https://github.com/jeemok/better-npm-audit/blob/master/test/__mocks__/v7-json-buffer.json) & [v8](https://github.com/jeemok/better-npm-audit/blob/master/test/__mocks__/v8-json-buffer.json).
+
+<br />
+
+## Installation
+
+    $ npm install --save better-npm-audit
+
+or
+
+    $ npm install -g better-npm-audit
+
+<br />
+
+## Usage
+
+### Run global
+
+```bash
+better-npm-audit audit
+```
+
+### Run with exceptions
+
+<img src="./.README/all_good.png" alt="Demo of table displaying the security report" />
+
+Unhandled or newly reported vulnerabilities will be highlighted:
+
+<img src="./.README/highlighted_exceptions.png" alt="Demo of table displaying the security report" />
+
+Unused exceptions will be notified:
+
+<img src="./.README/unused_exception.png" alt="Demo of displaying the unused exception" />
+
+### Add into package scripts
+
+```JSON
+{
+  "scripts": {
+    "prepush": "npm run test && npm run audit",
+    "audit": "better-npm-audit audit"
+  }
+}
+```
+
+Now you can run locally or in your CI pipeline:
+
+```bash
+npm run audit
+```
+
+### Filter vulnerability table
+
+You can filter the vulnerability table to show only vulnerabilities at or above a specified severity level using the `--filter-table` flag. This is useful for reducing noise in the output while maintaining the original audit behavior for exit codes.
+
+```bash
+# Filter table to show only high and critical vulnerabilities
+better-npm-audit audit --filter-table high
+
+# Filter table to match the audit level
+better-npm-audit audit --level moderate --filter-table
+
+# Set different levels for exit behavior vs table display
+better-npm-audit audit --level high --filter-table moderate
+```
+
+**Note:** The `--filter-table` flag only affects what vulnerabilities are displayed in the table. The audit level (`--level`) still controls the exit behavior and vulnerability counting.
+
+<br />
+
+## Options
+
+| Flag                | Short | Description                                                                                           |
+| ------------------- | ----- | ----------------------------------------------------------------------------------------------------- |
+| `--exclude`         | `-x`  | Exceptions or the vulnerabilities ID(s) to exclude; the ID can be the numeric ID, CVE, CWE or GHSA ID |
+| `--module-ignore`   | `-m`  | Names of modules to exclude                                                                           |
+| `--level`           | `-l`  | The minimum audit level to validate; Same as the original `--audit-level` flag                        |
+| `--filter-table`    | `-f`  | Filter the vulnerability table to show only vulnerabilities at or above the specified level. Accepts a level (`info`, `low`, `moderate`, `high`, `critical`) or can be used as a boolean flag to filter by the audit level |
+| `--production`      | `-p`  | Skip the `devDependencies`                                                                            |
+| `--registry`        | `-r`  | The npm registry url to use                                                                           |
+| `--include-columns` | `-i`  | Columns to include in report. Available columns: `ID`, `Module`, `Title`, `Paths`, `Severity`, `URL`, `Ex.`, `Fix` (e.g. `-i Module,Title,Severity`) |
+
+<br />
+
+## Environment Variables
+
+| Variable                 | Description                                                                                                                |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `NO_COLOR`               | Support the [no-color standard](https://no-color.org/) to allow users use the tool without colored output.                 |
+| `NPM_CONFIG_AUDIT_LEVEL` | Used in setting the audit level. <br /> _Note: this will be disregard if the audit level flag is passed onto the command._ |
+
+<br />
+
+## Using `.nsprc` file to manage exceptions
+
+You may add a file `.nsprc` to your project root directory to manage the exceptions. For example:
+
+```json
+{
+  "1337": {
+    "active": true,
+    "notes": "Ignored since we don't use xxx method",
+    "expiry": 1615462134681
+  },
+  "4501": {
+    "active": false,
+    "notes": "Ignored since we don't use xxx method"
+  },
+  "CWE-471": "CWE ID is acceptable",
+  "GHSA-ww39-953v-wcq6": "GHSA ID is acceptable",
+  "https://npmjs.com/advisories/1213": "Full or partial URL is acceptable too"
+}
+```
+
+### Fields
+
+| Attribute | Type             | Description                                               | Default | Examples                                                                                                                                                                                                                                                                                                                     |
+| --------- | ---------------- | --------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `active`  | Boolean          | If the tool should use it for exception                   | `true`  | `true`                                                                                                                                                                                                                                                                                                                       |
+| `expiry`  | String \| Number | Human-readable date, or milliseconds since the UNIX Epoch |         | - `'2020-01-31'` <br> - `'2020/01/31'` <br> - `'01/31/2021, 11:03:58'` <br> - `'1 March 2016 15:00'` <br> - `'1 March 2016 3:00 pm'` <br> - `'2012-01-26T13:51:50.417-07:00'` <br> - `'Sun, 11 Jul 2021 03:03:13 GMT'` <br> - `'Thu Jan 26 2017 11:00:00 GMT+1100 (Australian Eastern Daylight Time)'` <br> - `327611110417` |
+| `notes`   | String           | Notes related to the vulnerability.                       |         |
+
+<br />
+
+When using a `.nsprc` file, a report will be displayed when it starts running:
+
+<img src="./.README/exceptions_table.png" alt="Demo of table displaying a list of exceptions" />
+
+> Note: the expiry date will be styled in yellow and red color if it is detected more than one or five years ago.
+
+<br />
+
+## Changelog
+
+You can find the changelog [here](https://github.com/jeemok/better-npm-audit/blob/master/CHANGELOG.md).
+
+<br />
+
+## Contributors
+
+[Ian Wright](https://github.com/IPWright83), [Edwin Taylor](https://github.com/alertme-edwin), [Maarten Hus](https://github.com/MrHus), [Alex Burkowsky](https://github.com/alexburkowskypolysign), [David M. Lee](https://github.com/leedm777), [Kyle Clark](https://github.com/kyle-clark1824), [Guillermo Pincay](https://github.com/guillermaster), [Grzegorz Pawłowski](https://github.com/GrzesiekP), [CSLTech](https://github.com/CSLTech), [Paul Clarkin](https://github.com/paulclarkin), [mgdodge](https://github.com/mgdodge), [Ricky Sullivan](https://github.com/rickysullivan), [Sam Gregory](https://github.com/samgregory88), [Tristan WAGNER](https://github.com/tristanwagner), [Zak](https://github.com/ZedLove), [Eric Cornelissen](https://github.com/ericcornelissen), [Gaurav Chinavle](https://github.com/GauravChinavle)
+
+<br />
+
+---
+
+If you like this project,
+
+<a href="https://www.buymeacoffee.com/jeemok" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></a>

package/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callback = void 0;
+var commander_1 = require("commander");
+var child_process_1 = require("child_process");
+var handleInput_1 = __importDefault(require("./src/handlers/handleInput"));
+var handleFinish_1 = __importDefault(require("./src/handlers/handleFinish"));
+var package_json_1 = __importDefault(require("./package.json"));
+var MAX_BUFFER_SIZE = 1024 * 1000 * 50; // 50 MB
+var program = new commander_1.Command();
+/**
+ * Run audit
+ * @param  {String} auditCommand    The NPM audit command to use (with flags)
+ * @param  {String} auditLevel      The level of vulnerabilities we care about
+ * @param  {Array}  exceptionIds    List of vulnerability IDs to exclude
+ * @param  {Array} modulesToIgnore  List of vulnerable modules to ignore in audit results
+ * @param  {Array} columnsToInclude List of columns to include in audit results
+ * @param  {String} filterLevel     Optional level to filter table display
+ */
+function callback(auditCommand, auditLevel, exceptionIds, modulesToIgnore, columnsToInclude, filterLevel) {
+    // Increase the default max buffer size (1 MB)
+    var audit = (0, child_process_1.exec)("".concat(auditCommand, " --json"), { maxBuffer: MAX_BUFFER_SIZE });
+    // Grab the data in chunks and buffer it as we're unable to parse JSON straight from stdout
+    var jsonBuffer = '';
+    if (audit.stdout) {
+        audit.stdout.on('data', function (data) { return (jsonBuffer += data); });
+    }
+    // Once the stdout has completed, process the output
+    if (audit.stderr) {
+        audit.stderr.on('close', function () { return (0, handleFinish_1.default)(jsonBuffer, auditLevel, exceptionIds, modulesToIgnore, columnsToInclude, filterLevel); });
+        // stderr
+        audit.stderr.on('data', console.error);
+    }
+}
+exports.callback = callback;
+program.name(package_json_1.default.name).version(package_json_1.default.version);
+program
+    .command('audit')
+    .description('execute npm audit')
+    .option('-x, --exclude <ids>', 'Exceptions or the vulnerabilities ID(s) to exclude.')
+    .option('-m, --module-ignore <moduleNames>', 'Names of modules to ignore.')
+    .option('-l, --level <auditLevel>', 'The minimum audit level to validate.')
+    .option('-f, --filter-table [level]', 'Filter table to show only vulnerabilities at or above specified level (defaults to audit level if no value provided).')
+    .option('-p, --production', 'Skip checking the devDependencies.')
+    .option('-r, --registry <url>', 'The npm registry url to use.')
+    .option('-i, --include-columns <columnName1>,<columnName2>,..,<columnNameN>', 'Columns to include in report.')
+    .action(function (options) { return (0, handleInput_1.default)(options, callback); });
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,78 @@
+{
+    "name": "@whittjs/better-npm-audit",
+    "version": "3.12.0",
+    "author": "Jee Mok <jee.ict@hotmail.com>",
+    "description": "Reshape into a better npm audit for the community and encourage more people to include security audit into their process.",
+    "license": "MIT",
+    "main": "index.js",
+    "bin": {
+        "better-npm-audit": "index.js"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/WhittJS/better-npm-audit"
+    },
+    "engines": {
+        "node": ">= 8.12"
+    },
+    "scripts": {
+        "preaudit": "npm run build",
+        "audit": "node lib audit -x 1064843,1067245",
+        "test": "mocha -r ts-node/register test/**/*.test.ts",
+        "lint": "eslint .",
+        "qc": "npm run test && npm run lint",
+        "clean": "rimraf lib",
+        "prebuild": "npm run qc && npm run clean",
+        "build": "tsc",
+        "postbuild": "cp README.md lib && chmod +x ./lib/index.js",
+        "publish:live": "npm run build && npm publish ./lib --tag latest",
+        "publish:next": "npm run build && npm publish ./lib --tag next"
+    },
+    "dependencies": {
+        "commander": "^8.0.0",
+        "dayjs": "^1.10.6",
+        "lodash.get": "^4.4.2",
+        "semver": "^7.6.3",
+        "table": "^6.7.1"
+    },
+    "devDependencies": {
+        "@types/chai": "^4.2.19",
+        "@types/lodash.get": "^4.4.6",
+        "@types/mocha": "^8.2.3",
+        "@types/node": "^16.0.0",
+        "@types/semver": "^7.5.8",
+        "@types/sinon": "^10.0.2",
+        "@typescript-eslint/eslint-plugin": "^4.28.2",
+        "@typescript-eslint/parser": "^4.28.2",
+        "chai": "^4.3.0",
+        "eslint": "^7.25.0",
+        "eslint-config-google": "^0.14.0",
+        "eslint-config-prettier": "^8.3.0",
+        "eslint-plugin-prettier": "^3.4.0",
+        "mocha": "^10.7.3",
+        "prettier": "2.3.2",
+        "rimraf": "^3.0.2",
+        "sinon": "^9.2.4",
+        "ts-node": "^10.0.0",
+        "typescript": "^4.3.5"
+    },
+    "keywords": [
+        "npm",
+        "audit",
+        "skip",
+        "ignore",
+        "exclude",
+        "exceptions",
+        "node",
+        "security",
+        "advisory",
+        "vulnerabilities",
+        "continuous integration",
+        "dependencies",
+        "check",
+        "build",
+        "script",
+        "nsp",
+        "ci"
+    ]
+}

package/src/handlers/handleFinish.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var print_1 = require("../utils/print");
+var vulnerability_1 = require("../utils/vulnerability");
+/**
+ * Process and analyze the NPM audit JSON
+ * @param  {String} jsonBuffer        NPM audit stringified JSON payload
+ * @param  {Number} auditLevel        The level of vulnerabilities we care about
+ * @param  {Array} exceptionIds       List of vulnerability IDs to exclude
+ * @param  {Array} exceptionModules   List of vulnerable modules to ignore in audit results
+ * @param  {Array} columnsToInclude   List of columns to include in audit results
+ * @param  {String} filterLevel       Optional level to filter table display
+ */
+function handleFinish(jsonBuffer, auditLevel, exceptionIds, exceptionModules, columnsToInclude, filterLevel) {
+    var _a = (0, vulnerability_1.processAuditJson)(jsonBuffer, auditLevel, exceptionIds, exceptionModules, columnsToInclude, filterLevel), unhandledIds = _a.unhandledIds, report = _a.report, failed = _a.failed, unusedExceptionIds = _a.unusedExceptionIds, unusedExceptionModules = _a.unusedExceptionModules;
+    // If unable to process the audit JSON
+    if (failed) {
+        console.error('Unable to process the JSON buffer string.');
+        // Exit failed
+        process.exit(1);
+        return;
+    }
+    // Print the security report
+    if (report.length) {
+        (0, print_1.printSecurityReport)(report, columnsToInclude);
+    }
+    // Handle unused exceptions
+    (0, vulnerability_1.handleUnusedExceptions)(unusedExceptionIds, unusedExceptionModules);
+    // Display the found unhandled vulnerabilities
+    if (unhandledIds.length) {
+        console.error("".concat(unhandledIds.length, " vulnerabilities found. Node security advisories: ").concat(unhandledIds.join(', ')));
+        // Exit failed
+        process.exit(1);
+    }
+    else {
+        // Happy happy, joy joy
+        console.info('🤝  All good!');
+        process.exit(0);
+    }
+}
+exports.default = handleFinish;

package/src/handlers/handleInput.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var lodash_get_1 = __importDefault(require("lodash.get"));
+var semver_1 = __importDefault(require("semver"));
+var npm_1 = require("../utils/npm");
+var file_1 = require("../utils/file");
+var vulnerability_1 = require("../utils/vulnerability");
+/**
+ * Get the `npm audit` flag to audit only production dependencies.
+ * @return {String} The flag.
+ */
+function getProductionOnlyOption() {
+    var npmVersion = (0, npm_1.getNpmVersion)();
+    if (semver_1.default.satisfies(npmVersion, '<=8.13.2')) {
+        return '--production';
+    }
+    else {
+        return '--omit=dev';
+    }
+}
+/**
+ * Handle user's input
+ * @param  {Object} options     User's command options or flags
+ * @param  {Function} fn        The function to handle the inputs
+ */
+function handleInput(options, fn) {
+    // Generate NPM Audit command
+    var auditCommand = [
+        'npm audit',
+        // flags
+        (0, lodash_get_1.default)(options, 'production') ? getProductionOnlyOption() : '',
+        (0, lodash_get_1.default)(options, 'registry') ? "--registry=".concat(options.registry) : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    // Taking the audit level from the command or environment variable
+    var envVar = process.env.NPM_CONFIG_AUDIT_LEVEL;
+    var auditLevel = (0, lodash_get_1.default)(options, 'level', envVar) || 'info';
+    // Process filter table option
+    var filterLevel;
+    var filterTableOption = (0, lodash_get_1.default)(options, 'filterTable');
+    if (filterTableOption) {
+        if (typeof filterTableOption === 'string') {
+            // User provided a specific level for filtering
+            filterLevel = filterTableOption;
+        }
+        else {
+            // User provided true flag, use the audit level
+            filterLevel = auditLevel;
+        }
+    }
+    // Get the exceptions
+    var nsprc = (0, file_1.readFile)('.nsprc');
+    var cmdExceptions = (0, lodash_get_1.default)(options, 'exclude', '')
+        .split(',')
+        .map(function (each) { return each.trim(); })
+        .filter(function (each) { return each !== ''; });
+    var exceptionIds = (0, vulnerability_1.getExceptionsIds)(nsprc, cmdExceptions);
+    var cmdModuleIgnore = (0, lodash_get_1.default)(options, 'moduleIgnore', '').split(',');
+    var cmdIncludeColumns = (0, lodash_get_1.default)(options, 'includeColumns', '')
+        .split(',')
+        .map(function (each) { return each.trim(); })
+        .filter(function (each) { return !!each; });
+    fn(auditCommand, auditLevel, exceptionIds, cmdModuleIgnore, cmdIncludeColumns, filterLevel);
+}
+exports.default = handleInput;

package/src/utils/color.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSeverityBgColor = exports.color = void 0;
+var lodash_get_1 = __importDefault(require("lodash.get"));
+var RESET = '\x1b[0m';
+var COLORS = {
+    reset: {
+        fg: '\x1b[0m',
+        bg: '\x1b[0m',
+    },
+    black: {
+        fg: '\x1b[30m',
+        bg: '\x1b[40m',
+    },
+    red: {
+        fg: '\x1b[31m',
+        bg: '\x1b[41m',
+    },
+    green: {
+        fg: '\x1b[32m',
+        bg: '\x1b[42m',
+    },
+    yellow: {
+        fg: '\x1b[33m',
+        bg: '\x1b[43m',
+    },
+    blue: {
+        fg: '\x1b[34m',
+        bg: '\x1b[44m',
+    },
+    magenta: {
+        fg: '\x1b[35m',
+        bg: '\x1b[45m',
+    },
+    cyan: {
+        fg: '\x1b[36m',
+        bg: '\x1b[46m',
+    },
+    white: {
+        fg: '\x1b[37m',
+        bg: '\x1b[47m',
+    },
+};
+/**
+ * Color a console message's foreground and background
+ * @param  {String} message     Message
+ * @param  {String} fgColor     Foreground color
+ * @param  {String} bgColor     Background color
+ * @return {String}             Message
+ */
+function color(message, fgColor, bgColor) {
+    if ('NO_COLOR' in process.env) {
+        return message;
+    }
+    return [
+        (0, lodash_get_1.default)(COLORS, "".concat(fgColor, ".fg"), ''),
+        (0, lodash_get_1.default)(COLORS, "".concat(bgColor, ".bg"), ''),
+        message,
+        RESET,
+    ].join('');
+}
+exports.color = color;
+/**
+ * Get background color based on severity
+ * @param {String} severity           Vulnerability's severity
+ * @return {(String | undefined)}     Background color or undefined
+ */
+function getSeverityBgColor(severity) {
+    switch (severity) {
+        case 'info':
+            return undefined;
+        case 'low':
+            return undefined;
+        case 'moderate':
+            return undefined;
+        case 'high':
+            return 'red';
+        case 'critical':
+            return 'red';
+        default: {
+            var exhaustiveCheck = severity;
+            return exhaustiveCheck;
+        }
+    }
+}
+exports.getSeverityBgColor = getSeverityBgColor;

package/src/utils/common.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shortenNodePath = exports.trimArray = exports.isJsonString = exports.isWholeNumber = void 0;
+// TODO: This might be unused
+/**
+ * @param  {String | Number | Null | Boolean} value     The input number
+ * @return {Boolean}                                    Returns true if the input is a whole number
+ */
+function isWholeNumber(value) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (!Number(value)) {
+        return false;
+    }
+    return Number(value) % 1 === 0;
+}
+exports.isWholeNumber = isWholeNumber;
+/**
+ * @param  {String} string    The JSON stringified object
+ * @return {Boolean}          Returns true if the input string is parse-able
+ */
+function isJsonString(string) {
+    try {
+        JSON.parse(string);
+    }
+    catch (e) {
+        console.log('Failed parsing .nsprc file: ' + e);
+        return false;
+    }
+    return true;
+}
+exports.isJsonString = isJsonString;
+// TODO: Add unit tests
+/**
+ * Trim array size to a maximum number
+ * @param {Array} array       Array to trim
+ * @param {Number} maxLength  Desired length
+ * @return {Array}            Trimmed array with additional message
+ */
+function trimArray(array, maxLength) {
+    var originalLength = array.length;
+    var removedLength = Math.max(0, originalLength - maxLength);
+    if (removedLength === 0) {
+        return array;
+    }
+    array.length = maxLength;
+    return array.concat("...and ".concat(removedLength, " more"));
+}
+exports.trimArray = trimArray;
+/**
+ * Shorten node path (node_modules/nodemon/node_modules/chokidar/node_modules/fsevents) to (nodemon>chokidar>fsevents)
+ * @param {String} path Full node path
+ * @return {String}     Shorten Path
+ */
+function shortenNodePath(path) {
+    return path.replace('node_modules/', '').replace(/\/node_modules\//g, '>');
+}
+exports.shortenNodePath = shortenNodePath;

package/src/utils/date.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeExpiry = exports.isValidDate = void 0;
+var dayjs_1 = __importDefault(require("dayjs"));
+/**
+ * Validate if the given timestamp is a valid UNIX timestamp
+ * @param   {Any} timestamp   The given timestamp
+ * @return  {Boolean}         Returns true if it is a valid UNIX timestamp
+ */
+function isValidDate(timestamp) {
+    return new Date(timestamp).getTime() > 0;
+}
+exports.isValidDate = isValidDate;
+/**
+ * Analyze the given date time if it has expired (in the past)
+ * @param  {String | Number} expiry     Expiry timestamp
+ * @param  {String | Number} now        The date to compare with
+ * @return {Object}                     Return the analysis
+ */
+function analyzeExpiry(expiry, now) {
+    if (now === void 0) { now = new Date().valueOf(); }
+    if (!expiry) {
+        return { valid: true };
+    }
+    if (!isValidDate(expiry) || !isValidDate(now)) {
+        return { valid: false };
+    }
+    var dayjsNow = (0, dayjs_1.default)(now);
+    return {
+        valid: true,
+        expired: dayjsNow.isAfter(expiry),
+        years: dayjsNow.diff(expiry, 'years'),
+    };
+}
+exports.analyzeExpiry = analyzeExpiry;

package/src/utils/file.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFile = void 0;
+var fs_1 = __importDefault(require("fs"));
+var common_1 = require("./common");
+/**
+ * Read file from path
+ * @param  {String} path          File path
+ * @return {(Object | Boolean)}   Returns the parsed data if found, or else returns `false`
+ */
+function readFile(path) {
+    try {
+        var data = fs_1.default.readFileSync(path, 'utf8');
+        if (!(0, common_1.isJsonString)(data)) {
+            return false;
+        }
+        return JSON.parse(data);
+    }
+    catch (err) {
+        return false;
+    }
+}
+exports.readFile = readFile;

package/src/utils/npm.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNpmVersion = void 0;
+var child_process_1 = require("child_process");
+/**
+ * Get the current npm version
+ * @return {String} The npm version
+ */
+function getNpmVersion() {
+    var version = (0, child_process_1.execSync)('npm --version');
+    return version.toString();
+}
+exports.getNpmVersion = getNpmVersion;

package/src/utils/print.js

@@ -0,0 +1,93 @@
+"use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printExceptionReport = exports.printSecurityReport = exports.getColumnWidth = void 0;
+var lodash_get_1 = __importDefault(require("lodash.get"));
+var table_1 = require("table");
+var SECURITY_REPORT_HEADER = ['ID', 'Module', 'Title', 'Paths', 'Severity', 'URL', 'Ex.', 'Fix'];
+var EXCEPTION_REPORT_HEADER = ['ID', 'Status', 'Expiry', 'Notes'];
+// TODO: Add unit tests
+/**
+ * Get the column width size for the table
+ * @param {Array} tableData     Table data (Array of array)
+ * @param {Number} columnIndex  Target column index
+ * @param {Number} maxWidth     Maximum width
+ * @param {Number} minWidth     Minimum width
+ * @return {Number}             width
+ */
+function getColumnWidth(tableData, columnIndex, maxWidth, minWidth) {
+    if (maxWidth === void 0) { maxWidth = 50; }
+    if (minWidth === void 0) { minWidth = 15; }
+    // Find the maximum length in the column
+    var contentLength = tableData.reduce(function (max, cur) {
+        var content = JSON.stringify((0, lodash_get_1.default)(cur, columnIndex, ''));
+        // Remove the color codes
+        content = content.replace(/\\x1b\[\d{1,2}m/g, '');
+        content = content.replace(/\\u001b\[\d{1,2}m/g, '');
+        content = content.replace(/"/g, '');
+        // Keep whichever number that is bigger
+        return content.length > max ? content.length : max;
+    }, 
+    // Start with minimum width (also auto handling empty column case)
+    minWidth);
+    // Return the content length up to a maximum point
+    return Math.min(contentLength, maxWidth);
+}
+exports.getColumnWidth = getColumnWidth;
+/**
+ * Print the security report in a table format
+ * @param  {Array} data               Array of arrays
+ * @return {undefined}                Returns void
+ * @param  {Array} columnsToInclude   List of columns to include in audit results
+ */
+function printSecurityReport(data, columnsToInclude) {
+    var configs = {
+        singleLine: true,
+        header: {
+            alignment: 'center',
+            content: '=== npm audit security report ===\n',
+        },
+        columns: {
+            // "Title" column index
+            2: {
+                width: getColumnWidth(data, 2),
+                wrapWord: true,
+            },
+            // "Paths" column index
+            3: {
+                width: getColumnWidth(data, 3),
+                wrapWord: true,
+            },
+        },
+    };
+    var headers = columnsToInclude.length ? SECURITY_REPORT_HEADER.filter(function (h) { return columnsToInclude.includes(h); }) : SECURITY_REPORT_HEADER;
+    console.info((0, table_1.table)(__spreadArray([headers], data, true), configs));
+}
+exports.printSecurityReport = printSecurityReport;
+/**
+ * Print the exception report in a table format
+ * @param  {Array} data   Array of arrays
+ * @return {undefined}    Returns void
+ */
+function printExceptionReport(data) {
+    var configs = {
+        singleLine: true,
+        header: {
+            alignment: 'center',
+            content: '=== list of exceptions ===\n',
+        },
+    };
+    console.info((0, table_1.table)(__spreadArray([EXCEPTION_REPORT_HEADER], data, true), configs));
+}
+exports.printExceptionReport = printExceptionReport;

package/src/utils/vulnerability.js

@@ -0,0 +1,365 @@
+"use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleUnusedExceptions = exports.processExceptions = exports.getExceptionsIds = exports.processAuditJson = exports.validateV7Vulnerability = exports.validateV6Vulnerability = exports.mapLevelToNumber = void 0;
+var lodash_get_1 = __importDefault(require("lodash.get"));
+var common_1 = require("./common");
+var color_1 = require("./color");
+var print_1 = require("./print");
+var date_1 = require("./date");
+var MAX_PATHS_SIZE = 5;
+/**
+ * Converts an audit level to a numeric value
+ * @param  {String} auditLevel  Audit level
+ * @return {Number}             Numeric level: the higher the number, the more severe it is
+ */
+function mapLevelToNumber(auditLevel) {
+    switch (auditLevel) {
+        case 'info':
+            return 0;
+        case 'low':
+            return 1;
+        case 'moderate':
+            return 2;
+        case 'high':
+            return 3;
+        case 'critical':
+            return 4;
+        default:
+            return 0;
+    }
+}
+exports.mapLevelToNumber = mapLevelToNumber;
+/**
+ * Validate if the vulnerability should be excepted
+ * @param {Object}  vulnerability   NPM v6 audit report's vulnerability
+ * @param {Array}   exceptionIds    Exception IDs
+ * @return {Object}                 Validation result
+ */
+function validateV6Vulnerability(vulnerability, exceptionIds) {
+    return exceptionIds.reduce(function (acc, id) {
+        // check if ID matches
+        if (id === String(vulnerability.id)) {
+            return { isExcepted: true, usedExceptionKey: id };
+        }
+        // check if any of the CVEs matches
+        if (Array.isArray(vulnerability.cves) && vulnerability.cves.includes(id)) {
+            return { isExcepted: true, usedExceptionKey: id };
+        }
+        // check if the CWE matches
+        if (vulnerability.cwe === id) {
+            return { isExcepted: true, usedExceptionKey: id };
+        }
+        // check if the URL matches
+        if (vulnerability.url && vulnerability.url.includes(id)) {
+            return { isExcepted: true, usedExceptionKey: id };
+        }
+        return acc;
+    }, {
+        isExcepted: false,
+        usedExceptionKey: '',
+    });
+}
+exports.validateV6Vulnerability = validateV6Vulnerability;
+/**
+ * Validate if the vulnerability should be excepted
+ * @param {Object}  vulnerability   NPM v7 audit report's vulnerability
+ * @param {Array}   exceptionIds    Exception IDs
+ * @return {Object}                 Validation result
+ */
+function validateV7Vulnerability(vulnerability, exceptionIds) {
+    return exceptionIds.reduce(function (acc, id) {
+        // check if ID matches
+        if (id === String(vulnerability.source)) {
+            return { isExcepted: true, usedExceptionKey: id };
+        }
+        // check if the URL matches
+        if (vulnerability.url && vulnerability.url.includes(id)) {
+            return { isExcepted: true, usedExceptionKey: id };
+        }
+        return acc;
+    }, {
+        isExcepted: false,
+        usedExceptionKey: '',
+    });
+}
+exports.validateV7Vulnerability = validateV7Vulnerability;
+/**
+ * Analyze the JSON string buffer
+ * @param  {String} jsonBuffer      NPM Audit JSON string buffer
+ * @param  {String} auditLevel      User's target audit level
+ * @param  {Array} exceptionIds     Exception IDs (ID to be ignored)
+ * @param  {Array} exceptionModules Exception modules (modules to be ignored)
+ * @param  {Array} columnsToInclude List of columns to include in audit results
+ * @param  {String} filterLevel     Optional level to filter table display (if not provided, shows all vulnerabilities)
+ * @return {Object}                 Processed vulnerabilities details
+ */
+function processAuditJson(jsonBuffer, auditLevel, exceptionIds, exceptionModules, columnsToInclude, filterLevel) {
+    if (jsonBuffer === void 0) { jsonBuffer = ''; }
+    if (auditLevel === void 0) { auditLevel = 'info'; }
+    if (exceptionIds === void 0) { exceptionIds = []; }
+    if (exceptionModules === void 0) { exceptionModules = []; }
+    if (columnsToInclude === void 0) { columnsToInclude = []; }
+    if (!(0, common_1.isJsonString)(jsonBuffer)) {
+        return {
+            unhandledIds: [],
+            vulnerabilityIds: [],
+            vulnerabilityModules: [],
+            unusedExceptionIds: exceptionIds,
+            unusedExceptionModules: exceptionModules,
+            report: [],
+            failed: true,
+        };
+    }
+    // NPM v6 uses `advisories`
+    // NPM v7 uses `vulnerabilities`
+    // Refer to the `test/__mocks__` folder for some sample mockups
+    var _a = JSON.parse(jsonBuffer), advisories = _a.advisories, vulnerabilities = _a.vulnerabilities;
+    // NPM v6 handling
+    if (advisories) {
+        return Object.values(advisories).reduce(function (acc, cur) {
+            var shouldAudit = mapLevelToNumber(cur.severity) >= mapLevelToNumber(auditLevel);
+            var _a = validateV6Vulnerability(cur, exceptionIds), isIdExcepted = _a.isExcepted, usedExceptionKey = _a.usedExceptionKey;
+            var isModuleExcepted = exceptionModules.includes(cur.module_name);
+            var isExcepted = isIdExcepted || isModuleExcepted;
+            // Record used exception ID/module
+            if (isIdExcepted) {
+                acc.unusedExceptionIds = acc.unusedExceptionIds.filter(function (id) { return id !== usedExceptionKey; });
+            }
+            if (isModuleExcepted) {
+                acc.unusedExceptionModules = acc.unusedExceptionModules.filter(function (module) { return module !== cur.module_name; });
+            }
+            var rowData = [
+                { key: 'ID', value: cur.id.toString() },
+                { key: 'Module', value: cur.module_name },
+                { key: 'Title', value: cur.title },
+                {
+                    key: 'Paths',
+                    value: (0, common_1.trimArray)(cur.findings.reduce(function (a, c) { return __spreadArray(__spreadArray([], a, true), c.paths, true); }, []), MAX_PATHS_SIZE).join('\n'),
+                },
+                { key: 'Severity', value: cur.severity },
+                { key: 'URL', value: cur.url },
+                { key: 'Ex.', value: isExcepted ? 'y' : 'n' },
+                { key: 'Fix', value: 'N/A' },
+            ]
+                .filter(function (_a) {
+                var key = _a.key;
+                return (columnsToInclude.length ? columnsToInclude.includes(key) : true);
+            })
+                .map(function (_a) {
+                var key = _a.key, value = _a.value;
+                return (0, color_1.color)(value, isExcepted ? '' : 'yellow', key === 'Severity' ? (0, color_1.getSeverityBgColor)(cur.severity) : undefined);
+            });
+            // Record this vulnerability into the report based on filter level
+            var shouldIncludeInTable = filterLevel ? mapLevelToNumber(cur.severity) >= mapLevelToNumber(filterLevel) : true;
+            if (shouldIncludeInTable) {
+                acc.report.push(rowData);
+            }
+            acc.vulnerabilityIds.push(cur.id.toString());
+            if (!acc.vulnerabilityModules.includes(cur.module_name)) {
+                acc.vulnerabilityModules.push(cur.module_name);
+            }
+            // Found unhandled vulnerabilities
+            if (shouldAudit && !isExcepted) {
+                acc.unhandledIds.push(cur.id.toString());
+            }
+            return acc;
+        }, {
+            unhandledIds: [],
+            vulnerabilityIds: [],
+            vulnerabilityModules: [],
+            unusedExceptionIds: exceptionIds,
+            unusedExceptionModules: exceptionModules,
+            report: [],
+        });
+    }
+    // NPM v7 handling
+    if (vulnerabilities) {
+        return Object.values(vulnerabilities).reduce(function (acc, cur) {
+            // Inside `via` array, its either the related module name or the vulnerability source object.
+            (0, lodash_get_1.default)(cur, 'via', []).forEach(function (vul) {
+                // The vulnerability ID is labeled as `source`
+                var id = (0, lodash_get_1.default)(vul, 'source');
+                var moduleName = (0, lodash_get_1.default)(vul, 'name', '');
+                // Let's skip if ID is a string (module name), and only focus on the root vulnerabilities
+                if (!id || typeof id === 'string' || typeof vul === 'string') {
+                    return;
+                }
+                var shouldAudit = mapLevelToNumber(vul.severity) >= mapLevelToNumber(auditLevel);
+                var _a = validateV7Vulnerability(vul, exceptionIds), isIdExcepted = _a.isExcepted, usedExceptionKey = _a.usedExceptionKey;
+                var isModuleExcepted = exceptionModules.includes(moduleName);
+                var isExcepted = isIdExcepted || isModuleExcepted;
+                // Record used exception ID/module
+                if (isIdExcepted) {
+                    acc.unusedExceptionIds = acc.unusedExceptionIds.filter(function (id) { return id !== usedExceptionKey; });
+                }
+                if (isModuleExcepted) {
+                    acc.unusedExceptionModules = acc.unusedExceptionModules.filter(function (module) { return module !== moduleName; });
+                }
+                var rowData = [
+                    { key: 'ID', value: String(id) },
+                    { key: 'Module', value: vul.name },
+                    { key: 'Title', value: vul.title },
+                    { key: 'Paths', value: (0, common_1.trimArray)((0, lodash_get_1.default)(cur, 'nodes', []).map(common_1.shortenNodePath), MAX_PATHS_SIZE).join('\n') },
+                    { key: 'Severity', value: vul.severity, bgColor: (0, color_1.getSeverityBgColor)(vul.severity) },
+                    { key: 'URL', value: vul.url },
+                    { key: 'Ex.', value: isExcepted ? 'y' : 'n' },
+                    {
+                        key: 'Fix',
+                        value: (function () {
+                            var fixAvailable = (0, lodash_get_1.default)(cur, 'fixAvailable');
+                            if (typeof fixAvailable === 'object' && fixAvailable !== null && fixAvailable.isSemVerMajor) {
+                                return 'major';
+                            }
+                            return String(Boolean(fixAvailable));
+                        })(),
+                    },
+                ]
+                    .filter(function (_a) {
+                    var key = _a.key;
+                    return (columnsToInclude.length ? columnsToInclude.includes(key) : true);
+                })
+                    .map(function (_a) {
+                    var key = _a.key, value = _a.value, bgColor = _a.bgColor;
+                    return (0, color_1.color)(value, isExcepted ? '' : 'yellow', key === 'Severity' ? bgColor : undefined);
+                });
+                // Record this vulnerability into the report based on filter level
+                var shouldIncludeInTable = filterLevel ? mapLevelToNumber(vul.severity) >= mapLevelToNumber(filterLevel) : true;
+                if (shouldIncludeInTable) {
+                    acc.report.push(rowData);
+                }
+                acc.vulnerabilityIds.push(String(id));
+                if (!acc.vulnerabilityModules.includes(moduleName)) {
+                    acc.vulnerabilityModules.push(moduleName);
+                }
+                // Found unhandled vulnerabilities
+                if (shouldAudit && !isExcepted) {
+                    acc.unhandledIds.push(String(id));
+                }
+            });
+            return acc;
+        }, {
+            unhandledIds: [],
+            vulnerabilityIds: [],
+            vulnerabilityModules: [],
+            unusedExceptionIds: exceptionIds,
+            unusedExceptionModules: exceptionModules,
+            report: [],
+        });
+    }
+    return {
+        unhandledIds: [],
+        vulnerabilityIds: [],
+        vulnerabilityModules: [],
+        unusedExceptionIds: exceptionIds,
+        unusedExceptionModules: exceptionModules,
+        report: [],
+        failed: true,
+    };
+}
+exports.processAuditJson = processAuditJson;
+/**
+ * Process all exceptions and return a list of exception IDs
+ * @param  {Object | Boolean} nsprc           File content from `.nsprc`
+ * @param  {Array}            cmdExceptions   Exceptions passed in via command line
+ * @return {Array}                            List of found vulnerabilities
+ */
+function getExceptionsIds(nsprc, cmdExceptions) {
+    if (cmdExceptions === void 0) { cmdExceptions = []; }
+    // If file does not exists
+    if (!nsprc || typeof nsprc !== 'object') {
+        // If there are exceptions passed in from command line
+        if (cmdExceptions.length) {
+            // Display simple info
+            console.info("Exception IDs: ".concat(cmdExceptions.join(', ')));
+            return cmdExceptions;
+        }
+        return [];
+    }
+    // Process the content of the file along with the command line exceptions
+    var _a = processExceptions(nsprc, cmdExceptions), exceptionIds = _a.exceptionIds, report = _a.report;
+    (0, print_1.printExceptionReport)(report);
+    return exceptionIds;
+}
+exports.getExceptionsIds = getExceptionsIds;
+/**
+ * Filter the given list in the `.nsprc` file for valid exceptions
+ * @param  {Object} nsprc           The nsprc file content, contains exception info
+ * @param  {Array}  cmdExceptions   Exceptions passed in via command line
+ * @return {Object}                 Processed vulnerabilities details
+ */
+function processExceptions(nsprc, cmdExceptions) {
+    if (cmdExceptions === void 0) { cmdExceptions = []; }
+    return Object.entries(nsprc).reduce(function (acc, _a) {
+        var id = _a[0], details = _a[1];
+        var isActive = Boolean((0, lodash_get_1.default)(details, 'active', true)); // default to true
+        var notes = typeof details === 'string' ? details : (0, lodash_get_1.default)(details, 'notes', '');
+        var _b = (0, date_1.analyzeExpiry)((0, lodash_get_1.default)(details, 'expiry')), valid = _b.valid, expired = _b.expired, years = _b.years;
+        // Color the status accordingly
+        var status = (0, color_1.color)('active', 'green');
+        if (expired) {
+            status = (0, color_1.color)('expired', 'red');
+        }
+        else if (!valid) {
+            status = (0, color_1.color)('invalid', 'red');
+        }
+        else if (!isActive) {
+            status = (0, color_1.color)('inactive', 'yellow');
+        }
+        // Color the date accordingly
+        var expiry = (0, lodash_get_1.default)(details, 'expiry');
+        var expiryDate = expiry !== undefined && expiry !== null ? new Date(expiry).toUTCString() : '';
+        // If it was expired for more than 5 years ago, warn by coloring the date in red
+        if (years && years <= -5) {
+            expiryDate = (0, color_1.color)(expiryDate, 'red');
+        }
+        else if (years && years <= -1) {
+            expiryDate = (0, color_1.color)(expiryDate, 'yellow');
+        }
+        acc.report.push([id, status, expiryDate, notes]);
+        if (isActive && !expired) {
+            acc.exceptionIds.push(id);
+        }
+        return acc;
+    }, {
+        exceptionIds: cmdExceptions,
+        report: cmdExceptions.map(function (id) { return [String(id), (0, color_1.color)('active', 'green'), '', '']; }),
+    });
+}
+exports.processExceptions = processExceptions;
+/**
+ * Handle unused exceptions from user: console log them
+ * @param {Array} unusedExceptionIds      List of unused exception IDs
+ * @param {Array} unusedExceptionModules  List of unused exception module names
+ */
+function handleUnusedExceptions(unusedExceptionIds, unusedExceptionModules) {
+    var cleanedUnusedExceptionIds = unusedExceptionIds.filter(Boolean);
+    var cleanedUnusedExceptionModules = unusedExceptionModules.filter(Boolean);
+    var message = [
+        cleanedUnusedExceptionIds.length &&
+            "".concat(cleanedUnusedExceptionIds.length, " of the excluded vulnerabilities did not match any of the found vulnerabilities: ").concat(cleanedUnusedExceptionIds.join(', '), "."),
+        cleanedUnusedExceptionIds.length &&
+            "".concat(cleanedUnusedExceptionIds.length > 1 ? 'They' : 'It', " can be removed from the .nsprc file or --exclude -x flags."),
+        cleanedUnusedExceptionModules.length &&
+            "".concat(cleanedUnusedExceptionModules.length, " of the ignored modules did not match any of the found vulnerabilities: ").concat(cleanedUnusedExceptionModules.join(', '), "."),
+        cleanedUnusedExceptionModules.length &&
+            "".concat(cleanedUnusedExceptionModules.length > 1 ? 'They' : 'It', " can be removed from the --module-ignore -m flags."),
+    ]
+        .filter(Boolean)
+        .join(' ');
+    if (message) {
+        console.warn(message);
+    }
+}
+exports.handleUnusedExceptions = handleUnusedExceptions;