nmap-vulners: it replaces the script nmap already ships, and a leftover file keeps sweeping
Nmap NSE scripts that turn a service scan into CVEs, CVSS scores and known exploits — fingerprints software from HTTP responses and checks every detected CPE against the Vulners database.
At a glance
- What is it?
- nmap-vulners is a single NSE script that takes the software nmap already identified on each port and asks a vulnerability database what is known about that exact version, then prints the answer inside the scan report ordered by exploitability. It stays out of nmap's default script set on purpose, because using it sends the identity of your target's software to a third party. Use it on hosts you are authorised to assess.
- Who is it for?
- nmap-vulners is worth having if you already run service detection scans and want the answer prioritised by what is actually being used against real systems rather than by score alone. Three things to settle first.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly Lua, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.
Star history
- vulnersCom/nmap-vulners3,515 ★ · +24
| Repository | 2026-09-24 | 2026-11-13 |
|---|---|---|
| vulnersCom/nmap-vulners | 3.5k | 3.5k |
24 Stars in the last 50 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The script stays out of nmap's default set, and the file says why
Start with the design decision that matters most, because it is a consent decision.
The script is deliberately not part of nmap's default script set, so a plain default scan will not run it. The stated reason is that sending the identity of your target's software to a third party should be something you asked for.
That is the correct boundary for a tool of this kind, and it is worth stating plainly what it implies. Running it means the products and versions detected on your target leave your network and reach the vendor's database. On a network you are authorised to assess, that is an acceptable cost of a prioritised answer. On someone else's network it is not your scan to enrich, and this is exactly the case the default-set exclusion is designed to catch.
The interface itself is one command, and two parts of it matter. The version detection flag is not optional, because without it nmap reports that a port is open and nothing more, which leaves no software to ask about. The file names that as the single most common reason for an empty result. The second flag is the script selector, which is the deliberate opt-in:
nmap -sV --script vulners scanme.nmap.orgA leftover file from the older line keeps sweeping targets under a plain scan
Here is the one operational trap in the whole project, and it deserves its own section because it undoes the consent boundary above.
Upgrading from the older line means two files have to be deleted from the script directory by hand, in addition to installing the new one. One of them, a leftover script from the older line, still carries nmap's default category. That means it keeps sweeping targets under a plain default scan, which is precisely the behaviour the current script was moved out of the default set to avoid.
So the exclusion described in the previous section protects you only if you clean up. A leftover file silently restores the behaviour, sends target software details to a third party on scans you did not ask to enrich, and produces output that looks like it came from the tool you installed.
The file is explicit that the installer does this cleanup for you. That is the argument for using the installer rather than copying a file by hand, and it is the argument for checking the directory after an upgrade you did by hand.
The old script also had a different name for its work, which means the presence of both files is visible in a directory listing if anyone looks. The default sweep is the part that does not announce itself.
It replaces a script of the same name that nmap ships itself
nmap bundles a script with this project's name. The file says so plainly: the installer checks that the script selector really resolves to what it just installed, because nmap ships its own copy and this replaces it.
That check exists because the alternative failure is invisible. Ask nmap to run the script by name and it may run the copy in its own script database rather than the one you installed, and both work, so nothing fails and nothing tells you which one ran. The output looks the same.
The same trap has a second form, and the file documents it for people running from a checkout. A relative path to the script in the checkout is resolved against nmap's own script database first, so it quietly runs the shipped copy instead of yours. The fix is to pass an absolute path, which works because the script can be run directly from where you cloned it without installing anything.
Together with the previous section, that is three ways for the wrong file to run: the bundled copy, a leftover older file, and a relative path. All three produce output rather than an error, which is why the file spends more words on this than on the actual query.
Two installers, four options each, and a way to ask nmap where it keeps its data
Installation is a one-line pipe on both platforms, with the same four options behind it.
On Unix-like systems including macOS, Linux, Kali and WSL, the installer is fetched and run in one command with no arguments. On Windows the equivalent is a PowerShell invocation that has to be run as administrator.
The installer asks nmap where it keeps its data directory rather than guessing, copies the script there, rebuilds the script database, and performs the resolution check described above. It also offers to store an API key if you have one.
The options cover the four cases people actually hit. A user mode installs into the directory in your home with no elevated rights and prints the environment line you need to add to your shell profile. A prefix option targets a specific directory. A reference option installs a specific release rather than the branch tip. And an uninstall option removes what it installed. The Windows installer takes the same four under different spellings.
For finding the right directory, the file lists the usual locations per platform and then gives a better method: ask nmap itself with a debug-level script-help probe, and the directory holding the script database's main file is the one this nmap uses. That is more reliable than the table, because the table is where installations drift.
By hand it is one file, because the script fetches its fingerprints at scan time
The manual install is described as one file plus one command: copy the script into the scripts directory inside nmap's data directory and rebuild the script database with elevated rights.
The reason nothing else is needed is worth reading, because it explains a design choice rather than an omission. The script downloads its fingerprint data at scan time and writes nothing to disk. So there is no second file to place, no data directory to populate, and nothing to forget.
The last part of that sentence is the historical note. The file says this used to produce a script that ran, found nothing, and said nothing about why, which is the worst failure mode a lookup tool has: it looks like a clean result. Moving the fetch to scan time removes an entire class of installation mistake.
There is a small tension between the two halves of this repository worth noting. The manual instructions say the data is downloaded at scan time, and the repository tree also contains a catalogue directory, so the data exists in two places depending on which route you took. Nothing in the visible text explains which one the script uses.
The ranking is by what is being used against real systems, not by score
The output is a block inserted under each port that has something known against it, and the ordering is the whole point.
The script prints findings ordered so that the things people are actually being attacked with come first, rather than merely the things with the highest score. That is a deliberate departure from severity sorting, and it explains why the example block leads with three critical rows that differ in the second numeric column even though the severity word is identical.
The header line names one piece of software and counts it. A common platform identifier spelling out kind, vendor, product and version is followed by the number of records held for that exact version, and then by how many of those are published exploit code or have some. A single port can produce several blocks: a web server, the interpreter behind it, and a library on the page.
The visible columns are severity, a base score, a second score that is not the same number, a flags column where an exploit marker appears on some rows, and a link column. The second score and the flag meanings are described in a table that the file cuts off before finishing, so those two are the ones to check in the documentation rather than infer from the sample.
No account is needed, and three releases shipped on one morning
The last practical point is what it costs to use and how fast it moves.
No account and no key are required. A free key makes each answer richer, and there is a documentation section that shows the same scan run both ways. The concrete effect stated in the output section is that the count of findings reported as having published exploit code goes up with a key, so the free tier is a subset rather than a different product.
The release history is unusually compressed. Three releases landed on the same morning in August 2026, about an hour apart, taking the version from 2.0 to 2.0.2. That is the signature of a release that stabilised its packaging rather than of a slow-moving tool, and it is also a reason to look at what changed between 2.0 and 2.0.2 before pinning.
On licensing, the repository records no recognised identifier while a licence file sits at the root, so the terms are in the file rather than in the metadata. And the contents table promises five more sections, covering ranking, a politeness section for scanning, the machine-readable output, the options reference and the troubleshooting material; the text available here stops inside the columns table, so those are sections to look for in the repository rather than facts to read here.
Editorial conclusion
nmap-vulners is worth having if you already run service detection scans and want the answer prioritised by what is actually being used against real systems rather than by score alone. Three things to settle first. It is an enrichment step on top of a scan you are already running, so it inherits that scan's authorisation scope, and running it sends product names and versions to a third-party service, which is why it is not in the default script set. The most common empty result is a scan without version detection, since there is then no product identity to look up. And if you are upgrading from the older line, delete the old scripts by hand, because a leftover one of them still sits in the default set and will keep sending target details on a plain scan.
Frequently asked questions
What does the nmap-vulners script do?
It takes the software nmap already identified on each open port, asks the Vulners database what is known about that exact version, and prints the answer under that port in your existing scan report, ordered so that what is actually exploited comes before what merely scores highest.
Do I need an API key for nmap-vulners?
No. It works with no account and no key. A free key makes each answer richer, and the file notes specifically that the number of findings reported as having published exploit code goes up with a key.
Why does my nmap-vulners scan return nothing?
Version detection is not optional. Without it nmap reports only that a port is open, so there is no software identity to look up, and the file names that as the most common reason for an empty result.
Will nmap-vulners run under a plain default script scan?
The current script is deliberately outside the default set, so a plain scan will not run it. A leftover file from the older line still carries the default category, so on an upgrade you must delete the old scripts by hand or a plain scan will keep sweeping targets.
How do I install nmap-vulners without root?
The installer has a user mode that installs into the nmap directory inside your home with no elevated rights and prints the environment line to add to your shell profile. It also takes a prefix option, a release reference option and an uninstall option, with different spellings for the PowerShell installer.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/vulnerscom-nmap-vulners)Star history chart for your README
[](https://hysenlabs.com/projects/vulnerscom-nmap-vulners)Was this useful?