# npm-risk

A zero-dependency CLI that checks npm packages for basic supply-chain risk signals before you install them.

```bash
npx npm-risk <package-name>
```

## Why?

Installing an npm package means trusting code that can run on your machine.

npm-risk gives you a quick risk snapshot before you add a dependency to your project.

It checks for things like:

- Recently published versions
- Install lifecycle scripts
- Runtime dependency count
- Maintainer count
- Known npm vulnerabilities
- GitHub repository health
- Open GitHub issues
- GitHub stars
- Last repository activity
- Archived repositories

## Example

```bash
npx npm-risk axios
```

Example output:

```bash
axios@1.13.2
Risk: MEDIUM score: 4
Checks:
✓ latest version: 1.13.2
✓ latest version published 42 day(s) ago
✓ no install lifecycle scripts
✓ 3 runtime dependencies
✓ 7 maintainers
✓ no known npm vulnerabilities found
✓ GitHub repository: axios/axios
⚠ 520 open GitHub issues
✓ 106000 GitHub stars
✓ last GitHub push was 2 day(s) ago`
```

## Install

You do not need to install it just run:

```bash
npx npm-risk <package-name>
```

## Usage

```bash
npx npm-risk <package-name>
```

## Risk levels

npm-risk assigns a simple risk score based on warning signals.

Score Risk

0–3 LOW

4–7 MEDIUM

8+ HIGH

The score is not a guarantee that a package is safe or unsafe. It is a quick signal to help you decide whether to investigate further.

## Checks

### Publish date

Very new releases can be risky because malicious versions are often discovered shortly after publication.

### Install lifecycle scripts

Packages with preinstall, install, or postinstall scripts can execute code during installation.

### Runtime dependencies

A large dependency tree increases the amount of third-party code you trust.

### Maintainers

Packages with only one maintainer may have higher continuity and account-compromise risk.

### Known vulnerabilities

Checks npm’s public security advisory endpoint for known vulnerabilities affecting the latest version.

### GitHub health

When a GitHub repository is detected, npm-risk checks:

- Open issue count
- Star count
- Whether the repository is archived
- Last push date

## Zero dependencies

npm-risk intentionally has no runtime dependencies.

That matters because a dependency-risk checker should not introduce unnecessary dependency risk itself.

## Requirements

Node.js 18 or newer.

This package uses the built-in fetch API.

## Limitations

npm-risk is intentionally lightweight.

It does not currently:

- Verify package provenance
- Detect all malicious packages
- Analyze package source code
- Check every transitive dependency
- Replace npm audit
- Replace manual security review

Use it as a quick first-pass signal, not as a complete security tool.

## Roadmap

Possible future checks:

- Typosquat detection
- Maintainer change detection
- Package age and download trend changes
- Repository/package name mismatch
- Suspicious bin entries
- Transitive dependency risk summary
- GitHub Action for pull requests
- JSON output for CI

## Contributing

Ideas, issues, and pull requests are welcome.

Useful contributions include:

- Better heuristics
- Safer defaults
- More package health checks
- False-positive reductions
- Tests across popular npm packages