tessl/npm-nsp

Command line interface for the Node Security Platform to scan Node.js projects for known security vulnerabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Output Formatters

Name: tessl/npm-nsp
Author: tessl

NSP provides multiple built-in formatters for displaying vulnerability results in different formats, plus support for custom third-party formatters.

Capabilities

Built-in Formatters

All built-in formatters follow the same function signature.

/**
 * Format vulnerability scan results for output
 * @param {Error|null} err - Error object if scan failed
 * @param {VulnerabilityResult[]} data - Array of vulnerability results
 * @param {string} pkgPath - Path to the package.json file being scanned
 * @returns {string} Formatted output string
 */
interface FormatterFunction {
  (err: Error | null, data: VulnerabilityResult[], pkgPath: string): string;
}

Default Formatter

Provides colorized table output with detailed vulnerability information including CVSS scores.

/**
 * Default colorized table formatter with full vulnerability details
 * @param {Error|null} err - Error object or null
 * @param {VulnerabilityResult[]} data - Vulnerability results
 * @param {string} pkgPath - Package path
 * @returns {string} Colorized table output
 */
function default(err, data, pkgPath);

Output Features:

Color-coded output using chalk (red for vulnerabilities, green for success)
Tabular format with columns for Name, CVSS, Installed, Vulnerable, Patched, Path, More Info
Automatic terminal width detection for responsive layout
Sorts vulnerabilities by CVSS score (highest first)
Shows total vulnerability count

Usage Example:

const { formatters } = require('nsp');

nsp.check(function(err, results) {
  const output = formatters.default(err, results, './package.json');
  console.log(output);
  // Output: Colorized table with vulnerability details
});

Summary Formatter

Simplified table format showing only essential information.

/**
 * Summary table formatter with essential vulnerability information
 * @param {Error|null} err - Error object or null  
 * @param {VulnerabilityResult[]} data - Vulnerability results
 * @param {string} pkgPath - Package path
 * @returns {string} Summary table output
 */
function summary(err, data, pkgPath);

Output Features:

Simplified table with columns: Name, Installed, Patched, Path, More Info
No CVSS scores or detailed descriptions
Clean table formatting without borders
Color-coded vulnerability count

Usage Example:

const { formatters } = require('nsp');

nsp.check(function(err, results) {
  const output = formatters.summary(err, results, './package.json');
  console.log(output);
  // Output: Clean summary table
});

JSON Formatter

Raw JSON output of vulnerability data for programmatic consumption.

/**
 * JSON formatter for programmatic consumption
 * @param {Error|null} err - Error object or null
 * @param {VulnerabilityResult[]} data - Vulnerability results  
 * @param {string} pkgPath - Package path
 * @returns {string} JSON string output
 */
function json(err, data, pkgPath);

Output Features:

Pretty-printed JSON with 2-space indentation
Complete vulnerability data structure
Error information included if scan failed
Machine-readable format for CI/CD integration

Usage Example:

const { formatters } = require('nsp');

nsp.check(function(err, results) {
  const output = formatters.json(err, results, './package.json');
  
  // Save to file
  fs.writeFileSync('security-report.json', output);
  
  // Parse for programmatic use
  const data = JSON.parse(output);
  console.log(`Found ${data.length} vulnerabilities`);
});

Code Climate Formatter

Code Climate compatible JSON format for integration with Code Climate platform.

/**
 * Code Climate compatible formatter
 * @param {Error|null} err - Error object or null
 * @param {VulnerabilityResult[]} data - Vulnerability results
 * @param {string} pkgPath - Package path  
 * @returns {string} Code Climate JSON format
 */
function codeclimate(err, data, pkgPath);

Output Features:

Code Climate JSON format with required fields
Maps vulnerability data to Code Climate issue format
Includes severity levels based on CVSS scores
Compatible with Code Climate analysis platform

Usage Example:

const { formatters } = require('nsp');

nsp.check(function(err, results) {
  const output = formatters.codeclimate(err, results, './package.json');
  
  // Output for Code Climate
  process.stdout.write(output);
});

None Formatter

Suppresses all output - useful when you only need the exit code.

/**
 * No output formatter - suppresses all output
 * @param {Error|null} err - Error object or null
 * @param {VulnerabilityResult[]} data - Vulnerability results
 * @param {string} pkgPath - Package path
 * @returns {string} Empty string
 */
function none(err, data, pkgPath);

Usage Example:

# CLI usage - only exit code matters
nsp check --output none
echo $? # Check exit code: 0 = no vulnerabilities, 1 = vulnerabilities found

Quiet Formatter

Minimal output formatter for CI/CD environments.

/**
 * Quiet formatter with minimal output
 * @param {Error|null} err - Error object or null
 * @param {VulnerabilityResult[]} data - Vulnerability results  
 * @param {string} pkgPath - Package path
 * @returns {string} Minimal output string
 */
function quiet(err, data, pkgPath);

Usage Example:

const { formatters } = require('nsp');

nsp.check(function(err, results) {
  const output = formatters.quiet(err, results, './package.json');
  
  // Minimal output for logs
  if (output) {
    console.log(output);
  }
});

Custom Formatters

NSP supports third-party formatters following the naming convention nsp-formatter-<name>.

// Custom formatter installation and usage
// 1. Install custom formatter: npm install nsp-formatter-<name>
// 2. Use with CLI: nsp check --output <name>
// 3. Use with library: nsp.getFormatter('<name>')

Custom Formatter Examples:

# Install custom XML formatter
npm install -g nsp-formatter-xml

# Use with CLI
nsp check --output xml

# Use with library
const xmlFormatter = nsp.getFormatter('xml');
const output = xmlFormatter(err, results, pkgPath);

Creating Custom Formatters:

Custom formatters should export a function matching the FormatterFunction interface:

// Example: nsp-formatter-csv
module.exports = function(err, data, pkgPath) {
  if (err) {
    return 'Error,' + err.message;
  }
  
  if (data.length === 0) {
    return 'No vulnerabilities found';
  }
  
  let csv = 'Module,Version,Title,CVSS,Advisory\n';
  data.forEach(vuln => {
    csv += `${vuln.module},${vuln.version},"${vuln.title}",${vuln.cvss_score || 'N/A'},${vuln.advisory}\n`;
  });
  
  return csv;
};

Formatter Selection Priority

When resolving formatter names, NSP follows this priority order:

Built-in formatters - default, summary, json, codeclimate, none, quiet
Custom formatters - nsp-formatter-<name> packages
Fallback - default formatter if no match found

Usage Example:

const nsp = require('nsp');

// This will use built-in json formatter even if nsp-formatter-json exists
const formatter = nsp.getFormatter('json');

// This will use custom formatter if nsp-formatter-xml is installed
const customFormatter = nsp.getFormatter('xml');

Install with Tessl CLI