npm-security-guardian

npm-security-guardian is a TypeScript CLI and VSCode extension for finding npm dependency security, license, maintainer, install-script, and secret-exposure risks before they reach production.

It is built for maintainers who want fast, reviewable answers: what changed, what looks risky, what should fail CI, and what needs human review.

What Is npm-security-guardian?

npm-security-guardian scans Node.js projects and turns dependency risk signals into practical reports. It reads package manifests and lockfiles, calls npm registry metadata, summarizes npm audit, checks license and maintainer signals, detects risky install scripts, scans for likely leaked secrets, and exports results for terminals, browsers, CI, and code scanning platforms.

It does not replace a complete application security program. It gives developers a focused first line of defense for everyday dependency review.

Why Developers Need It

Modern npm risk is bigger than known CVEs. A package may deserve review because it has suspicious metadata, no repository, no license, very low downloads, stale publishing activity, install lifecycle scripts, risky maintainer signals, or a dependency tree that is hard to reason about.

Use npm-security-guardian to:

• review new packages before adoption
• catch risky dependency changes in pull requests
• create repeatable CI gates for dependency risk
• generate reports maintainers can share and archive
• inspect package health before running npm install
• scan for likely secrets before code is pushed

Feature Overview

Area	What it does
Dependency scan	Scores direct dependencies with npm metadata, lockfile versions, install scripts, license signals, downloads, age, and repository data.
npm audit summary	Runs npm audit --json when available and summarizes low, moderate, high, and critical vulnerabilities.
Health score	Produces a project score and grade based on risk, audit findings, missing lockfiles, outdated packages, and optional secret findings.
Secret scanning	Detects likely tokens, keys, database URLs, JWTs, and private keys while masking secret previews.
License policy	Flags allowed, warning, denied, and missing license states with optional CI failure policy.
Maintainer trust	Reviews maintainer and publish activity signals for project dependencies or a single package.
Install scripts	Finds install lifecycle scripts and highlights suspicious command patterns.
Reports	Writes JSON, Markdown, HTML dashboards, dependency graphs, PR comments, badges, and SARIF.
VSCode extension	Adds a Security Guardian sidebar, package actions, status bar score, hovers, decorations, and dashboard.

Installation

Run it without installing:

npx npm-security-guardian scan

Install it in a project:

npm install --save-dev npm-security-guardian
npx npm-security-guardian scan

Install it globally:

npm install --global npm-security-guardian
npm-security-guardian scan

Requirements:

• Node.js >=20
• npm, pnpm, or Yarn

Quick Start

Scan the current project:

npx npm-security-guardian scan

Use exact installed versions from a lockfile:

npx npm-security-guardian scan --lockfile

Generate reports:

npx npm-security-guardian scan --lockfile --output report.json --md report.md --html report.html

Fail CI when high-risk packages are found:

npx npm-security-guardian scan --fail-on high

Create a starter config:

npx npm-security-guardian init-config

Next steps:

• Getting started
• Command reference
• Configuration

CLI Commands

Command	Purpose
scan	Scan dependencies, audit results, risk signals, and optional secrets.
inspect <package>	Inspect one npm package before adoption.
safe-install <package>	Inspect a package before running npm install.
alternatives <package>	Search for lower-risk package alternatives.
secrets	Scan project files for likely leaked credentials.
actions	Scan GitHub Actions workflows for risky workflow patterns.
licenses	Check dependency licenses and apply license policy.
outdated	Show dependencies behind the latest npm version.
maintainers	Analyze maintainer and publish activity signals.
scripts	Analyze npm install lifecycle script risk.
graph	Build dependency graph data or an interactive HTML graph.
badge	Generate Shields.io badge Markdown or URLs.
cache stats	Show local npm metadata cache status.
cache clear	Clear local npm metadata cache.
benchmark	Measure scan performance and cache behavior.
init-config	Create npm-security-guardian.config.json.
init-ci	Create a GitHub Actions workflow.
release	Prepare a local release without publishing.

See docs/commands.md for usage, options, examples, and output summaries for every command.

VSCode Extension

npm-security-guardian also ships as a VSCode extension. It adds a Security Guardian activity bar view, package risk tree, status bar health score, package hovers, package.json decorations, quick package actions, and an HTML dashboard webview.

Common extension commands:

• npm-security-guardian.scan
• npm-security-guardian.scanDetailed
• npm-security-guardian.scanSecrets
• npm-security-guardian.openDashboard
• npm-security-guardian.inspectDependency
• npm-security-guardian.openNpmPage
• npm-security-guardian.viewLicense
• npm-security-guardian.openSettings

Local development:

npm install
npm run build

Open the repository in VSCode, press F5, and choose an Extension Development Host. See docs/vscode-extension.md.

Reports

npm-security-guardian can create reports for local review, pull requests, dashboards, and audit trails.

Report	Command
JSON	npx npm-security-guardian scan --output report.json
Markdown	npx npm-security-guardian scan --md report.md
HTML dashboard	npx npm-security-guardian scan --html report.html
Dependency graph	npx npm-security-guardian graph --html dependency-graph.html
PR comment	npx npm-security-guardian scan --github-pr-comment
SARIF	npx npm-security-guardian scan --sarif results.sarif
Badges	npx npm-security-guardian badge

More detail: docs/reports.md.

Screenshots

