cveye 3.2.0__tar.gz

cveye-3.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PwnedBytes0x1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cveye-3.2.0/PKG-INFO

@@ -0,0 +1,511 @@
+Metadata-Version: 2.4
+Name: cveye
+Version: 3.2.0
+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.0-blue?style=for-the-badge" alt="version">
+<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*
+
+[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
+# Run directly from a checkout
+git clone https://github.com/PwnedBytes0x1/cveye.git
+cd cveye
+python3 main.py -h
+
+# Or install as a proper console script
+pip install .
+cveye latest
+```
+
+### 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)
+```
+
+## 🐳 Other install methods
+
+```bash
+# 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
+```
+
+## 🧪 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 ⭐**
+
+Made with ☕ and Python stdlib by [PwnedBytes0x1](https://github.com/PwnedBytes0x1)
+
+</div>