Metadata-Version: 2.4
Name: cveye
Version: 3.2.5
Summary: Check latest CVEs and exploit availability without API keys
Author: PwnedBytes0x1
License: MIT
Keywords: cve,nvd,exploit,security,osv,kev
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">

# C V E y e

<img src="https://img.shields.io/badge/version-3.2.5-blue?style=for-the-badge" alt="version">
<img src="https://img.shields.io/badge/pypi-cveye-blue?style=for-the-badge&logo=pypi&logoColor=white" alt="pypi">
<img src="https://img.shields.io/badge/docker-ghcr.io-informational?style=for-the-badge&logo=docker&logoColor=white" alt="docker">
<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="license">
<img src="https://img.shields.io/badge/python-3.7%2B-informational?style=for-the-badge" alt="python">
<img src="https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20Windows%20%7C%20Termux-success?style=for-the-badge" alt="platform">
<img src="https://img.shields.io/badge/API%20keys-none-critical?style=for-the-badge" alt="no api keys">

**Zero-dependency CLI for CVE details & exploit availability — without API keys**

NVD · OSV.dev · MITRE · CISA KEV · FIRST EPSS · ExploitDB · GitHub

*Clean tagged output, CVSS v4.0 scoring, concurrent batch mode*

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/pwnedbytes0x1)

