Metadata-Version: 2.4
Name: vamp-supply-chain
Version: 1.0
Summary: Supply chain security scanner: SBOM, CVE checks, typosquatting detection and checksum verification
Author-email: VampSecure Studios <contact@vampsecurestudios.com>
License: AGPL-3.0-only
Project-URL: Homepage, https://github.com/Vampsecure-Labs/vamp-supply-chain
Project-URL: Repository, https://github.com/Vampsecure-Labs/vamp-supply-chain
Keywords: security,pentest,supply-chain,sbom,typosquatting,vampsecure,devsecops,osv,cve
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: rich>=13.7.0
Requires-Dist: aiohttp>=3.8.0

<!-- © VampSecure Studios — VampSecure Labs Security Research Division -->
<h1 align="center">vamp-supply-chain</h1>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.9%2B-blue?logo=python&logoColor=white" alt="Python 3.9+"/>
  <img src="https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey" alt="Platform"/>
  <img src="https://img.shields.io/badge/license-AGPL--3.0-green" alt="License AGPL-3.0"/>
  <img src="https://img.shields.io/badge/VampSecure-Labs-magenta" alt="VampSecure Labs"/>
</p>

## Overview

`vamp-supply-chain` is a supply chain security scanner that audits project dependencies for CVE vulnerabilities, typosquatting attacks, and checksum integrity. It automatically detects dependency manifests (`requirements.txt`, `pyproject.toml`, `setup.cfg`, `package.json`) and queries OSV.dev for known vulnerabilities, performs Levenshtein-distance typosquatting detection against a curated list of 30 popular packages, and verifies package checksums against PyPI metadata. It can also generate Software Bill of Materials (SBOM) in CycloneDX JSON format. Findings are rated CRITICAL to INFO and exported to Console (Rich), JSON, or HTML.

## Features

- Automatic dependency manifest discovery: `requirements.txt`, `requirements-*.txt`, `pyproject.toml` (`[project].dependencies`), `setup.cfg` (`[options].install_requires`), `package.json` (`dependencies` + `devDependencies`)
- CVE check via OSV.dev API: POST to `https://api.osv.dev/v1/query` per package with severity rated CRITICAL/HIGH from CVSS score
- Typosquatting detection: pure-Python Levenshtein distance (no external library) against 30 curated popular packages; distance ≤ 2 triggers HIGH severity finding
- Checksum verification: queries `https://pypi.org/pypi/{pkg}/{version}/json` and compares `.tar.gz` SHA-256; unresolved packages flagged as MEDIUM
- SBOM generation (subcommand `sbom`): CycloneDX JSON with `bomFormat`, `specVersion`, `serialNumber`, per-component `purl` (pkg:pypi/name@version) and `licenses`
- Rich console output: per-issue-type panels and a severity summary table
- Export to JSON and HTML (standalone, dark-theme)
- Exit codes for CI/CD pipeline integration

## Requirements

- Python 3.9 or later
- `rich >= 13.7.0`
- `aiohttp >= 3.8.0`

## Installation

```bash
pip install vamp-supply-chain
# o con Homebrew:
brew install vampsecure-labs/labs/vamp-supply-chain
```

```bash
git clone https://github.com/Vampsecure-Labs/vamp-supply-chain.git
cd vamp-supply-chain
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## Usage

```
vamp-supply-chain --help
```

```
usage: vamp-supply-chain [-h] {scan,sbom} ...

vamp-supply-chain — Supply Chain Security Scanner (VampSecure Labs)

subcommands:
  scan    Scan dependency manifests for CVEs, typosquatting and checksum issues
  sbom    Generate a CycloneDX SBOM from discovered dependencies
```

## Examples

```bash
# Scan all dependency manifests in the current directory
vamp-supply-chain scan --path .

# Scan a specific project and export findings to JSON and HTML
vamp-supply-chain scan --path /path/to/project --json results.json --html report.html

# Scan and also emit a CycloneDX SBOM
vamp-supply-chain scan --path . --sbom sbom.json

# Generate SBOM only (no vulnerability check)
vamp-supply-chain sbom --path . --output sbom.json

# Generate SBOM in SPDX format
vamp-supply-chain sbom --path . --output sbom.json --format spdx
```

## CLI Reference

### `scan`

| Flag | Default | Description |
|------|---------|-------------|
| `--path DIR` | `.` | Directory to scan for dependency manifests |
| `--json FILE` | — | Export findings to JSON |
| `--html FILE` | — | Export dark-theme HTML report |
| `--sbom FILE` | — | Also emit a CycloneDX SBOM alongside the scan |

### `sbom`

| Flag | Default | Description |
|------|---------|-------------|
| `--path DIR` | `.` | Directory to scan for dependency manifests |
| `--output FILE` | `sbom.json` | Output SBOM file path |
| `--format FORMAT` | `cyclonedx` | SBOM format: `cyclonedx` or `spdx` |

## Output Formats

| Format | Flag | Description |
|--------|------|-------------|
| Console | (default) | Rich panels grouped by issue type with severity color-coding |
| JSON | `--json FILE` | Machine-readable full finding set |
| HTML | `--html FILE` | Dark-theme standalone report |
| SBOM | `--sbom FILE` / `sbom --output` | CycloneDX JSON Software Bill of Materials |

## Exit Codes

| Code | Meaning | CI/CD Behavior |
|------|---------|----------------|
| `0` | No CRITICAL or HIGH findings | Pipeline passes |
| `1` | CRITICAL or HIGH findings detected | Pipeline fails — review required |
| `2` | Execution error | Pipeline fails — check configuration |

## Legal Notice

Use exclusively on systems you own or for which you hold explicit written authorization from the system owner. VampSecure Studios assumes no liability for unauthorized use.

## Part of VampSecure Labs Toolkit

`vamp-supply-chain` is one tool in the VampSecure Labs security research toolkit. For the full toolkit including the orchestrator that runs all tools in sequence and aggregates findings into a single engagement report, see:

- Portfolio: [github.com/Vampsecure-Labs](https://github.com/Vampsecure-Labs)
- Orchestrator: [github.com/Vampsecure-Labs/vamp-orchestrator](https://github.com/Vampsecure-Labs/vamp-orchestrator)

---

© VampSecure Studios — VampSecure Labs Security Research Division

## Versión
v1.0 — VampSecure Labs Security Research Division
