check-npm-lockfile

Detect recently published npm packages in lockfiles for supply chain attack prevention.

Why?

Supply chain attacks often involve publishing malicious packages or compromising existing ones. This tool helps identify packages in your lockfile that were published recently, allowing you to review them before they enter your codebase.

Installation

# Global installation
npm install -g check-npm-lockfile

# Or use with npx (no installation required)
npx -y check-npm-lockfile

Usage

# Check current directory (auto-detects lockfile)
check-npm-lockfile

# Check specific lockfile
check-npm-lockfile package-lock.json
check-npm-lockfile yarn.lock

Options

| Option | Description | Default | |--------|-------------|---------| | --minimum-release-age <duration> | Minimum age threshold (e.g., "7 days", "30 days") | "3 days" | | -e, --exclude <packages...> | Packages to exclude from checking | - | | -f, --format <type> | Output format: console or json | "console" | | -c, --concurrency <number> | Max concurrent API requests | 10 | | --no-exit-code | Always exit with code 0 | false | | -v, --verbose | Show verbose output | false |

Examples

# Detect packages published within the last 7 days
check-npm-lockfile --minimum-release-age "7 days"

# Exclude specific packages
check-npm-lockfile --exclude lodash --exclude react

# Output as JSON (useful for CI pipelines)
check-npm-lockfile --format json

# Combine options
check-npm-lockfile --minimum-release-age "30 days" --format json --verbose

Supported Lockfiles

• package-lock.json (npm v1 and v2+)
• yarn.lock (Yarn v1 and Berry/v2+)

CI Integration

Use in your CI pipeline to block builds containing recently published packages:

# GitHub Actions example
- name: Check for recently published packages
  run: npx -y check-npm-lockfile --minimum-release-age "7 days"

The command exits with code 1 if recent packages are found (unless --no-exit-code is specified).

Requirements

• Node.js >= 22.0.0

License

MIT