Metadata-Version: 2.4
Name: dep-shield
Version: 2.0.0
Summary: A cross-ecosystem dependency vulnerability scanner and guard.
Author-email: Het Joshi <hetjoshi.mukt@pm.me>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: typer[all]
Requires-Dist: rich
Requires-Dist: requests
Requires-Dist: pydantic
Requires-Dist: packaging
Dynamic: license-file

# 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)](https://osv.dev) distributed database.

## Installation

Requires Python 3.10+.

```bash
pip install dep-shield

```

## Usage

### 1. Passive Scanning

Scan your current project manifests for known vulnerabilities.

```bash
# 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:**

```bash
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`):

```bash
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:

```bash
$ 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**

```yaml
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:**

```json
[
  {
    "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
