npm Malware Scanner

A simple and lightweight Python CLI tool that checks installed npm packages against GitHub’s npm malware advisories from their Advisory Database.

This repo ships a malware.db for convenience, so that you can run scan without a token. You can refresh the list with update-db or scan … --update-db when you want the latest (after adding a token).

Originally based on crawler by dsawardekar.

Requirements

• Python 3.10 or newer

For updating the malware DB:

• A network connection
• A GitHub personal access token

Quick start

1. Install Python 3.10+ (If needed)

On macOS you can quickly install with Homebrew. For pyenv, uv, pip, and other setups, see Advanced setup below.

brew install python

Confirm with python3 --version.

2. Clone Repo

Clone and cd into the project root:

cd ~/
git clone https://github.com/csloisel/npm-malware-scanner.git
cd npm-malware-scanner

3. Run Scan

Point scan at the directory you want to scan.

Recommended: use your home directory as the scan path so that everything under your account is checked in one run.

python3 -m malscan scan ~/

This uses the checked-in malware.db and does not need a GitHub token.

Usage

Subcommands are the same no matter how you launch the CLI; only the prefix changes based on your chosen python setup.

malware.db and results.json are resolved relative to the current working directory. Run commands from the repository root so the bundled malware.db is picked up and results.json lands next to it.

Command	Purpose
scan <directory> [--update-db]	Walk <directory> for package.json projects, match node_modules against malware.db. --update-db refreshes the DB first (needs token).
update-db	Fetch npm malware advisories from GitHub into malware.db.
clear-token	Remove the saved token file and optionally enter a new token.

Advanced setup

Pick one of the following workflow tracks; you do not need both.

pyenv + venv + pip

Use this track if you manage Python with pyenv, Homebrew, or another install and want a classic virtualenv plus pip.

pyenv (optional): The repo includes .python-version (3.14). After you install pyenv and clone this repository, run this once (it does nothing if 3.14 is already installed):

Skip this if you already use Python 3.10+ from somewhere else.

pyenv install -s 3.14

When your shell is inside the project directory, pyenv uses that version automatically; you do not need pyenv local.

venv + editable install: From the repository root:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

That installs the malscan console script from [project.scripts] in pyproject.toml. You can then run the scanner using:

malscan scan /path/to/scan/

uv

Use uv when you want an all-in-one version manager, package manager, and venv. Install uv, then from the repository root run this once:

uv sync

That creates .venv and installs the package from uv.lock and pyproject.toml. You can now run the scan with uv run:

uv run malscan scan /path/to/scan/

You can also optionally activate the venv with:

source .venv/bin/activate

Which puts the malscan entry point on your PATH, allowing you to run the scanner using:

malscan scan /path/to/scan/

GitHub Access Token

The tool resolves a token in this order:

1. GITHUB_TOKEN or GH_TOKEN environment variable
2. A token stored in the config file
3. Interactive prompt

Saved token file location:

• macOS / Linux: ~/.config/npm-malware-scanner/github_token, or under $XDG_CONFIG_HOME when set.
• Windows: %APPDATA%\npm-malware-scanner\github_token (or under %USERPROFILE% if APPDATA is unset).

Use clear-token to remove the stored file; environment variables are not cleared.