dep-shield 2.0.0

A cross-ecosystem dependency vulnerability scanner and guard.

Dep-Shield

Dep-Shield is a lightweight, cross-ecosystem dependency vulnerability scanner. It supports NPM (JavaScript/Node) and PyPI (Python).

Unlike passive scanners, Dep-Shield can act as an active guard, intercepting package installation commands (npm install, pip install) to detect and block vulnerabilities before they are written to your disk.

Features

• Multi-Ecosystem: Parses package.json, package-lock.json, and requirements.txt.
• Real-time Guard: Intercepts install commands to prevent vulnerable packages from entering your project.
• Smart Recommendations: Suggests safe upgrade versions when vulnerabilities are detected.
• CI/CD Ready: Outputs machine-readable JSON for pipeline integration.
• Powered by OSV: Uses the Open Source Vulnerabilities (OSV) distributed database.

Installation

Requires Python 3.10+.

pip install dep-shield

Usage

1. Passive Scanning

Scan your current project manifests for known vulnerabilities.

# Scan a Node.js project
dep-shield scan package.json

# Scan a Python project
dep-shield scan requirements.txt

Options:

• --json: Output results in JSON format (useful for CI/CD).
• --fail-on-high: Exit with an error code if High/Critical vulnerabilities are found.

2. Active Guard Mode

Dep-Shield can wrap your package manager to screen dependencies before installation.

Manual Usage:

dep-shield guard npm install lodash@4.17.15
dep-shield guard pip install django==2.2

If a vulnerability is found, Dep-Shield will block the installation, display a security report, and offer to install a safe version (if available).

Automatic Setup (Aliases): To make this seamless, add the following aliases to your shell configuration (.bashrc, .zshrc, or .profile):

alias npm="dep-shield guard npm"
alias pip="dep-shield guard pip"
alias pnpm="dep-shield guard pnpm"

Once configured, your standard commands are automatically protected:

$ npm install react
> Dep-Shield Guard is analyzing...
> No vulnerabilities found. Proceeding with installation.

CI/CD Integration

Use the --json flag to integrate Dep-Shield into GitHub Actions, GitLab CI, or Jenkins.

Example: GitHub Actions

steps:
  - uses: actions/checkout@v3
  - name: Install Dep-Shield
    run: pip install dep-shield
  - name: Security Scan
    run: dep-shield scan package.json --fail-on-high

JSON Output Schema:

[
  {
    "dependency": {
      "name": "lodash",
      "version": "4.17.15",
      "ecosystem": "npm"
    },
    "vulnerabilities": [
      {
        "id": "GHSA-p6mc-m468-83gw",
        "severity": "HIGH",
        "fixed_in": "4.17.21",
        "summary": "Prototype Pollution in lodash"
      }
    ]
  }
]

Supported Files

Ecosystem	Manifest File
Node.js	package.json
Python	requirements.txt

License

MIT License