🔍 VulnScanner

Professional-grade network vulnerability scanner — port scanning, CVE analysis, and risk-scored reporting in one tool.

Features · Installation · CLI Usage · Web UI · Screenshots · Project Structure

---

Overview

VulnScanner is a modular Python tool that combines TCP port discovery with National Vulnerability Database (NVD) CVE lookups to produce ranked, risk-scored vulnerability reports. It identifies open services on a target host using Nmap or a raw-socket fallback, queries the NVD API v2 for known CVEs per service with full CVSS v3 scoring, and outputs actionable findings in CSV, HTML, and JSON — all from a single CLI command or through an interactive Streamlit web dashboard with a live terminal feed, colour-coded results table, summary cards, and persistent scan history.

---

Features

Category	Capability
Scanning	Nmap -sV -T4 service detection with automatic raw-socket fallback
Scanning	Banner grabbing for service identification on non-standard ports
CVE lookup	NVD API v2 with rate-limit handling and CVSS v3.1 → v3.0 → v2 fallback
CVE lookup	Severity filtering at query time (LOW / MEDIUM / HIGH / CRITICAL)
Risk engine	Weighted scoring with diminishing returns; normalised risk category
Risk engine	Scan diff — identify new, resolved, and persisting CVEs across snapshots
Reports	Timestamped CSV, styled HTML executive report, and JSON
Web UI	Live terminal feed streamed line-by-line during scanning
Web UI	Colour-coded findings table with clickable NVD links
Web UI	4 summary cards: overall risk level, open ports, CVE count, scan duration
Web UI	Scan history — last 5 scans in sidebar, one-click result restore
Web UI	Demo mode — full interface walkthrough with no real target required

---

Tech Stack

Layer	Technology
Language	Python 3.10+
Port scanning	python-nmap · raw socket
Vulnerability data	NVD API v2 (NIST)
Web UI	Streamlit ≥ 1.35
HTTP client	requests
Concurrency	threading · queue (live terminal streaming)
Reports	csv · json · html (stdlib)

---

Prerequisites

Requirement	Version	Notes
Python	3.10+
Nmap	7.x+	Optional — falls back to raw sockets if absent
NVD API key	—	Optional — raises rate limit from 5 → 50 req/30 s

Install Nmap:

brew install nmap          # macOS
sudo apt install nmap      # Debian / Ubuntu
sudo dnf install nmap      # RHEL / Fedora

Get an NVD API key (free, instant approval): https://nvd.nist.gov/developers/request-an-api-key

---

Installation

# 1. Clone
git clone https://github.com/ameerrkhann/vulnscanner.git
cd vulnscanner

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

Optional — configure your NVD API key in config.py:

NVD_API_KEY = "your-key-here"   # or pass --api-key at runtime

---

CLI Usage

# Basic scan — ports 1–1024, Nmap, all severities
python vuln_scanner.py --target 192.168.1.10

# Scan a wider port range
python vuln_scanner.py --target myhost.local --ports 1-65535

# Filter to HIGH and CRITICAL CVEs only
python vuln_scanner.py --target 10.0.0.5 --severity-filter HIGH

# Use NVD API key for higher rate limits
python vuln_scanner.py --target 192.168.1.10 --api-key YOUR_KEY

# Raw socket scanner — no Nmap required
python vuln_scanner.py --target 192.168.1.10 --no-nmap

# Generate all three report formats
python vuln_scanner.py --target 192.168.1.10 --format all

# Save reports to a custom directory
python vuln_scanner.py --target 192.168.1.10 --output-dir /tmp/reports

# Compare against a previous scan (new vs. resolved CVEs)
python vuln_scanner.py --target 192.168.1.10 --compare reports/prev.json

# Verbose debug output
python vuln_scanner.py --target 192.168.1.10 --verbose

Flag Reference

Flag	Short	Default	Description
--target	-t	—	Target IP or hostname (required)
--ports	-p	1-1024	Port range, e.g. 22-443 or 1-65535
--no-nmap		off	Use raw socket scanner instead of Nmap
--severity-filter	-s	all	Minimum severity: LOW MEDIUM HIGH CRITICAL
--api-key	-k	config.py	NVD API key
--output-dir	-o	reports/	Output directory for saved reports
--format	-f	csv,html	Formats: csv html json all
--compare		—	Path to a previous JSON report for diff
--verbose	-v	off	Enable debug-level logging

