Metadata-Version: 2.4
Name: vamp-cve-oracle
Version: 3.2
Summary: CVE vulnerability intelligence aggregator for authorized security assessments
Author-email: VampSecure Studios <contact@vampsecurestudios.com>
License: MIT
Project-URL: Homepage, https://github.com/Vampsecure-Labs/vamp-cve-oracle
Project-URL: Repository, https://github.com/Vampsecure-Labs/vamp-cve-oracle
Keywords: security,pentest,audit,cybersecurity,vampsecure,cve,vulnerability,nvd,threat-intelligence
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: rich>=13.7.0
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/badge/version-3.1-crimson?style=flat-square" />
  <img src="https://img.shields.io/badge/python-3.11+-blue?style=flat-square&logo=python&logoColor=white" />
  <img src="https://img.shields.io/badge/async-aiohttp-teal?style=flat-square" />
  <img src="https://img.shields.io/badge/VampSecure_Labs-Security_Research-8b0000?style=flat-square" />
</p>

<h1 align="center">vamp-cve-oracle</h1>
<p align="center"><em>CVE Intelligence &amp; Risk-Based Vulnerability Management Engine — VampSecure Labs</em></p>

---

## Overview

**vamp-cve-oracle** is an asynchronous CVE intelligence platform that enriches vulnerability data from four authoritative sources and applies a Risk-Based Vulnerability Management (RBVM) scoring model to prioritize remediation effort.

It correlates threat intelligence from the **NVD**, **AlienVault OTX**, **FIRST.org EPSS**, and the **CISA KEV catalog**, then computes a composite priority score using the formula:

```
Priority = EPSS_probability × CVSS_base_score
```

EPSS (Exploit Prediction Scoring System) quantifies the probability of exploitation in the wild within 30 days, making this metric a reliable signal for distinguishing theoretically severe CVEs from those actively being exploited. An optional asset inventory CSV allows per-host correlation, weighting findings by asset criticality.

---

## Features

- Four-source intelligence aggregation: NVD, AlienVault OTX, FIRST.org EPSS, CISA KEV
- RBVM priority scoring: `EPSS × CVSS` with configurable asset criticality weighting
- CISA KEV integration — immediately flags vulnerabilities under active exploitation
- Asset inventory correlation via CSV (`host,software,version,criticality`)
- Batch CVE processing from file — handles large sets of identifiers efficiently
- Four output formats: Rich console, JSON, dark-theme HTML, and Markdown (GFM)
- Configurable API keys for higher rate limits on both NVD and OTX

---

## Requirements

```
Python 3.11+
aiohttp >= 3.9.0
rich >= 13.7.0
```

Install dependencies:

```bash
pip install -r requirements.txt
```

---

## Installation

```bash
git clone https://github.com/belky-me/vamp-cve-oracle.git
cd vamp-cve-oracle
pip install -r requirements.txt
```

---

## Configuration

API keys are optional but strongly recommended to avoid rate limiting on large batches:

| Variable | Source | Default rate limit |
|----------|--------|--------------------|
| `NVD_API_KEY` | https://nvd.nist.gov/developers/request-an-api-key | 5 req / 30 s → 50 req / 30 s |
| `OTX_API_KEY` | https://otx.alienvault.com | Anonymous access |

```bash
export NVD_API_KEY=your_nvd_key
export OTX_API_KEY=your_otx_key
```

---

## Usage

```
python vamp_cve_oracle.py [CVE-ID ...] [OPTIONS]

Positional:
  CVE-ID [CVE-ID ...]            One or more CVE identifiers (e.g. CVE-2024-21762)

Input:
  -f, --file FILE                File with one CVE ID per line

Asset correlation:
  --inventory FILE               CSV file: host,software,version,criticality

Output:
  -o, --output FILE              Write findings to JSON
      --html FILE                Generate standalone HTML report (dark theme)
      --markdown FILE            Generate Markdown report (GFM-compatible)
```

---

## Examples

Query a single CVE with full intelligence context:

```bash
python vamp_cve_oracle.py CVE-2024-21762
```

Process a list of CVEs from a penetration test and write a JSON report:

```bash
python vamp_cve_oracle.py -f pentest_cves.txt -o results.json
```

Correlate findings against an asset inventory and generate an HTML report:

```bash
python vamp_cve_oracle.py -f cves.txt --inventory assets.csv --html rbvm_report.html
```

Query multiple CVEs and export Markdown for wiki or ticket integration:

```bash
python vamp_cve_oracle.py CVE-2023-27997 CVE-2022-40684 CVE-2024-21762 --markdown findings.md
```

---

## Output Formats

| Format | How to enable | Description |
|--------|---------------|-------------|
| Console | Default | Rich panel per CVE with CVSS, EPSS score, KEV status, and OTX pulse count |
| JSON | `-o FILE` | Full structured output including all source data and priority scores |
| HTML | `--html FILE` | Dark-theme standalone report, browser-ready |
| Markdown | `--markdown FILE` | GFM-compatible export for GitHub, Confluence, or Jira tickets |

---

## Exit Codes

| Code | Meaning | CI/CD usage |
|------|---------|-------------|
| `0` | All CVEs processed cleanly, no critical KEV hits | Pass gate |
| `1` | Findings present — review RBVM scores | Review recommended |
| `2` | Critical or KEV-confirmed exploited vulnerabilities found | Fail gate — remediate immediately |

---

## Part of VampSecure Labs Toolkit

`vamp-cve-oracle` is part of the **VampSecure Labs Security Research Toolkit** — a collection of professional-grade, self-hosted security assessment tools.

| Tool | Purpose |
|------|---------|
| [vamp-forticheck](https://github.com/belky-me/vamp-forticheck) | Multi-vendor edge device CVE scanner |
| [vamp-cve-oracle](https://github.com/belky-me/vamp-cve-oracle) | CVE intelligence and RBVM engine |
| [vamp-passive-recon](https://github.com/belky-me/vamp-passive-recon) | Passive recon and attack surface mapping |
| [vamp-subdomain-takeover](https://github.com/belky-me/vamp-subdomain-takeover) | Subdomain takeover vulnerability scanner |
| [vamp-cloud-enum](https://github.com/belky-me/vamp-cloud-enum) | Cloud storage bucket enumerator |
| [vamp-orchestrator](https://github.com/belky-me/vamp-orchestrator) | Multi-tool assessment orchestrator |

---

<p align="center">
  © VampSecure Studios — VampSecure Labs Security Research Division<br/>
  For authorized security assessments only. Unauthorized use is prohibited.
</p>
