ts-lock-scanner — TypeScript package

ts-lock-scanner is a library and CLI tool for validating yarn.lock and package-lock.json files against known vulnerable or malicious dependencies. The list of bad version ranges is fetched from a remote URL, making updates easy.

Russian version / Русская версия

Features

• 🚨 Validate yarn.lock (Yarn v1 and Berry v2/3).
• 🚨 Validate package-lock.json (npm v6+).
• 🌐 Fetch list of vulnerable version ranges from the network (configurable URL or environment variable BAD_MODULES_URL).
• ✅ Deduplication: each package version is reported only once, even if it appears in multiple places.
• 🧩 Separate functions for npm and yarn — usable as a library.
• 📦 CLI interface for quick scanning.
• 🔧 Supports semver ranges (>=, <, ^, etc.).

Installation

npm install ts-lock-scanner --save-dev
# or
pnpm add -D ts-lock-scanner
# or
yarn add -D ts-lock-scanner

Build (if working from source):

npm run build

Usage (CLI)

# Set the URL of the bad-ranges JSON
export BAD_MODULES_URL="https://your.cdn/bad-packages.json"

# Check yarn.lock
npx ts-lock-scanner ./yarn.lock

# Check package-lock.json
npx ts-lock-scanner ./package-lock.json

# Provide URL explicitly
npx ts-lock-scanner ./yarn.lock --url https://your.cdn/bad-packages.json

Example bad-packages.json:

{
  "chalk": ">=5.6.1 <5.6.3",
  "ansi-regex": ">=6.2.1",
  "debug": ">=4.4.2 <4.4.3"
}

Usage (as a library)

import { fetchBadRanges, scanYarnLock, scanPackageLock } from "ts-lock-scanner";
import { readFileSync } from "fs";

// Load bad ranges
const bad = await fetchBadRanges({ url: "https://your.cdn/bad-packages.json" });

// Validate yarn.lock
const yarnText = readFileSync("./yarn.lock", "utf8");
const yarnResult = scanYarnLock(yarnText, bad);
console.log(yarnResult.hits);

// Validate package-lock.json
const npmText = readFileSync("./package-lock.json", "utf8");
const npmResult = scanPackageLock(npmText, bad);
console.log(npmResult.hits);

Types

• fetchBadRanges({ url? }) → Promise<BadRangeMap> — loads a map { packageName: semverRange }.
• scanYarnLock(text, badMap) → ScanResult.
• scanPackageLock(text, badMap) → ScanResult.
• ScanResult contains hits: Hit[].
• Hit = { name, version, ranges[], from? }.

Recommendations when vulnerabilities are found

• Pin safe versions (<= minimum vulnerable − 1).

• Clear cache:

  yarn cache clean
  npm cache clean --force

• Fully reinstall dependencies.

Requirements

• Node.js >=18 (uses built-in fetch).
• Compatible with TypeScript 5.x.

License

MIT