[Quick Start](#-quick-start) ·
[Commands](#-commands) ·
[Configuration](#%EF%B8%8F-configuration) ·
[Contributing](CONTRIBUTING.md)

</div>

---

> [!WARNING]
> CVEye is for **defensive security research** only. You are responsible for
> your actions. Always obtain proper authorization before testing any system.

## 📖 Table of Contents

- [Why CVEye?](#-why-cveye)
- [Quick Start](#-quick-start)
- [Commands](#-commands)
- [Demo](#-demo)
- [Data Sources](#-data-sources)
- [Exploit Signal Model](#-exploit-signal-model)
- [Configuration](#%EF%B8%8F-configuration)
- [Caching](#%EF%B8%8F-caching)
- [Tool Interop](#-tool-interop)
- [Exit Codes](#-exit-codes)
- [Project Structure](#-project-structure)
- [Development](#-development)
- [FAQ](#-faq)
- [Contributing](#-contributing)
- [Acknowledgments](#-acknowledgments)
- [License](#-license)

## 🤔 Why CVEye?

Most CVE tooling forces you through API-key signup walls, pip dependency
hell, or rate-limit roulette. **CVEye does one thing well**: answer *"what is
this CVE, and can I exploit it?"* — instantly, from public sources, with
clean output that pipes beautifully.

```text
✅ Zero dependencies      Python stdlib only — runs anywhere, even Termux
✅ Zero API keys          NVD, OSV, MITRE, KEV, EPSS, ExploitDB — all public
✅ CVSS v4.0 scoring      Official FIRST MacroVector algorithm embedded
✅ Honest signals         Confirmed exploits separated from weak "leads"
✅ Fast                   Disk cache + concurrent batch mode
✅ Clean UX               Single-dash flags, stderr/stdout discipline
```

## 🚀 Quick Start

```bash
# Install from PyPI (recommended)
pip install cveye

cveye latest -l 5
cveye scan CVE-2021-44228
```

### Other install methods

```bash
# From a checkout (run without installing)
git clone https://github.com/PwnedBytes0x1/cveye.git
cd cveye
python3 main.py -h

# From a checkout (install the console script)
pip install .

# Docker
docker run --rm ghcr.io/pwnedbytes0x1/cveye latest -l 5

# Termux
git clone https://github.com/PwnedBytes0x1/cveye.git
cd cveye && bash termux-install.sh
```

### Requirements

| Requirement | Notes |
|-------------|-------|
| Python **3.7+** | stdlib only — no `pip install` needed |
| `git` | optional, only for `-clone-pocs` |
| `GITHUB_TOKEN` | optional env/config key; raises GitHub search limits |
| `NVD_API_KEY` | optional env/config key; raises NVD limit 5 → 50 req/30s ([free](https://nvd.nist.gov/developers/request-an-api-key)) |

## ⌨️ Commands

| Command | Purpose |
|---------|---------|
| [`latest`](#latest--newest-published-cves) | Newest published CVEs from NVD |
| [`search`](#search--cve-details) | Full details for one CVE |
| [`check`](#check--exploit-availability) | Exploit availability check |
| [`scan`](#scan--details--exploits) | Details + exploit check combined |
| [`affected`](#affected--am-i-affected) | Is my product (CPE) affected? |
| [`watch`](#watch--new-exploited-vulns) | Diff CISA KEV against last run |
| [`kev`](#kev--browse-the-kev-catalog) | Browse/search the KEV catalog |
| [`sbom`](#sbom--check-your-dependencies) | Check CycloneDX/SPDX components vs OSV |
| [`diff`](#diff--compare-two-result-sets) | Compare two CVEye JSON runs |
| [`report`](#report--htmlmarkdown-reports) | Render JSON as HTML / Markdown |
| [`completions`](#completions--shell-completions) | bash / zsh / fish scripts |
| `version` | Version information |

Flags use single-dash long options (`-json`, never `--json`) — short,
consistent, and easy to type.

### Global Flags

| Flag | Description |
|------|-------------|
| `-h, -help` | Show help and exit |
| `-V, -version` | Show version and exit |
| `-s, -silent` | Suppress info/warning messages (**errors still shown**) |
| `-no-color` | Disable ANSI colors |
| `-o, -output FILE` | Write stdout results to file |
| `-j, -json` | Machine-readable JSON output |
| `-no-cache` | Bypass the local response cache |

---

### `latest` — newest published CVEs

```bash
cveye latest                 # newest 10
cveye latest -l 20 -e        # 20 entries + exploit checks
cveye latest -l 50 -c        # compact, one line per CVE
cveye latest -json           # machine-readable
```

True newest-first ordering via NVD tail pagination. Fallback chain:
publish-date query → recently-modified query → CISA KEV catalog.

### `search` — CVE details

```bash
cveye search CVE-2021-44228
cveye search CVE-2021-44228 -f        # all references
cveye search CVE-2021-44228 -ghsa     # + GitHub Advisory (CWEs, malware flags)
```

Severity badge, CVSS v3/v4 score, **EPSS probability**, aliases, description,
affected products and references. IDs are validated client-side — garbage
input fails instantly, offline.

### `check` — exploit availability

```bash
cveye check CVE-2021-44228
cveye check CVE-2021-44228 -D -clone-pocs     # download + clone PoCs
printf 'CVE-2021-44228\nCVE-2024-3400\n' | cveye check - -c 10
```

### `scan` — details + exploits

```bash
cveye scan CVE-2021-44228
cveye scan CVE-2021-44228 -json
```

### `affected` — am I affected?

```bash
cveye affected CVE-2021-44228 -cpe apache:log4j
cveye affected CVE-2024-3400 \
    -cpe "cpe:2.3:a:paloaltonetworks:pan-os:10.2:*:*:*:*:*:*:*"
```

Accepts full CPE 2.3 URIs, legacy 2.2 notation, or `vendor:product`
shorthand. Wildcard-aware matching against NVD configuration data.

### `watch` — new exploited vulns

```bash
cveye watch                    # diff vs last run (state file)
cveye watch -since 168         # 7-day look-back window
cveye watch -json              # machine-readable
```

First run seeds the baseline; every later run prints only *new* KEV
additions — ransomware usage flagged in red.

Push new entries straight to chat with `-notify` (Discord, Slack, Teams,
or any generic JSON webhook — auto-detected from the URL):

```bash
cveye watch -notify https://discord.com/api/webhooks/... 
```

### `kev` — browse the KEV catalog

```bash
cveye kev -l 50                     # 50 most recent entries
cveye kev -vendor microsoft         # filter by vendor/product substring
cveye kev -product exchange -days 90
cveye kev -ransomware               # only ransomware-associated entries
cveye kev -priority                 # + compute triage priority per entry
```

### `sbom` — check your dependencies

```bash
cveye sbom -i cyclonedx.json
cyclyx generate | cveye sbom        # stdin works too
```

Reads CycloneDX or SPDX JSON, extracts Package URLs, and bulk-checks
every component against OSV in a single batched request. Exit code is
0 even when vulnerabilities are found (parse `-json` for CI gating).

### `diff` — compare two result sets

```bash
cveye latest -json -o old.json      # ...later...
cveye latest -json -o new.json
cveye diff old.json new.json
```

Reports added / removed / changed CVEs (severity, CVSS, EPSS, exploit
status). `-json` for machine-readable output; `-` reads one side from
stdin.

### `report` — HTML/Markdown reports

```bash
cveye scan CVE-2021-44228 -json | cveye report -o report.html
cveye latest -l 50 -json -o out.json && cveye report -i out.json -format md
```

Accepts any CVEye JSON payload (`scan`, `check`, `latest`, `search`).
Self-contained dark-themed HTML; clean Markdown tables.

### `completions` — shell completions

```bash
cveye completions -shell bash >> ~/.bashrc    # or zsh / fish
```

## 🎬 Demo

```text
$ cveye scan CVE-2021-44228

CVE Details: CVE-2021-44228
  CVE-2021-44228
  [CRITICAL]  Severity: CRITICAL  CVSS: 10.0
  Source: OSV (aka GHSA-jfh8-c2jp-5v3q)
  Published: 2021-12-10
  Modified: 2026-08-13 04:01
  EPSS: 100.0% exploitation probability (percentile 100.0)

Exploit Analysis
Strong signals found for CVE-2021-44228:

[!] CISA Known Exploited Vulnerability (exploited in the wild)
    Name: Apache Log4j2 Remote Code Execution Vulnerability
    Date Added: 2021-12-10
    Known Ransomware Use: Known

[+] ExploitDB exploits found:
    - [EDB-50592] Apache Log4j 2 - Remote Code Execution (RCE)
      https://www.exploit-db.com/exploits/50592

[+] GitHub PoC repositories found:
    - fullhunt/log4j-scan (3421 stars)
      https://github.com/fullhunt/log4j-scan

[+] SUMMARY: Exploits found for CVE-2021-44228
```

## 📡 Data Sources

| Source | What it provides | Key needed? |
|--------|------------------|-------------|
| [NVD 2.0 API](https://nvd.nist.gov/developers) | CVE details, CPE configs, CVSS | ❌ (5 req/30s) |
| [OSV.dev](https://osv.dev) | Rich vulnerability records | ❌ |
| [MITRE CVE Services](https://cveawg.mitre.org) | Authoritative CVE records | ❌ |
| [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | Exploited-in-the-wild list | ❌ |
| [FIRST EPSS](https://www.first.org/epss/) | Exploitation probability | ❌ |
| [ExploitDB mirror](https://gitlab.com/exploit-database/exploitdb) | Full exploits CSV index | ❌ |
| [GitHub Search](https://docs.github.com/rest/search) | PoC repositories | ❌ *(token optional)* |
| [GitHub Advisory DB](https://github.com/advisories) | GHSA records, CWEs, malware flags (`-ghsa`) | ❌ *(token optional)* |

## 🔍 Exploit Signal Model

CVEye refuses to cry wolf:

| Signal class | Examples | Effect |
|--------------|----------|--------|
| ✅ **Confirmed** | CISA KEV listing, ExploitDB entry, relevant GitHub PoC repo (CVE ID in name/description), PacketStorm / Metasploit / VulnCheck | Drives `has_exploit`, green summary |
| 💡 **Reference leads** | Pages merely mentioning *poc/exploit* keywords | Dim, labeled *"unconfirmed"* — never triggers a verdict |

## 🎯 Triage Priority

`latest -priority` and `scan` compute a composite triage level from
everything CVEye knows — CVSS severity, EPSS probability, exploit signals,
and KEV status:

| Level | Meaning |
|-------|---------|
| `P0` | CISA KEV — exploited in the wild |
| `P1` | Confirmed exploits + EPSS ≥ 0.5 (very likely exploited) |
| `P2` | Confirmed exploits OR very high EPSS OR GitHub-flagged malware PoC |
| `P3` | HIGH/CRITICAL severity without confirmation |
| `P4` | Baseline |

Results are sorted worst-first. `scan -json` includes the full
`priority` object with human-readable reasons.

## 📤 SARIF & CI Integration

`-sarif` on `latest`, `search`, and `scan` emits SARIF 2.1.0 with
GitHub `security-severity` properties — uploadable to code scanning:

```yaml
# .github/workflows/security.yml (excerpt)
- run: python main.py latest -l 50 -priority -sarif -o results.sarif
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: results.sarif }
```

## ⚙️ Configuration

`~/.config/cveye/config.json` (Windows: `%APPDATA%\CVEye\config.json`).
Precedence: **CLI flag > config file > environment > default**.

```json
{
  "limit": 10,
  "download_dir": "exploits",
  "concurrency": 5,
  "silent": false,
  "no_color": false,
  "no_cache": false,
  "github_token": "",
  "nvd_api_key": ""
}
```

## ♻️ Caching

| Data | TTL | Storage |
|------|-----|---------|
| CVE details | 1 hour | `~/.cache/cveye/cache.json` |
| EPSS scores | 24 hours | same |
| CISA KEV index | 30 minutes | `~/.cache/cveye/big-cache.json` |
| ExploitDB CSV index | 24 hours | same |

Bypass everything with `-no-cache` or `CVEYE_NO_CACHE=1`. Delete the files
to reset.

For very large batches, switch to the SQLite backend (single `cache.db`,
stdlib `sqlite3` only):

```bash
CVEYE_CACHE_BACKEND=sqlite cveye check - < many-cves.txt
```

## 🔗 Tool Interop

nuclei/httpx JSON lines are auto-detected on stdin — CVEs are extracted per
line, deduplicated, and processed:

```bash
cat nuclei-results.jsonl | cveye check - -silent
printf 'CVE-2021-44228\nCVE-2024-3400\n' | cveye scan - -c 20 -json
```

Failed lookups never vanish silently:

```bash
$ cat cves.txt | cveye scan - -json | jq '.[] | select(.error)'
{"cve_id": "CVE-2099-00001", "error": "lookup failed"}
```

## 🚦 Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Operational failure (not found, fetch failed, invalid ID) |
| `2` | Usage error (bad arguments, unwritable output) |

## 🏗️ Project Structure

```text
├── main.py            launcher shim (source checkouts)
├── Dockerfile         container image (GHCR published)
├── termux-install.sh  one-shot Termux installer
├── pyproject.toml     packaging (console script: cveye)
├── cveye/
│   ├── cli.py         entry point: global flags, stream redirection
│   ├── parser.py      argparse tree, custom help formatter
│   ├── output.py      banner, CVE printers, presentation helpers
│   ├── batch.py       stdin batch engine (concurrent, JSONL-aware)
│   ├── commands/      command implementations
│   │   ├── cve.py     latest / search / check / scan / affected
│   │   ├── intel.py   kev / sbom / diff
│   │   └── tools.py   watch / report / completions / version
│   ├── triage.py      priority scoring (P0-P4), EPSS trend
│   ├── sarif.py       SARIF 2.1.0 output
│   ├── notify.py      webhook notifications (Discord/Slack/Teams)
│   ├── config.py      URLs, constants, user-config loading
│   ├── colors.py      ANSI colors, tags/banner (stderr)
│   ├── utils.py       HTTP client, validation, CVSS v3, CPE
│   ├── cvss4.py       CVSS v4.0 scorer (official lookup embedded)
│   ├── cache.py       TTL caches (JSON default, sqlite optional)
│   ├── sources.py     NVD / OSV / MITRE / KEV / EPSS / GHSA fetchers
│   ├── exploits.py    exploit checker (KEV, refs, GitHub PoC, EDB)
│   ├── downloader.py  exploit file downloads, PoC repo cloning
│   └── report.py      HTML/Markdown report rendering
└── tests/             unittest suite (mocked, zero network)
```

## 🧪 Development

```bash
python3 -m unittest discover -s tests   # fully mocked test suite
python3 main.py -h                      # run from source
```

CI runs the suite on Python 3.7–3.13 via GitHub Actions on every push/PR.
Releases are published to PyPI automatically via Trusted Publishing.

Design notes:

- **CVSS v3.x** requires every mandatory metric — partial vectors are never
  guessed, so computed scores are never silently inflated.
- **CVSS v4.0** embeds FIRST's official MacroVector lookup + interpolation;
  validated against the **31,694-vector reference corpus (100% pass)**.
- **HTTP**: permanent 4xx errors are never retried; 429/5xx/network retry
  with backoff. Unknown CVEs fail fast instead of stalling.
- **Downloads**: filenames resolved from Content-Disposition / URL / content
  sniffing; oversized payloads refused; repo names sanitized before clone.

## ❓ FAQ

### Does this need API keys?

No. Every data source used by default is public. A GitHub token is optional
and only raises search rate limits.

### Why single-dash flags?

Short, consistent, and easy to type across every command.
`--json` is rejected on purpose — use `-json`.

### Is this a scanner?

No — CVEye performs **OSINT** about published vulnerabilities. It never
touches target systems.

### Windows support?

Yes. ANSI colors are enabled best-effort on legacy consoles; everything else
is pure stdlib.

## 🤝 Contributing

PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, test and style
guidelines, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community
standards.

Please keep the zero-runtime-dependency promise: stdlib only, Python 3.7+
compatible, and add tests for new logic.

## 🙏 Acknowledgments

- [FIRST](https://www.first.org/cvss/) — CVSS v4.0 specification & reference calculator (BSD-2-Clause, ported in `cvss4.py`)
- [NVD](https://nvd.nist.gov), [OSV.dev](https://osv.dev), [MITRE](https://cve.org), [CISA](https://www.cisa.gov/known-exploited-vulnerabilities-catalog), [FIRST EPSS](https://www.first.org/epss/), [ExploitDB](https://www.exploit-db.com) — the open data making this possible

## 📄 License

[MIT](LICENSE) © PwnedBytes0x1

---

<div align="center">

**If CVEye saved you time, consider leaving a ⭐**

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=flat-square&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/pwnedbytes0x1)

Made with ☕ and Python stdlib by [PwnedBytes0x1](https://github.com/PwnedBytes0x1)

</div>
