nmap-vulners: turning an nmap service scan into CVEs, exploits and CVSS scores

What nmap-vulners adds to a service scan

nmap already answers what software is listening on a port. nmap-vulners answers what is wrong with it. The script takes the software nmap identified during version detection, asks vulners.com what is known about that software, and prints the result inside the normal scan report under the matching port. It is aimed at people who already run nmap during reconnaissance and want CVE context without introducing a second scanner into the workflow. The README is explicit that the script is not part of nmap's default script set, so a plain -sC will not run it. That is a deliberate choice: sending the identity of your target's software to a third party should be something you asked for, not a side effect of a default scan. The output is ordered so that what is being attacked in the wild comes first, rather than simply what carries the highest score, which is the part that separates this from a raw database lookup.

How the CPE lookup and ranking actually work

The mechanism is narrow, and that is a strength. nmap's version detection produces a CPE for each matched service, the script sends that CPE to the Vulners API, and the response is rendered as an indented block beneath the port line. The header of that block names one piece of software and counts what was found against it, in the form cpe:/a:apache:http_server:2.4.7 followed by a findings count and an exploitable count. Each row carries a severity, a CVSS score, an AI score, a flags column and a link into vulners.com. The flags column is where the practical value sits: the README's example output marks rows with EXP, and the ordering pushes those rows up. A CVSS 10.0 with no known exploit and a CVSS 9.8 with an exploit entry are not the same operational problem, and the default sort reflects that. The script downloads its fingerprint data at scan time and writes nothing to disk, so there is no local database to age or to corrupt. The trade-off is that a scan is only as good as the CPE nmap produced. If version detection is wrong or vague, the lookup inherits that error.

Installing nmap-vulners and running a first scan

The README gives a one-line installer for macOS, Linux, Kali and WSL, and a PowerShell equivalent for Windows run as Administrator. The installer asks nmap where it keeps its data, copies the script there, rebuilds the script database, and then verifies that --script vulners resolves to what it just installed. That last step matters because nmap ships a vulners.nse of its own, and this replaces it.

curl -fsSL https://raw.githubusercontent.com/vulnersCom/nmap-vulners/master/install.sh | sh

On Windows, in PowerShell as Administrator:

irm https://raw.githubusercontent.com/vulnersCom/nmap-vulners/master/install.ps1 | iex

If you cannot or do not want to install system-wide, the installer takes a --user flag that places everything in ~/.nmap and prints the NMAPDIR line to add to your profile. A specific directory and a specific release are also accepted:

curl -fsSL https://raw.githubusercontent.com/vulnersCom/nmap-vulners/master/install.sh | sh -s -- --user
./install.sh --prefix /usr/local/share/nmap
./install.sh --ref v2.0

The first real scan is one command, and the README states that -sV is not optional because it is the flag that makes nmap work out which software is behind each port:

nmap -sV --script vulners scanme.nmap.org

You get the usual nmap report with a block added under each port that has something known against it. If the block never appears, the README names the most common cause: the scan ran without -sV, so there was no software identity to look up and the script had nothing to do.

Running from a checkout, and the relative path trap

Cloning the repository and running the installer from inside it installs exactly what you cloned, because the installer uses the files sitting next to it. You can also skip installation entirely and point nmap at the script in place, but the README warns about path resolution here. nmap resolves a relative --script ./vulners.nse against its own script.db first and quietly runs the copy that shipped with nmap instead of yours. Use an absolute path:

nmap -sV --script "$PWD/vulners.nse" <target>

Upgrading from 1.x has its own cleanup step. The README says to delete vulners_enterprise.nse and http-vulners-regex.nse from the nmap scripts directory. The second one is the sharper problem: a leftover http-vulners-regex.nse still carries the default category, so it keeps sweeping targets under a plain -sC scan, which is exactly the behaviour the current design avoids. The installer removes these for you. If you placed files by hand, nothing does.

Where the fingerprint data comes from, and what that costs you

The README has a section on where fingerprints come from, and the answer shapes how you should think about coverage. The script does not build its own signature set. It consumes the CPE that nmap's version detection produced and hands that string to Vulners. A service nmap cannot identify produces no CPE, so it produces no findings, and the report says nothing about the gap. The README's own demo shows the other end of this: a web port where nmap reports a Coyote banner and the sweep names the Tomcat and the jQuery behind it. That is the script doing real work beyond a literal CPE match, but it is still bounded by what the response contains. Any service behind authentication, a non-standard banner, or a protocol nmap does not fingerprint will come back empty. An empty block is not evidence that a host is clean, and the README does not present it as such.

The API key question: what changes and what does not

The script works with no account and no API key. A free key makes each answer richer, and the README devotes a section to showing the same scan run both ways rather than describing the difference in the abstract. The installer offers to store a key if you have one, and the README documents where to keep it. Two things follow from this. First, the no-key path is genuinely usable, which is unusual for a tool that depends on a commercial database, and it makes evaluation cheap. Second, you must not compare a finding count from an unauthenticated scan against one from an authenticated scan and treat the difference as a change in the target. It is a change in the answer, and the README's side-by-side exists precisely to make that visible. If you plan to feed this output into a report, decide which mode you are standardising on before you start collecting.

Vulscan and full vulnerability scanners: what is actually different

Vulscan is the comparison people reach for, and the difference is in where the data lives and who curates it. Vulscan is an nmap script that matches detected services against offline databases shipped with it, so it works air-gapped and needs no network call during a scan, at the cost of whatever staleness the local copies carry and manual updating. nmap-vulners inverts that: nothing is shipped, the fingerprint data is downloaded at scan time, and the answers come from vulners.com. That gives fresher data and the exploit flagging, and it means every scan makes an outbound request that discloses the software identity of the target. A full vulnerability scanner such as an authenticated agent-based tool is a different category again: it can inspect installed package versions on the host itself, which an unauthenticated nmap scan cannot do, and it produces host-level rather than port-level findings. nmap-vulners is not competing with that. It is competing with doing the CPE-to-CVE lookup by hand, which is the realistic alternative for most people who would use it.

Licence, maintenance and the cost of keeping up

The repository carries a NOASSERTION licence identifier, and the README's badge points at the Nmap Public Source licence. Those two signals do not agree, and the practical consequence is that anyone redistributing the script or bundling it into a product should read the LICENSE file rather than assume a permissive default. This is not legal advice; it is a reason to open the file. On maintenance, the last push was on 2026-09-21 and the most recent release, v2.0.2, is dated 2026-08-20, with v2.0 and v2.0.1 both dated 2026-08-20. The upgrade path from 1.x is the part with real cost: it is not a drop-in replacement, because two scripts were removed and one of them used to run under -sC. The installer handles the cleanup, so the cost is concentrated in environments where files were placed by hand or where the installer cannot run. The script itself has no local database to update, which removes the usual recurring maintenance task, but it also means the answers depend on a live service being reachable and on nmap's version detection being accurate.

Editorial conclusion

Adopt nmap-vulners if you already run nmap -sV and want per-port CVE context without standing up a scanner. Skip it if you need authenticated, host-level findings or your rules forbid sending detected CPEs to a third party. Before relying on it, run the same host with and without a Vulners API key and compare the finding counts, since the README shows the answer getting richer once a key is present.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. vulnersCom/nmap-vulners on GitHub