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

Configuration

Name: tessl/npm-nsp
Author: tessl

NSP supports multiple configuration methods including .nsprc files, environment variables, and command-line options for customizing vulnerability scanning behavior.

Capabilities

.nsprc Configuration Files

NSP uses the rc library to load configuration from .nsprc files in JSON format.

/**
 * Configuration file format (.nsprc)
 * Supports JSON with comments via json-strip-comments
 */
interface NSPConfig {
  /** Array of advisory URLs to exclude from vulnerability reports */
  exceptions?: string[];
  /** Proxy server URL for API requests */
  proxy?: string; 
  /** Path to local advisories file for offline mode */
  advisoriesPath?: string;
}

Configuration File Locations:

NSP searches for .nsprc files in the following order:

Current project directory
User home directory
Command-line arguments override file settings

Usage Examples:

// .nsprc in project root
{
  "exceptions": [
    "https://nodesecurity.io/advisories/123",
    "https://nodesecurity.io/advisories/456"
  ],
  "proxy": "http://proxy.company.com:8080",
  "advisoriesPath": "./local-advisories.json"
}

// .nsprc with comments (supported via json-strip-comments)
{
  // Exclude these advisories after security review
  "exceptions": [
    "https://nodesecurity.io/advisories/123" // Low impact for our use case
  ],
  
  // Corporate proxy configuration
  "proxy": "http://proxy.company.com:8080"
}

Exception Handling

Configure exceptions to exclude specific advisories that have been reviewed and deemed acceptable.

/**
 * Exception format - must be valid Node Security advisory URLs
 * Pattern: https://nodesecurity.io/advisories/[ADVISORY_ID]
 */
interface ExceptionConfig {
  exceptions: string[]; // Array of advisory URLs
}

Exception URL Format:

// Valid exception URLs
const validExceptions = [
  "https://nodesecurity.io/advisories/123",
  "https://nodesecurity.io/advisories/456",
  "https://nodesecurity.io/advisories/789"
];

// Invalid formats (will be rejected)
const invalidExceptions = [
  "123", // Missing URL
  "https://example.com/123", // Wrong domain
  "https://nodesecurity.io/advisories/abc" // Non-numeric ID
];

Usage Examples:

// In .nsprc file
{
  "exceptions": [
    "https://nodesecurity.io/advisories/534" // Prototype pollution in lodash - reviewed and mitigated
  ]
}

// Via library API
nsp.check({
  package: './package.json',
  exceptions: ['https://nodesecurity.io/advisories/534']
}, callback);

// Via CLI
nsp check # Uses exceptions from .nsprc file

Proxy Configuration

Configure proxy servers for environments that require HTTP proxies for external API access.

/**
 * Proxy configuration supports multiple methods
 */
interface ProxyConfig {
  // .nsprc file setting
  proxy?: string;
  
  // Environment variables (checked in order)
  // process.env.https_proxy
  // process.env.HTTPS_PROXY
  
  // Library API option
  // options.proxy
}

Supported Proxy Protocols:

http:// - HTTP proxy
https:// - HTTPS proxy
socks:// - SOCKS v5 proxy with optional authentication
socks5:// - SOCKS v5 proxy with optional authentication
socks4:// - SOCKS v4 proxy
pac+http:// - PAC (Proxy Auto-Configuration) file

Usage Examples:

// .nsprc configuration
{
  "proxy": "http://proxy.company.com:8080"
}

// Environment variable
export HTTPS_PROXY=http://proxy.company.com:8080
nsp check

// With authentication
{
  "proxy": "http://username:password@proxy.company.com:8080"
}

// SOCKS proxy
{
  "proxy": "socks5://proxy.company.com:1080"
}

// Library API
nsp.check({
  package: './package.json',
  proxy: 'http://proxy.company.com:8080'
}, callback);

Advisories Path Configuration

Configure the path to local advisories file for offline mode operation.

/**
 * Advisories path configuration for offline mode
 */
interface AdvisoriesPathConfig {
  advisoriesPath?: string; // Path to local advisories.json file
}

Setup Process:

# 1. Download advisory database
npm run setup-offline

# 2. Configure path in .nsprc
{
  "advisoriesPath": "./advisories.json"
}

# 3. Use offline mode
nsp check --offline

Usage Examples:

// .nsprc configuration
{
  "advisoriesPath": "/path/to/advisories.json"
}

// Relative path (resolved from current working directory)
{
  "advisoriesPath": "./security/advisories.json" 
}

// Library API
nsp.check({
  package: './package.json',
  shrinkwrap: './npm-shrinkwrap.json',
  offline: true,
  advisoriesPath: './advisories.json'
}, callback);

// CLI usage
nsp check --offline --advisoriesPath ./advisories.json

Environment Variables

Environment variables that affect NSP behavior.

/**
 * Environment variables recognized by NSP
 */
interface EnvironmentConfig {
  /** HTTPS proxy URL (lowercase) */
  https_proxy?: string;
  /** HTTPS proxy URL (uppercase) */
  HTTPS_PROXY?: string;
}

Priority Order:

Command-line options (highest priority)
.nsprc file settings
Environment variables (lowest priority)

Usage Examples:

# Set proxy via environment
export HTTPS_PROXY=http://proxy.company.com:8080
nsp check

# Temporary proxy for single command
HTTPS_PROXY=http://proxy.company.com:8080 nsp check

# Mixed configuration (proxy from env, exceptions from .nsprc)
export HTTPS_PROXY=http://proxy.company.com:8080
echo '{"exceptions": ["https://nodesecurity.io/advisories/123"]}' > .nsprc
nsp check

Configuration Validation

NSP validates configuration options using Joi schema validation.

/**
 * Configuration validation rules
 */
interface ConfigValidation {
  exceptions: string[]; // Must be valid advisory URLs matching regex pattern
  proxy: string; // Must be valid URL format
  advisoriesPath: string; // Must be valid file path
}

// Exception URL validation regex: /^https\:\/\/nodesecurity\.io\/advisories\/([0-9]+)$/

Validation Examples:

// Valid configuration
{
  "exceptions": ["https://nodesecurity.io/advisories/123"],
  "proxy": "http://proxy.example.com:8080",
  "advisoriesPath": "./advisories.json"
}

// Invalid configuration (will cause errors)
{
  "exceptions": ["invalid-url"], // Invalid URL format 
  "proxy": "not-a-url", // Invalid proxy URL
  "advisoriesPath": 123 // Should be string
}

Configuration Debugging

Debug configuration loading and resolution:

// Check effective configuration
const Conf = require('rc')('nsp', {
  api: {
    baseUrl: 'https://api.nodesecurity.io'
  }
});

console.log('Loaded configuration:', Conf);
console.log('Exceptions:', Conf.exceptions);
console.log('Proxy:', Conf.proxy);
console.log('Advisories path:', Conf.advisoriesPath);

Install with Tessl CLI