---

[!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?
• Quick Start
• Commands
• Demo
• Data Sources
• Exploit Signal Model
• Configuration
• Caching
• Tool Interop
• Exit Codes
• Project Structure
• Development
• FAQ
• Contributing
• Acknowledgments
• 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.

✅ 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

# Install from PyPI (recommended)
pip install cveye

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

Other install methods

# 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)

⌨️ Commands

Command	Purpose
latest	Newest published CVEs from NVD
search	Full details for one CVE
check	Exploit availability check
scan	Details + exploit check combined
affected	Is my product (CPE) affected?
watch	Diff CISA KEV against last run
kev	Browse/search the KEV catalog
sbom	Check CycloneDX/SPDX components vs OSV
diff	Compare two CVEye JSON runs
report	Render JSON as HTML / Markdown
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

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

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

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

cveye scan CVE-2021-44228
cveye scan CVE-2021-44228 -json

affected — am I affected?

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

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

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

kev — browse the KEV catalog

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

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

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

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

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

🎬 Demo

$ 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	CVE details, CPE configs, CVSS	❌ (5 req/30s)
OSV.dev	Rich vulnerability records	❌
MITRE CVE Services	Authoritative CVE records	❌
CISA KEV	Exploited-in-the-wild list	❌
FIRST EPSS	Exploitation probability	❌
ExploitDB mirror	Full exploits CSV index	❌
GitHub Search	PoC repositories	❌ (token optional)
GitHub Advisory DB	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:

# .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.

{
  "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):

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:

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:

$ 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

├── 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

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 for setup, test and style guidelines, and 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 — CVSS v4.0 specification & reference calculator (BSD-2-Clause, ported in cvss4.py)
• NVD, OSV.dev, MITRE, CISA, FIRST EPSS, ExploitDB — the open data making this possible

📄 License

MIT © PwnedBytes0x1

---