Sample Output

============================================================
  VULNERABILITY SCANNER
  Target  : 192.168.1.10
  Ports   : 1-1024
  Scanner : Nmap (-sV -T4)
  Filter  : None (all severities)
  Formats : CSV, HTML
============================================================

14:21:33  INFO  Phase 1/3 — Port scanning (192.168.1.10)
14:21:45  INFO    OPEN  22/tcp   ssh   OpenSSH 8.9p1
14:21:45  INFO    OPEN  80/tcp   http  Apache httpd 2.4.52
14:21:45  INFO  Nmap scan complete — 2 open port(s) found

14:21:45  INFO  Phase 2/3 — CVE lookup for 2 service(s)
14:21:52  INFO    → 5 CVE(s) found

[RISK]  CRITICAL  (score: 48.2)  |  Ports: 2  |  CVEs: 5  (C:2 H:2 M:1 L:0)

  TOP 5 CRITICAL FINDINGS — 192.168.1.10
=========================================
   1. CVE-2022-31813   CRITICAL  9.8   port 80   [Apache httpd 2.4.52]
   2. CVE-2023-38408   CRITICAL  9.8   port 22   [OpenSSH 8.9p1]
   3. CVE-2023-28531   HIGH      8.1   port 22   [OpenSSH 8.9p1]
   ...

[+] CSV  → reports/vuln_report_192_168_1_10_20260302_142153.csv
[+] HTML → reports/vuln_report_192_168_1_10_20260302_142153.html
[✓] Scan complete.

---

Web UI

streamlit run app.py
# → Open http://localhost:8501

Enter a target in the sidebar and click ▶ Start Scan, or click ⚡ Try Demo Scan to explore the full interface with pre-loaded CVE data — no real host required.

Dashboard Tabs

Tab	Content
🛡 Findings	Colour-coded CVE table filterable by severity; clickable NVD links
🔌 Open Ports	Full port / service / version table
🏆 Top 10	Ranked top findings with CVSS scores and descriptions
📊 Compare	Upload a previous JSON report to diff new vs. resolved CVEs
📋 Scan Log	Full terminal output replay

---

Screenshots

Replace the placeholders below with actual screenshots once captured.

Welcome screen — feature cards and demo button

[screenshot: welcome-screen.png]

Live terminal feed during an active scan

[screenshot: live-terminal.png]

Results dashboard — summary cards and colour-coded findings table

[screenshot: results-dashboard.png]

Scan history in the sidebar

[screenshot: scan-history.png]

---

Project Structure

vulnscanner/
├── vuln_scanner.py          # CLI entry point (argparse)
├── app.py                   # Streamlit web dashboard
├── config.py                # API keys and default settings
├── requirements.txt
├── README.md
├── scanner/
│   ├── __init__.py          # Package exports
│   ├── port_scanner.py      # Nmap + raw socket scanning, banner grabbing
│   ├── cve_lookup.py        # NVD API v2 client, CVEResult dataclass
│   ├── risk_engine.py       # Weighted risk scoring, ranking, scan diff
│   └── report_generator.py  # CSV / HTML / JSON report generation
└── reports/                 # Generated reports (created on first run)

Scan Pipeline

Target → PortScanner     → [open ports + service identifiers]
       → CVELookup       → [CVEResult list with CVSS v3 scores]
       → RiskEngine      → [ScanResult: scored, ranked, diffable]
       → ReportGenerator → CSV · HTML · JSON

---

Ethical & Legal Disclaimer

This tool is intended for authorised security testing, educational research, and defensive use only.

Scanning systems without explicit written permission from the system owner is illegal in most jurisdictions, including under the Computer Fraud and Abuse Act (CFAA, 18 U.S.C. § 1030) in the United States, the Computer Misuse Act 1990 in the United Kingdom, and equivalent legislation worldwide.

The authors and contributors accept no liability for any misuse or damage caused by this software. By downloading or using VulnScanner you confirm that you have obtained all necessary authorisations and will comply with all applicable laws and regulations.

---

License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2026 <Your Name>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

---

_{Built with Python  ·  Powered by the NVD API}