These documentation images are placeholders until final public captures are recorded.

Area	Preview
CLI scan output
HTML dashboard
Dependency graph
Secret scanner
License checker
VSCode extension sidebar
VSCode dashboard
SARIF output

CI/CD

Use --fail-on to turn a scan into a policy gate:

npx npm-security-guardian scan --lockfile --fail-on high

Minimal GitHub Actions example:

name: npm-security-guardian

on:
  push:
  pull_request:

permissions:
  contents: read

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx npm-security-guardian scan --lockfile --fail-on high

Use npx npm-security-guardian init-ci to create a starter workflow. See docs/ci-cd.md.

Monorepo Support

Workspace scanning is opt-in. Use --workspaces to scan every detected workspace or --workspace <name> to scan one package.

npx npm-security-guardian scan --workspaces
npx npm-security-guardian scan --workspace packages/api
npx npm-security-guardian graph --workspaces --html dependency-graph.html

Supported workspace sources:

• package.json workspaces
• Yarn-style workspaces.packages
• pnpm-workspace.yaml

See docs/monorepo-support.md.

pnpm Support

npm-security-guardian reads pnpm-lock.yaml v8+ lockfiles and applies the same dependency, license, script, maintainer, graph, and report workflows used for npm projects.

npx npm-security-guardian scan --lockfile

See docs/pnpm-yarn-support.md.

Yarn Support

npm-security-guardian reads Yarn Classic and modern Yarn lockfiles where lockfile metadata is available. When multiple lockfiles exist, the scanner follows package.json packageManager first, then falls back to lockfile priority.

npx npm-security-guardian scan --lockfile

See docs/pnpm-yarn-support.md.

SARIF Export

Export SARIF v2.1.0 for code scanning platforms:

npx npm-security-guardian scan --lockfile --sarif results.sarif
npx npm-security-guardian secrets --sarif secrets.sarif
npx npm-security-guardian actions --sarif actions.sarif

See docs/sarif.md.

Config Examples

Create npm-security-guardian.config.json:

npx npm-security-guardian init-config

Example:

{
  "failOn": "high",
  "ignorePackages": ["@types/node"],
  "cacheTTLHours": 24,
  "riskRules": {
    "lowDownloadsThreshold": 100,
    "oldPackageYears": 2,
    "newPackageDays": 30,
    "tooManyDependencies": 20
  },
  "secrets": {
    "ignorePaths": ["docs/**", "examples/**"],
    "allowlist": ["example-token"],
    "ignorePatterns": ["TEST_API_KEY=.*"]
  },
  "licenses": {
    "allowed": ["MIT", "Apache-2.0", "BSD-3-Clause", "ISC"],
    "denied": ["AGPL-3.0", "GPL-3.0"],
    "warn": ["LGPL-3.0", "UNKNOWN", "UNLICENSED"],
    "allowMissing": false
  }
}

CLI flags override config values where both are available. See docs/configuration.md.

Badges

Generate Shields.io badges from a project scan:

npx npm-security-guardian badge
npx npm-security-guardian badge --type health
npx npm-security-guardian badge --type vulnerabilities --format url

Supported badge types are health, vulnerabilities, risk, and license. See docs/reports.md.

Privacy And Security Notes

• Dependency metadata comes from your local project files and npm registry responses.
• npm audit --json is run locally through npm when audit data is needed.
• Report files are written to paths you choose; the tool does not upload generated reports.
• Secret findings are masked in output. Full secret values are not printed in policy warnings.
• Secret scanning is heuristic. Treat findings as review prompts, not proof of compromise.
• Registry and audit calls may reveal package names to npm infrastructure, the same way normal npm tooling does.

More detail: docs/troubleshooting.md.

FAQ

Does this replace Dependabot, npm audit, or SCA tooling?
No. It complements those tools by combining audit data with package metadata, license, maintainer, install-script, and secret signals.

Does the scanner modify my dependencies?
No. Scan commands read project files and write reports only when you pass report output flags. safe-install is the command that can install a package, and it asks for confirmation unless forced.

Can I run it offline?
Yes, use --offline with cached npm metadata. Fresh package metadata and audit results require registry access.

Why are screenshots placeholders?
They are stable documentation targets until final release captures are recorded. Replace files in docs/screenshots/ before a public launch.

Where are release notes?
See CHANGELOG.md.

Release Notes

Release history is tracked in CHANGELOG.md. Review it before upgrading in CI or packaging a VSCode extension release.

Roadmap

• Publish final screenshots and Marketplace assets.
• Expand package provenance and integrity signals.
• Improve transitive dependency risk explanations.
• Add more report examples for common CI providers.
• Continue expanding fixture coverage for report formats and lockfile variants.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md.

Useful local commands:

npm install
npm run build
npm run test:run
npm run quality:full

Please keep changes focused, include tests for behavior changes, and update docs when user-facing behavior changes.

Documentation

• Getting started
• Commands
• Configuration
• Reports
• VSCode extension
• CI/CD
• Monorepo support
• pnpm and Yarn support
• SARIF
• Troubleshooting

Examples

• npm project
• pnpm project
• Yarn project
• Monorepo project
• GitHub Actions
• SARIF upload

Security

If you believe you found a vulnerability, please read SECURITY.md and report it privately before opening a public issue.

License

MIT. See LICENSE.