Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@kimuson/npm-fw) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

npm-fw

npm registry proxy firewall. Blocks vulnerable packages — including transitive dependencies — before they reach node_modules. Falls back to the newest safe version when latest is affected.

Quick Start

npm install -g @kimuson/npm-fw

Per-command wrapper

Prefix any package manager command with npm-fw:

npm-fw npm install axios
npm-fw pnpm add react
npm-fw yarn add lodash

The first run automatically starts a background daemon and routes the command through it. No configuration needed.

Standalone mode

Set npm-fw as your persistent registry so every install goes through it:

npm-fw setup-standalone

This starts the daemon and runs npm config set registry for you. All subsequent npm install / pnpm add / yarn add commands are automatically protected.

Note: The daemon runs as a background process and won't survive a reboot. If installs suddenly fail with connection errors, run npm-fw doctor to check and npm-fw setup-standalone to restart.

To go back to the default registry:

npm config delete registry
npm-fw daemon-stop

How it works

npm-fw runs a local HTTP proxy daemon between your package manager and the npm registry:

npm install axios
  → npm client resolves http://localhost:42424/axios
    → npm-fw proxies to https://registry.npmjs.org/axios
      → checks advisories, filters metadata
        → returns safe response

Tarball requests (/axios/-/axios-1.0.0.tgz) — checks the npm advisory API for the specific version. If a known vulnerability exists at or above the configured severity, the download is blocked with a 403 response.

Metadata requests (/axios) — fetches the full metadata from the upstream registry, then queries the advisory API for all available versions. Versions matching any advisory's vulnerable range are removed from the response. If latest is affected, it is recalculated to the newest safe version — so package managers naturally resolve to a safe version instead.

Advisory results are cached in-memory per package@version, so repeated requests do not cause additional API calls.

npm-fw uses npm's public Bulk Advisory Endpoint — the same endpoint that npm audit and pnpm audit use. Under npm's Open Source Terms, use of this API for your own internal security purposes is permitted. Keep total requests under 5 million per month per individual as per Acceptable Use.

Features

Vulnerability-based blocking — checks every package against npm's security advisory database before download, including transitive dependencies
Metadata filtering — hides vulnerable versions from registry responses and recalculates latest to the newest safe version
Severity threshold — blocks only at or above the configured level (default: high)
Static blocklist — block specific packages or versions regardless of advisories
Drop-in — works with npm, pnpm, yarn, and any npm-registry-compatible client
Zero external service dependencies — only talks to the public npm registry API

CLI Reference

$ npm-fw --help

Usage: npm-fw [options] [command] [command...]

npm registry proxy firewall

Options:
  -V, --version     output the version number
  -h, --help        display help for command

Commands:
  setup-standalone  Set up npm-fw as a persistent registry proxy
  doctor            Check daemon status and npm registry configuration
  daemon-reload     Restart the proxy daemon
  daemon-start      Start the proxy daemon directly (for systemd/launchd)
  daemon-stop       Stop the proxy daemon

Scope and limitations

npm-fw blocks packages with known security advisories (CVEs/GHSAs) registered in the GitHub Advisory Database.

Advisories typically appear in the npm API within hours of publication, but there is no documented SLA — the delay depends on the advisory source (GitHub-reviewed vs. NVD auto-import) and review pipeline timing. This means a window exists between a malicious package being published and npm-fw being able to block it.

For defense in depth, use pnpm's minimalReleaseAge alongside npm-fw. Advisories generally appear within hours, so setting it to 1440 (24 hours, pnpm's default) or higher covers the gap.

npm-fw does not:

Detect novel/zero-day malware — for that, consider hosted threat intel services
Perform static analysis of package code

Similar projects

Project	Approach	Key difference
Takumi Guard	Hosted registry proxy	Proprietary threat intelligence with real-time malware detection (GMO Flatt Security). Free for basic use.
Aikido Safe Chain	Local MITM proxy	Aikido Intel feed for malware blocking + minimum package age filter. Free, no account needed.
Socket Firewall	Local wrapper	Socket's proprietary threat detection. Free tier available.
npm-fw (@kimuson/npm-fw)	Local HTTP proxy	Advisory API only. No external service, no telemetry, no API key. MIT licensed.

npm-fw is the lightest option: it relies solely on npm's public advisory database, requires no third-party service, and collects no data. If you need real-time malware detection beyond published advisories, the other projects fill that gap.

License

MIT