safe-npm-install

Detect risky npm packages before installation by checking install scripts, release freshness, and trust signals.

Problem

Malicious npm packages are a real supply chain risk.

Attackers abuse install-time hooks like preinstall and postinstall, publish suspiciously fresh versions, and rely on trust gaps before the ecosystem notices. By the time npm audit runs, the package may already be in node_modules and its install script may already have executed.

safe-npm-install is built for the question developers actually ask before installing a package:

"What if this package or its newest release is malicious?"

What It Checks

safe-npm-install evaluates real pre-install signals from the npm registry:

• Install-time scripts such as preinstall, install, and postinstall
• Fresh releases that have not had much ecosystem scrutiny yet
• Package age and release history
• Weekly download volume
• Maintainer count
• Direct dependency count

It then produces a risk score and, when the latest release looks risky, recommends a safer historical version to pin instead of leaving you with a vague warning.

Install

npm install -g safe-npm-install

Or run it directly:

npx safe-npm-install express

Quick Usage

safe-npm-install express
safe-npm-install lodash axios chalk
safe-npm-install --strict some-unknown-pkg
safe-npm-install --json express

Example Output

🔍 Checking axios...

  safe-npm-install  npm package risk check
  --------------------------------------------------------
  Package: [email protected]
  ⚠ Risk: Moderate (58/100) [MODERATE]

  ✔ Popular package (18,000,000 weekly downloads)
  ✔ Package has been on npm for over a year
  ✔ 2 maintainers listed

  ⚠ Install-time scripts detected: postinstall
  ⚠ Latest release was published 2 day(s) ago

  Recommendation
  → Prefer [email protected]
    Stable candidate published 96 day(s) ago without install-time scripts.
    - latest release runs install-time scripts (postinstall)
    - latest release is only 2 day(s) old

  Score breakdown
    Package Age       ███████████████  100
    Downloads         ███████████████   90
    Install Scripts   ██░░░░░░░░░░░░░   10
    Dependencies      ████████████░░░   85
    Maintainer Trust  ███████████████  100
    Release Freshness ████████░░░░░░░   55
  --------------------------------------------------------

Why The Recommendation Feature Matters

Most tools stop at "this package looks risky."

safe-npm-install goes one step further:

• It flags risky latest releases.
• It looks through version history.
• It recommends a safer, more mature version when one exists.

That makes it an installation assistant, not just a checker.

CLI Options

| Flag | Short | Description | | --- | --- | --- | | --strict | -s | Exit with code 1 if any package is high risk | | --json | -j | Output JSON for CI/CD or pipelines | | --help | -h | Show help | | --version | -v | Show version |

Risk Model

Each package receives a score from 0 to 100, where higher means safer.

| Signal | Weight | Why it matters | | --- | --- | --- | | Package Age | 15% | Very new packages have less trust history | | Weekly Downloads | 20% | Real usage is a useful trust signal | | Install Scripts | 25% | Install hooks can execute arbitrary code | | Dependency Count | 10% | Large trees increase attack surface | | Maintainer Trust | 15% | More maintainers and release history improve trust | | Release Freshness | 15% | Extremely fresh releases are riskier; abandoned releases are also suspicious |

Risk Levels

| Score | Level | Meaning | | --- | --- | --- | | 70-100 | Safe | Strong trust signals, low immediate concern | | 40-69 | Moderate | Review before installing | | 0-39 | High | Block in strict mode |

Programmatic API

import { fetchPackageData, fetchDownloads, analyze, score } from 'safe-npm-install';

const [pkg, downloads] = await Promise.all([
  fetchPackageData('axios'),
  fetchDownloads('axios'),
]);

const signals = analyze(pkg, downloads);
const report = score(signals);

console.log(report.score);
console.log(report.riskLevel);
console.log(report.warnings);
console.log(report.recommendation);

Exports

| Function | Description | | --- | --- | | fetchPackageData(name) | Fetch package metadata from the npm registry | | fetchDownloads(name) | Fetch last-week download counts | | analyze(pkg, downloads) | Extract risk and trust signals from registry data | | score(signals) | Compute a final report and risk level | | reportText(report) | Format a terminal-friendly report | | reportJson(reports) | Format JSON output |

JSON Output

JSON output includes more than the score. It also contains:

• warnings for risky signals
• positives for trust signals
• recommendation when a safer stable version is available
• breakdown for weighted score factors

That makes it usable in CI, internal developer tooling, and install policy automation.

CI/CD

- name: Check package safety
  run: npx safe-npm-install --strict --json $(cat packages-to-install.txt)

Example shell gate:

RESULT=$(npx safe-npm-install --json some-pkg)
RISK=$(echo "$RESULT" | jq -r '.[0].riskLevel')

if [ "$RISK" = "high" ]; then
  echo "Blocked: high-risk package"
  exit 1
fi

Architecture

CLI Input
   |
   v
Fetcher -> Analyzer -> Scorer -> Reporter
   |
   v
 Cache

| Module | Role | | --- | --- | | fetcher | Retrieves npm registry metadata and download counts | | analyzer | Extracts release signals and safer-version recommendations | | scorer | Weighs trust and risk signals into a final score | | reporter | Produces terminal and JSON output | | cache | Stores a short-lived cache under ~/.safe-npm-install/cache/ | | cli | Parses arguments and orchestrates analysis |

Development

git clone https://github.com/vahabcore/safe-npm-install.git
cd safe-npm-install
npm install
npm run build
npm test
npm run lint

Roadmap

• [x] Pre-install risk scoring
• [x] Strict mode for CI
• [x] JSON output
• [x] Safer-version recommendation
• [x] File-based caching
• [ ] Analyze every dependency in a local package.json
• [ ] Add GitHub repository trust signals
• [ ] Add organization allowlists and policy files
• [ ] Export SARIF or machine-readable policy violations

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT