[ cvescope: CVEs That Hit the Gear You Actually Run ]

[ 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/
The cvescope exposure page on its demo network: a header with 29 act now, 217 watch and 726 info counts and a CVE search box; a left sidebar listing inventory items like Apache HTTP Server, Tomcat, a FortiOS edge firewall, GitLab, Jenkins and OpenSSH with per-item tier counts; and a ranked list of CVEs, each with an affected badge, the matched item and version, evidence pills (KEV, Metasploit, Nuclei, Exploit-DB, GitHub PoC counts), CVSS and EPSS, and a one-line reason.
The exposure page on the made-up demo network. Each CVE carries the item it hit, the exploitation evidence, and a plain-language reason it's ranked where it is.

[ 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.
A cvescope CVE detail panel for CVE-2024-23897 on the demo network: an Act now banner, the description, CVSS 9.8 critical with its vector, CWE-27, EPSS at 100% and percentile 100, SSVC exploitation active, the matched inventory item (Jenkins build box 2.441), the CISA KEV entry with added and due dates and the ransomware flag, the Metasploit module name, and the Nuclei template.
The detail panel for one CVE: the reason up top, then CVSS, EPSS, SSVC, which of my items it hit, and the KEV, Metasploit and Nuclei evidence.

[ 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 -sV scan 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 or verify_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 like OpenSSH (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 run cvescope sync on a schedule, and only real changes
come through: a cron line every few hours on Linux, or a Task Scheduler job on
Windows. --log keeps a record of every run, since nobody is watching a
console, and cvescope sync --dry-run prints 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 status says 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 --test fires 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.
The exploit-sources section of a cvescope CVE detail on the demo network: the Metasploit module, a Nuclei template, an Exploit-DB entry, and a GitHub PoCs list of 52 repos under a banner reading Repos are listed, never fetched; fake PoCs that drop malware on researchers are common, read the code first and only run it in a throwaway VM. Each repo shows stars, forks and creation date, with warnings like created within 2 days of disclosure and no description.
The exploit sources for one CVE. The GitHub PoCs are listed from the index, never fetched, and the sketchy ones are flagged.

[ 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.
cvescope on a phone: the header tier counts and CVE search stack, the Your exposure / Changes / Out in the wild tabs sit below, and each CVE becomes a full-width card with its evidence pills wrapping underneath.
The same page on a phone, over the LAN. It reflows to single-column cards, so a quick check from the couch works too.

[ 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 ]