npq - npm Package Security Auditor

npq is a comprehensive security auditing CLI tool that performs pre-installation checks on npm packages before they are installed. It acts as a safety layer between package managers (npm, yarn, pnpm) and package installation by running multiple security and quality checks ("marshalls") to detect vulnerabilities, malware, typosquatting, deprecated packages, and supply chain risks.

Package Information

• Package Name: npq
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install -g npq or brew install npq
• Minimum Node Version: >=20.13.0

Quick Start

# Install globally
npm install -g npq

# Audit and install a package
npq install express

# Dry run (audit only)
npq install express --dry-run

See Quick Start Guide for detailed setup instructions.

Core Concepts

npq uses a plugin-based "marshall" architecture with 14 security checks organized into three categories:

1. Supply Chain Security: Signatures, provenance, vulnerabilities, author reputation, license verification
2. Package Health: Age, popularity, repository availability, deprecation status, maintainer validation
3. Malware Detection: Install scripts, typosquatting, new binary introductions

Command-Line Usage

# Basic usage
npq install <package> [options]

# Options
--dry-run               Run checks only, don't install
--plain                 Force non-rich text output
--packageManager        Package manager to use (default: npm)
--disable-auto-continue Disable auto-continue countdown, always prompt

Environment Variables

NPQ_PKG_MGR=yarn                    # Use yarn instead of npm
NPQ_DISABLE_AUTO_CONTINUE=true      # Always prompt for confirmation
SNYK_TOKEN=your_token_here          # Snyk API authentication
GITHUB_TOKEN=your_token_here        # GitHub API token for deprecation checks
MARSHALL_DISABLE_AGE=1              # Disable specific marshalls

See Reference: Configuration for complete environment variable list.

Marshall Quick Reference

See Reference: Security Marshalls for detailed documentation.

Exit Codes

type ExitCode = 0 | 1 | -1;

// 0: Success (no errors, or user confirmed installation)
// 1: User aborted operation (Ctrl+C or explicit 'n' response)
// -1: Error occurred (package not found, validation failed, network error, etc.)

Programmatic Usage

const Marshall = require('npq/lib/marshall');

const marshall = new Marshall({
  pkgs: ['express@latest'],
  progressManager: null
});

const results = await marshall.run();
// Returns: Array of MarshallResult objects

See Reference: API for complete programmatic usage documentation.

Resources

Guides

• Quick Start Guide - Getting started with npq
• Integration Guide - Integrating npq into workflows

Examples

• Real-World Scenarios - Common usage patterns and workflows
• Edge Cases - Advanced scenarios and error handling

Reference

• Security Marshalls - Complete marshall documentation
• API Reference - Programmatic usage and types
• Configuration - Environment variables and options
• Error Handling - Error types and handling patterns

Architecture

npq is built around a plugin-based "marshall" architecture:

• CLI Layer (npq and npq-hero): Entry points for interactive and automated usage
• Marshall Orchestration: Coordinates execution of all security checks
• Marshall Implementations: 14 pluggable security checks, each targeting specific risks
• Registry Integration: Queries npm registry, Snyk/OSV APIs, and GitHub for package metadata
• User Interaction: Progress indicators, formatted results, and confirmation prompts

Limitations

1. No Absolute Safety: npq cannot guarantee 100% safety. Malicious packages may pass all checks if no vulnerabilities are publicly disclosed.
2. Network Required: All marshalls require internet access to query npm registry, Snyk/OSV APIs, and GitHub.
3. Rate Limits: Without authentication tokens, GitHub API is limited to 60 requests/hour. Use GITHUB_TOKEN for 5000 requests/hour.
4. Programmatic API Stability: Internal APIs used for programmatic access are not officially supported and may change without notice.

Differences from npm audit

• Timing: npq runs before installation; npm audit runs after
• Scope: npq performs synthetic checks (age, scripts, typosquatting); npm audit only checks CVE database
• User Control: npq prompts for confirmation; npm audit installs regardless of vulnerabilities
• Prevention: npq prevents installation of risky packages; npm audit reports vulnerabilities after installation