nazar-audit

A modern, security-conscious package vulnerability scanner for the JavaScript ecosystem.

Named after the nazar, the protective eye amulet found across the Mediterranean that wards off malicious intent.

Features

• Wraps npm audit --json with structured output and exit code control
• Exception management with expiry dates, notes, and audit trail (.nazar.yml)
• Multiple output formats: colored table with severity breakdown, normalized JSON
• Dependency paths showing the full chain for each advisory
• Fix availability display showing upgrade paths and breaking change warnings
• Severity thresholds that independently control exit behavior and table display
• Fail-on modes for CI -- fail only on fixable vulnerabilities (--fail-on upgradable|patchable)
• Secure by design -- uses execFile (no shell injection), validates all external data with Valibot
• Windows compatible -- handles npm.cmd shims automatically
• Five runtime dependencies: citty, yaml, picocolors, valibot, nanospinner

Installation

npm install -g nazar-audit
# or
npx nazar-audit

Quick Start

# Run an audit
nazar-audit

# Set severity threshold (exit non-zero only for high+)
nazar-audit --level high

# Ignore specific advisories
nazar-audit --ignore GHSA-xxxx,CVE-2024-1234

# JSON output (suppresses banner and spinner)
nazar-audit --format json

# Filter table display while keeping full exit behavior
nazar-audit --level moderate --filter-table high

# Only fail CI when a fix is actually available
nazar-audit --fail-on upgradable

# Skip devDependencies
nazar-audit --production

# Custom timeout for slow registries
nazar-audit --timeout 120

Configuration

Create a .nazar.yml file in your project root to manage exceptions and defaults:

# Minimum severity for non-zero exit
level: high

# Which vulnerabilities count toward exit code: all (default), upgradable, patchable
failOn: upgradable

# npm audit timeout in seconds (default: 60)
timeoutSeconds: 120

# Skip devDependencies
production: false

exceptions:
  - id: "GHSA-xxxx-yyyy-zzzz"
    expiry: "2025-06-01"
    notes: "No impact -- we don't use the affected API"
    addedBy: "jrodger"

  - module: "minimist"
    notes: "Dev-only transitive dependency, not exposed"

  - id: "CVE-2024-1234"
    active: false
    notes: "Re-enabled after patch lands"

  - id: 1234567
    notes: "Accepted numeric npm advisory source ID"

Exception IDs may be quoted strings such as GHSA, CVE, or UUID-style values, or unquoted integer npm advisory source IDs. Numeric IDs are normalized to strings internally. nazar-audit lists matched exception IDs and package names and warns about unused or expired entries.

CLI Options

| Flag | Alias | Description | |---|---|---| | --level <severity> | -l | Minimum severity for non-zero exit (info, low, moderate, high, critical) | | --filter-table <severity> | | Only show rows at or above this severity in the table | | --format <type> | -f | Output format: table (default) or json | | --ignore <ids> | -i | Advisory IDs to ignore (comma-separated GHSA/CVE) | | --production | -p | Pass --omit=dev to npm audit (default: false) | | --fail-on <mode> | | Which vulnerabilities count toward exit code: all (default), upgradable, patchable | | --timeout <seconds> | | npm audit timeout in seconds (default: 60) | | --config <path> | | Path to .nazar.yml config file |

--level, --format, --filter-table, --production, --fail-on, and --timeout on the CLI take precedence over the matching .nazar.yml values. --ignore merges with (rather than replaces) config-file exceptions.

Exit Codes

| Code | Meaning | |---|---| | 0 | No unhandled vulnerabilities above threshold | | 1 | Unhandled vulnerabilities meeting both --level and --fail-on criteria | | 2 | Scanner error (network, parse failure, invalid config) |

Requirements

• Node.js >= 22.0.0
• npm >= 10 (ships with Node 22+)

Documentation

See the docs folder for the full roadmap and technical details:

• Overview
• Phase 0: MVP
• Phase 1: High Value
• Phase 2: Differentiators
• Phase 3: Aspirational
• Data Model
• Competitive Landscape
• Architecture Decisions

Development

npm install
npm run ship             # full quality gate: audit, depcheck, jscpd, license-check, format, lint, typecheck, build, self-audit, test
npm run test:watch       # vitest in watch mode
npm run test:coverage    # vitest with coverage report
npm run test:mutation    # stryker mutation testing
npm run lint:fix         # auto-fix lint issues
npm run depcheck         # check for unused dependencies (knip)
npm run license-check    # check dependency licenses
npm run jscpd            # check for duplicate code

License

MIT