🛡️ CVE Scanner — Vulnerability Detection System

BCA Year 3 Project | SOC L1 Portfolio Project

A Python-based vulnerability detection tool that scans a target host for open ports and services, then cross-references findings against the National Vulnerability Database (NVD) to surface real CVEs — complete with severity scoring and a live web dashboard.

---

📸 Dashboard Preview

---

📁 Project Structure

File	Purpose
app.py	Flask web server — routes and API endpoints
scanner.py	Nmap-based port and service scanner
cve_lookup.py	NVD API integration for CVE lookup
database.py	SQLite database — stores scans and CVE results
reporter.py	PDF & CSV export report generator
view_data.py	Terminal viewer for past scans and CVE results
tests/	Pytest suite — 65 unit tests
requirements.txt	Python dependencies

---

🔍 How It Works

1. Takes a target IP or hostname as input
2. Runs an Nmap -sV scan to detect open ports and service versions
3. Queries the NVD (National Vulnerability Database) API for known CVEs matching each detected service
4. Displays results on a live dashboard with severity scoring — CRITICAL / HIGH / MEDIUM / LOW
5. Stores all scan history in SQLite for later review and export

---

⚙️ Setup

Step 1 — Install Python dependencies

pip install -r requirements.txt

Step 2 — Install Nmap

Download from: https://nmap.org/download.html

⚠️ Make sure to add Nmap to your system PATH during installation.

Step 3 — Configure environment variables (optional, recommended)

Create a .env file in the root directory:

NVD_API_KEY=your_nvd_api_key_here
CVE_DB_PATH=cve_scanner.db

• NVD_API_KEY — speeds up NVD querying 10x (reduces the rate-limit delay from 6.0s to 0.6s per service lookup). Strongly recommended if you're scanning hosts with more than a couple of open services.
• CVE_DB_PATH — sets a custom path/name for the SQLite database. Defaults to cve_scanner.db if unset.

---

▶️ Running the App

Option A — Web Dashboard

Start the Flask web server:

python app.py

Then open your browser and go to:

http://127.0.0.1:5000

Enter a target IP (e.g. 127.0.0.1 or scanme.nmap.org) and click Run Scan.

Option B — Terminal Viewer

To quickly review all past scans and correlated CVEs without opening the dashboard:

python view_data.py

---

🧪 Testing

Run the full test suite (65 tests):

pytest tests/ -v

Tests are also run automatically on every push via GitHub Actions CI.

---

🧰 Tech Stack

Layer	Technology
Web Server	Python + Flask
Port & Service Detection	Nmap + python-nmap
CVE Data	NVD API (NIST)
Storage	SQLite
Reporting	ReportLab (PDF) + CSV
Frontend	HTML / CSS / JavaScript + Chart.js
CI/CD	GitHub Actions

---

🖥️ Dashboard Features

Feature	Detail
Severity Summary	CRITICAL / HIGH / MEDIUM / LOW counts at a glance
CVE Results Table	CVE ID, affected port, CVSS score, and description
Interactive Doughnut Chart	Click a severity segment to filter the results table
Scan History	All past scans with target, service count, and CVE count
CVE Database	Searchable global table of all stored CVEs across all scans
PDF & CSV Export	Download styled vulnerability reports per scan
Settings Panel	Configure NVD API key directly from the dashboard
Dark Mode	Toggle light/dark theme with persistent preference

---

⚠️ Legal Notice

Only scan systems you own or have explicit written permission to scan.

Unauthorized port scanning and vulnerability enumeration may be illegal under the Computer Fraud and Abuse Act (CFAA) and equivalent laws in other jurisdictions. The author assumes no liability for misuse of this tool.

---

📌 Known Limitations

• CVE matching is based on service name/version string correlation with NVD and may produce false positives or miss CVEs where banner versioning is inaccurate or suppressed.
• Without an NVD_API_KEY, scans against hosts with many services will be slow due to NVD's public rate limit.
• Nmap must be installed and reachable via PATH; the tool does not bundle Nmap.

---

📄 License

This project is licensed under the MIT License.