[ cvescope: CVEs That Hit the Gear You Actually Run ]
[ Overview |
What's new |
How it ranks what matters |
What it watches |
Where the evidence comes from |
Staying current |
A word on fake PoCs |
What stays on your machine |
FAQ ]
[ Overview ]
There are more than 40,000 new CVEs a year, and almost none of them matter to me. cvescope is the tool I built to find the few that do. I give it the gear I actually run — the firewall, the hypervisors, the DNS boxes, a handful of apps — and it matches their versions against the full CVE List, then ranks what's left by whether anyone is actually exploiting it. The ranking is the whole point. A CVSS 9.8 nobody has ever touched sits below a 7.5 with a Metasploit module and a spot on CISA's Known Exploited list. cvescope pulls that evidence from CISA KEV, EPSS, Metasploit, Nuclei, Exploit-DB, the public PoC index, and my own exploit archive, and sorts everything into three tiers: act now, watch, and info. It runs on my own machine. Python 3.11+, standard library only, no account and no API keys. It never scans anything — it only reads what I tell it to. Free software, GPL-3.0-or-later. git clone https://github.com/magikh0e/cvescope && cd cvescope pip install . cvescope init # writes a starter config to your user config dir cvescope sync # first run pulls the feeds (~750 MB, ~800 MB on disk) cvescope report # act-now and watch tiers in the terminal cvescope serve # the same thing as a page on http://127.0.0.1:8096/ GitHub source, README and changelog Releases tagged versions and notes Wiki setup, every collector, troubleshooting The screenshots below use the made-up network in the project's demo config, not my own gear. You can bring it up the same way: cvescope --config examples/demo.toml sync cvescope --config examples/demo.toml serve # http://127.0.0.1:8098/
[ What's new ]
New in 0.2.3: less noise, and a warning when the schedule stops.
Sync health the header shows when the last full sync finished. A
banner goes up if that's more than 12 hours ago, or if a
feed or collector failed, so a scheduled sync that quietly
stopped doesn't go unnoticed.
Less noise apps that update themselves stop carrying year-old CVEs
with no version data, and a "check" on a backported kernel
or vendor build only shows up once it's actually exploited
Removed packages dpkg also lists packages that were removed but left
their config files behind. Those don't count anymore.
0.2.2 added the pieces for running it unattended: a --log option, cron and
Task Scheduler setups in the README and wiki, Discussions for
questions, and an issue form for wrong or missing matches.
Before that, 0.2.1 taught it to run osquery live, here or over ssh, and
0.2.0 added most of what it can see today: the Debian and Ubuntu security
trackers for distro packages, every Proxmox VM and container, Docker and Podman
containers, desktops through osquery or a PowerShell script, WPScan and WhatWeb
reports, and nmap -sV scans.
The release notes have the details and the upgrade steps.
[ How it ranks what matters ]
Everything that matches lands in one of three tiers, newest-evidence first:
Act now exploited in the wild (CISA KEV, or SSVC "active"), a Metasploit
exploit module, or a Nuclei template for a CVSS 7+ bug
Watch public exploit code (Exploit-DB, a GitHub PoC, or a hit in my
own archive), a Metasploit auxiliary, SSVC "poc", or EPSS in
the top 10%
Info it matches, but nothing suggests anyone is using it
The counts in the header are those three tiers. The sidebar carries the same
split per item, so I can see at a glance which box is on fire. Click any CVE and
the detail panel lays out everything behind the ranking: the description, CVSS
with its vector, CWE, the EPSS probability and percentile, the SSVC decision,
which of my items it hit and why, and then the evidence itself — the KEV entry
with its due date, the Metasploit module, the Nuclei template, the Exploit-DB
entry.
Matching a version to a CVE is messier than it sounds, because CVE records spell
versions every which way. cvescope settles each match into one of four states:
affected your version is inside an affected range
check the product matches but the record can't settle your
version, or it's a distro or vendor build whose fixes may be
backported. A check like that only makes the lists once it's
actually exploited. Debian and Ubuntu packages skip all this,
because their own trackers decide.
not_affected your version is outside every affected range; kept and
counted as ruled out
keyword an old record that names no product but mentions your item
in its text; low confidence, hidden unless you ask
It copes with free-text ranges ("before 2.4.60", "1.1.1d-1.1.1f"), FreeBSD patch
levels, and CISA's habit of splitting one product into many single-range
entries. When a record carries no version data at all, it reads the description
and rules the CVE out only when the versions named there are clearly older than
yours. For apps that update themselves, like browsers and VS Code, a record
with no version data that's over a year old is ruled out too. Anything
open-ended stays check rather than guessing.
[ What it watches ]
An inventory is a list of collectors, each one a thing cvescope reads a version from. Some I just type in; most it pulls on its own: static a product and version you type in command a version pulled from any command's output (over ssh too) dpkg Debian/Ubuntu packages, judged by the distro's own tracker http_json a version field from any JSON endpoint nmap_xml every service nmap identified in a-sVscan you ran docker the app in each running Docker or Podman container osquery installed programs and packages; cvescope runs osqueryi live, here or over ssh, or reads a saved export or the repo's Windows inventory script wpscan WordPress core, theme and plugin versions from WPScan whatweb web server, PHP and CMS versions from WhatWeb proxmox PVE plus every VM and container (VM OS and kernel through the guest agent), optionally QEMU, LXC and the host kernel opnsense OPNsense, its FreeBSD base, OpenSSL, OpenSSH, Unbound and more unifi the UniFi controller and every adopted device's firmware pihole Pi-hole core, FTL and web versions homeassistant HA Core, and the OS and add-ons with an admin token Secrets never go in the config. You point at a token file or environment variable instead. For a self-signed appliance, you pin its certificate fingerprint once (cvescope pin host:443, checked against the device's own UI), and cvescope refuses to connect without either a pin orverify_tls. If a collector fails because a box is down or a token expired, its last known versions are kept and the page marks it, so one outage doesn't make the matches vanish. For a Debian or Ubuntu host, I hand the dpkg collector the host's os-release along with the package list. From then on the distro's tracker has the last word: a package built with a backported fix counts as fixed, even when its upstream version number sits inside the affected range. The thing it won't do is go looking. cvescope only knows what's in the config. To cover the NAS or old VM nobody remembers, you run an nmap version scan yourself, on a network you're allowed to scan, and feed it the XML: nmap -sV -oX ~/scans/lan.xml 192.168.1.0/24 Every service nmap versioned becomes an item, named likeOpenSSH (nas.lan:22). Your IDS will see that scan, so if you run one, plan for the alerts. cvescope still never sends a packet of its own.
[ Where the evidence comes from ]
cvescope fetches a handful of public feeds and keeps them in a local database.
The first sync is the big one; after that it's small deltas.
CVE List every CVE record, with CISA's Vulnrichment (SSVC, CPEs,
CVSS) — ~660 MB once, then hourly/daily delta zips
CISA KEV confirmed exploitation in the wild
FIRST EPSS a daily 30-day exploitation probability per CVE
Metasploit module metadata: weaponized exploits and scanners
Nuclei the templates index of mass-scannable checks
Exploit-DB the index of published exploit code
PoC-in-GitHub repos claiming a PoC (metadata only — see below)
your folders any local file that mentions a CVE ID
Debian tracker which package build fixed each CVE, per Debian release
(via OSV), pulled only if I run Debian
Ubuntu OVAL the same for Ubuntu, a couple of MB per release
That last one is why cvescope and my exploit archive talk to each other: I
point a local collector at the archive, and a CVE I've already got exploit code
for gets pushed up the list. The archive is a first-class exploitation source
alongside Metasploit and Exploit-DB.
It matches against the CVE List itself, not the NVD, because the NVD's analysis
backlog means it often lags the records it's enriching. The feeds keep their own
terms; cvescope fetches them at run time and redistributes none of their data.
[ Staying current ]
A one-time report is the boring part. The useful part is the day a quiet CVE stops being quiet. The Changes tab is exactly that: a CVE touching my inventory that got added to KEV, picked up an exploit, had its EPSS jump, or stopped applying after I upgraded. The Out in the wild tab is the wider weather — recent KEV additions, newly weaponized CVEs and the highest-EPSS new ones — whether or not I run the product. The first sync of each feed loads quietly and raises nothing; it's treated as history. After that I runcvescope syncon a schedule, and only real changes come through: a cron line every few hours on Linux, or a Task Scheduler job on Windows.--logkeeps a record of every run, since nobody is watching a console, andcvescope sync --dry-runprints what it would send without marking anything as seen. The wiki sets up both, step by step. The page also tells me when that schedule stops. Its header shows when the last full sync finished, and a banner goes up when that's more than 12 hours ago or when a feed or collector failed.cvescope statussays the same. When something crosses a tier I care about, it tells me. Alerts go over ntfy, straight into Home Assistant, or to any webhook, and you set the floor — say, only page me for "act now": [notify] min_tier = "act" [[notify.ntfy]] url = "https://ntfy.sh/pick-a-long-random-topic"cvescope notify --testfires one message at every channel so you know it works before you rely on it.
[ A word on fake PoCs ]
Fake proof-of-concept repos that drop malware on whoever runs them are an old trick, and they spike right after a juicy CVE lands — exactly when people go looking for exploit code. cvescope lists PoC repos because knowing one exists is useful, but it is careful about them. It never clones or fetches a PoC repo. It reads the index's metadata only, and flags the usual tells: no stars or forks, no description, a pitch to download a release or make contact, created within a couple of days of disclosure. The banner over the list says it plainly — read the code first, and run it only in a throwaway VM.
[ What stays on your machine ]
cvescope's results are a map of exactly what's weak on my network, so none of it
leaves. It runs locally, downloads the public feeds, and matches in its own
database. There's no cvescope server anywhere, and there are no accounts.
The serve page binds to 127.0.0.1 and rejects any request whose Host header
isn't the address it's serving on, which stops another website from reaching it
through a DNS-rebinding trick. If you bind it wider than localhost, put real
authentication in front of it — it's a list of what to attack and where.
The only traffic that leaves the machine is fetching the public feeds and
whatever alert channel you set up. Credentials for the appliances it reads live
in token files or environment variables, pinned to each device's certificate,
and are never written into the database or the page.
[ FAQ ]
Does cvescope scan my network? No. cvescope never scans anything. It only reads the versions of the gear you list, from the APIs and files you point it at. If you want it to cover a box nobody remembers, you run an nmap version scan yourself, on networks you're allowed to scan, and point an nmap_xml collector at the output. Does cvescope send my data anywhere? No. It runs on your own machine, downloads public feeds, and matches locally. The results page binds to 127.0.0.1 and rejects requests whose Host header isn't the address it serves on, which blocks DNS-rebinding tricks from other websites. The only outbound traffic is fetching the public feeds and whatever alert channel you set up. What do the act now, watch and info tiers mean? Act now is exploited in the wild (CISA KEV, SSVC "active"), a Metasploit exploit module, or a Nuclei template for a CVSS 7+ bug. Watch is public exploit code (Exploit-DB, a GitHub PoC, your own archive), a Metasploit auxiliary module, SSVC "poc", or EPSS in the top 10%. Info means it matches, but nothing suggests anyone is using it. What gear can cvescope track? Anything you can name a version for. Type it in, pull it from any command's output or a JSON endpoint, or use the built-in collectors: Proxmox (including every VM and container), OPNsense, UniFi, Pi-hole, Home Assistant, Debian and Ubuntu packages, Docker and Podman containers, and osquery or a PowerShell script for desktops. It also reads reports you ran from nmap -sV, WPScan and WhatWeb. Does cvescope understand distro backports? For Debian and Ubuntu, yes. Distros often patch a CVE without changing the upstream version number, so cvescope asks the Debian security tracker and Canonical's Ubuntu data which package build fixed each CVE, and compares that with the build you have installed. For other distros and appliances, an in-range match shows as check so you can look it up yourself. Where does the exploitation evidence come from? CISA KEV, FIRST EPSS, Metasploit module metadata, the Nuclei templates index, the Exploit-DB index, the PoC-in-GitHub index, and any local folders you point it at, like your own exploit archive. It matches against the full CVE List, including CISA's Vulnrichment. The NVD is not used, because its analysis backlog lags the CVE List. Does cvescope clone or run GitHub PoCs? No. It only lists the PoC index's metadata and flags the usual fake-PoC tells: no stars or forks, no description, a pitch to download a release or make contact, created within two days of disclosure. Read the code first, and run it only in a throwaway VM. How do I know the scheduled sync is still running? The page's header shows when the last full sync finished. If that's more than 12 hours ago (the limit is a setting), or a feed or collector failed in the last run, a banner says so and names what failed. cvescope status prints the same. Where do I ask questions or report a wrong match? Questions go to the project's GitHub Discussions. If cvescope matched a CVE it shouldn't have, or missed one, use the wrong-match issue form. It only asks for the CVE, the product and version, and the collector, so leave hostnames and IPs out. Security problems in cvescope itself go to GitHub's private reporting. Is cvescope free? Yes. It's free software under the GPL-3.0-or-later, and the source is on GitHub. It's Python 3.11+ with no third-party dependencies.
[ See Also ]
cvescope on GitHub # source, README and releases
The cvescope wiki # setup, every collector, matching, troubleshooting
cvescope Discussions # questions, ideas and setups
The demo network # the made-up gear in the screenshots
fwscope # its sibling: firewall, WAF and IDS logs in the browser
The exploit archive # one of cvescope's PoC sources
AI Attacks and Defense in Depth # why layered defense still matters
Code & Tools (parent) # the rest of the code
