██╗   ██╗██╗   ██╗██╗     ███╗   ██╗███████╗ ██████╗ ██████╗ ██╗   ██╗████████╗
██║   ██║██║   ██║██║     ████╗  ██║██╔════╝██╔════╝██╔═══██╗██║   ██║╚══██╔══╝
██║   ██║██║   ██║██║     ██╔██╗ ██║███████╗██║     ██║   ██║██║   ██║   ██║
╚██╗ ██╔╝██║   ██║██║     ██║╚██╗██║╚════██║██║     ██║   ██║██║   ██║   ██║
 ╚████╔╝ ╚██████╔╝███████╗██║ ╚████║███████║╚██████╗╚██████╔╝╚██████╔╝   ██║
  ╚═══╝   ╚═════╝ ╚══════╝╚═╝  ╚═══╝╚══════╝ ╚═════╝ ╚═════╝  ╚═════╝    ╚═╝

• Why Vulnerability Scanning Matters
• What Is VulnScout?
• Features
• What Happens During a Scan
• Architecture Overview
• Installation
• Usage
  • Interactive Mode
  • Command-Line Mode
  • Scan Modes Compared
• Understanding the Results
• Sample Report
• Project Structure
• How Each Module Works
• Technologies Used
• Legal Disclaimer
• Contributing
• Author
• License

Services listening on open ports are the attack surface. An unpatched Apache or a forgotten Telnet daemon can be the way in. Vulnerability scanning finds those open ports, identifies what's running, and checks if any of it has known CVEs. That's what VulnScout does.

The process breaks down into four steps:

1. Discovers what ports are open on a target system (the attack surface)
2. Identifies what software and version is running behind each port
3. Cross-references those versions against databases of known vulnerabilities
4. Reports findings with severity ratings and remediation guidance

I built VulnScout as a network vulnerability scanner in Python. It follows the same four-phase methodology that commercial scanners use — port discovery, service fingerprinting, vulnerability correlation, and report generation — but I wrote every phase in clean, commented code you can actually read through.

What it does:

1. Scans a target for open TCP ports across configurable port ranges (20, 100, or 1024 ports)
2. Identifies services and their versions through banner grabbing and regex-based fingerprinting
3. Checks discovered services against the NIST National Vulnerability Database (NVD) API and a curated offline CVE database
4. Generates both styled HTML reports and clean text reports with executive summaries, detailed findings, and remediation recommendations

Every networked computer has 65,535 TCP ports — think of them as individual doors into the machine. When a service like Apache or SSH starts up, it binds to a port and listens for connections. VulnScout attempts a TCP connection to each port in the selected range; if the three-way handshake completes, the port is open and something is listening.

Knowing a port is open isn't enough — you need to know what's running and what version it is. Most services introduce themselves when you connect: SSH sends SSH-2.0-OpenSSH_8.2p1, FTP sends 220 ProFTPD 1.3.5 Server ready, HTTP includes a Server: Apache/2.4.49 header. VulnScout reads these banners, parses them with regex, and extracts the service name and version number.

Each identified service gets checked against the NIST National Vulnerability Database and a curated offline database. If VulnScout finds "OpenSSH 8.2" on port 22, it pulls every CVE that matches. Each CVE carries a CVSS severity score:

VulnScout generates a styled HTML report with a colour-coded dashboard and severity badges, plus a clean text report with structured sections. Both include an executive summary, detailed findings per CVE, and remediation recommendations.

+-----------------------------------------------------------+
|                    VulnScout Workflow                      |
+-----------------------------------------------------------+
|                                                           |
|   [1] TARGET VALIDATION                                   |
|        |  Verify IP address or resolve hostname via DNS   |
|        |  Classify as private/internal or public           |
|        v                                                  |
|   [2] PORT SCANNING                (scanner.py)           |
|        |  TCP connect scan across selected port range     |
|        |  Multi-threaded: up to 100 concurrent threads    |
|        |  Configurable 1.5-second timeout per port        |
|        v                                                  |
|   [3] SERVICE DETECTION        (service_detector.py)      |
|        |  Banner grab on each open port (3s timeout)      |
|        |  HTTP HEAD probe for web ports without banners   |
|        |  Regex matching against 17+ service patterns     |
|        |  Port-based fallback identification              |
|        v                                                  |
|   [4] VULNERABILITY CHECK        (vuln_checker.py)        |
|        |  Query NIST NVD v2.0 API (keyword search)        |
|        |  Check curated offline database (13 services)    |
|        |  Merge results and deduplicate by CVE ID         |
|        |  Sort by CVSS severity (highest first)           |
|        |  Classify into CRITICAL/HIGH/MEDIUM/LOW          |
|        v                                                  |
|   [5] REPORT GENERATION        (report_generator.py)      |
|        |  Colour-coded terminal summary                   |
|        |  Styled HTML report with dashboard               |
|        |  Clean text report with executive summary         |
|        v                                                  |
|   [DONE] Reports saved to /reports directory              |
|                                                           |
+-----------------------------------------------------------+

• Python 3.8 or higher -- Download Python
• pip -- Python's package manager (included with Python)

# Clone the repository
git clone https://github.com/OMALICHAC/VulnScout-Network-Vulnerability-Scanner.git

# Navigate into the project directory
cd VulnScout-Network-Vulnerability-Scanner

# (Recommended) Create and activate a virtual environment
python -m venv venv
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate         # Windows

# Install dependencies
pip install -r requirements.txt

VulnScout relies on only 3 external packages. Everything else uses Python's standard library.

All three are optional in a degraded sense -- VulnScout checks for their presence at import time and falls back gracefully if any are missing. The core scanning logic uses only built-in modules (socket, threading, ipaddress, re, argparse, json, os, datetime).

Run the tool with no arguments to launch the guided menu:

python vulnscout.py

You will see:

╔══════════════════════════════════════╗
║          MAIN MENU                   ║
╠══════════════════════════════════════╣
║  1. Quick Scan    (Top 20 ports)     ║
║  2. Standard Scan (Top 100 ports)    ║
║  3. Full Scan     (1024 ports)       ║
║  4. Help / How to Use                ║
║  5. Exit                             ║
╚══════════════════════════════════════╝

Enter your choice (1-5): 1
Enter target IP or hostname: 192.168.1.1
Save reports? (y/n, default: y): y
Use online CVE lookup? (y/n, default: y): y

The tool walks you through target entry, scan mode selection, report saving, and API usage. No flags to memorise, no syntax to look up.

For scripted or repeatable workflows:

# Quick scan on a local target
python vulnscout.py --target 192.168.1.1 --quick

# Standard scan with report generation
python vulnscout.py --target 192.168.1.1 --standard --report

# Full scan, offline only (no NVD API calls)
python vulnscout.py --target 10.0.0.1 --full --report --no-api

# Scan a hostname
python vulnscout.py --target scanme.nmap.org --quick --report

# Display usage help
python vulnscout.py --help

Scan mode flags (--quick, --standard, --full) are mutually exclusive -- argparse enforces that only one can be used per invocation. If none is specified, the default is quick.

  SCAN RESULTS SUMMARY
============================================================

  Target:        192.168.1.1
  Scan Mode:     QUICK
  Duration:      4.32 seconds
  Ports Scanned: 20
  Open Ports:    3

  Port     Service                Version        Risk
  ──────── ────────────────────── ────────────── ────────────
  22       OpenSSH                8.2            HIGH
  80       Apache HTTP Server     2.4.49         HIGH
  443      HTTPS                  Unknown        N/A

  ──────────────────────────────────────────────────────

  Vulnerabilities Found: 4
    Critical: 1
    High:     2
    Medium:   1

  Top Findings:

    CVE-2023-38408 (CVSS: 9.8)
      Port 22 — OpenSSH
      Remote code execution via ssh-agent forwarding...

    CVE-2024-6387 (CVSS: 8.1)
      Port 22 — OpenSSH
      RegreSSHion: Remote code execution vulnerability...

VulnScout generates HTML reports viewable in any browser and text reports for archival. Each report includes scan information, an executive summary with severity breakdown, detailed findings per CVE with remediation steps, and general hardening recommendations. A sample report is included in the sample_reports/ directory — open the .html file in a browser to see the styled version.

VulnScout-Network-Vulnerability-Scanner/
|
|-- vulnscout.py            # Main entry point and orchestrator
|                            # Interactive menu, CLI argument parsing,
|                            # five-step scan workflow coordination,
|                            # colour-coded terminal output
|
|-- scanner.py              # Port scanning engine
|                            # TCP connect scan with socket library,
|                            # multi-threaded execution (up to 100 threads),
|                            # port list definitions (TOP_20, TOP_100, 1-1024),
|                            # port-to-service-name lookup dictionary
|
|-- service_detector.py     # Service identification engine
|                            # Banner grabbing over TCP sockets,
|                            # HTTP HEAD probing for web ports,
|                            # 17+ regex patterns for fingerprinting,
|                            # port-based fallback identification
|
|-- vuln_checker.py         # Vulnerability correlation engine
|                            # NIST NVD v2.0 REST API integration,
|                            # curated offline database (13 services, 20+ CVEs),
|                            # CVSS v3.1/v3.0/v2.0 score extraction,
|                            # severity classification and summary generation
|
|-- report_generator.py     # Report generation engine
|                            # Styled HTML report with CSS grid dashboard,
|                            # plaintext report with structured sections,
|                            # timestamped filename generation,
|                            # executive summary and recommendations
|
|-- requirements.txt        # Python package dependencies (3 packages)
|-- LICENSE                 # MIT License
|-- .gitignore              # Git ignore rules
|-- README.md               # This documentation
|
|-- sample_reports/          # Pre-generated example reports
|   |-- *.html              # Sample HTML report (browser-viewable)
|   |-- *.txt               # Sample text report
|
|-- reports/                 # Scan output directory (created at runtime)

vulnscout.py is the entry point. It handles both CLI argument parsing (via argparse with mutually exclusive scan mode flags) and the interactive menu. When a scan kicks off, run_full_scan() orchestrates the five-step workflow: validate target, scan ports, detect services, check vulnerabilities, and generate reports. Imports for colorama and tqdm are wrapped in try/except so VulnScout runs fine on a bare Python install — it just loses the visual polish.

scanner.py runs the TCP connect scan. Each port gets its own thread (capped at 100 concurrent), and each thread calls socket.connect_ex() with a 1.5-second timeout. connect_ex() returns 0 if the handshake completed (port open) or an error code otherwise — cleaner than catching exceptions when most ports will be closed. A threading lock protects the shared results list.

service_detector.py does banner grabbing and fingerprinting. It connects to each open port, reads whatever the service sends back (SSH and FTP announce themselves immediately), and for web ports that stay silent, sends an HTTP HEAD request to get the Server: header. The banner text runs through 17+ compiled regex patterns to extract service name and version. If nothing matches, a port-based lookup dictionary provides a best-guess fallback.

vuln_checker.py takes the identified services and finds known CVEs. It always checks the curated offline database first (covering 13 service families and 20+ high-impact CVEs), then optionally queries the NIST NVD v2.0 API with a keyword search like "OpenSSH 8.2". Results from both sources get merged and deduplicated by CVE ID, then sorted by CVSS severity (highest first). A 3-second delay between API calls respects the NVD rate limit.

report_generator.py turns the raw scan data into deliverable reports. The HTML report is a complete HTML5 document with embedded CSS — grid-based dashboard, gradient header, colour-coded severity badges — no external frameworks needed. The text report follows standard pentest report structure with sections for scan info, executive summary, findings, and recommendations. Filenames are timestamped to avoid overwriting previous scans.

Plus Python standard library modules (socket, threading, ipaddress, argparse, re, json, os, datetime, time).

For EDUCATIONAL PURPOSES and AUTHORIZED SECURITY TESTING only.

Only scan networks and systems you own or have explicit written permission to test. Unauthorized scanning is illegal in most jurisdictions. I assume no liability for misuse.

Safe targets for practice:

• 127.0.0.1 -- Your own machine
• scanme.nmap.org -- Provided by the Nmap Project for scanner testing
• Your own home network (e.g., 192.168.1.0/24)
• Intentionally vulnerable labs (Metasploitable, DVWA, HackTheBox, TryHackMe)

Contributions are welcome. Here is how to get started:

1. Fork this repository
2. Create a feature branch (git checkout -b feature/your-feature-name)
3. Commit your changes (git commit -m "Add your feature")
4. Push to the branch (git push origin feature/your-feature-name)
5. Open a Pull Request

• Add UDP scanning support (DNS, SNMP, DHCP)
• Expand the offline vulnerability database with additional services and CVEs
• Add CIDR notation support for scanning entire subnets
• Build a web-based dashboard for viewing historical scan results

Chioma Iroka Computer Science Graduate | Cybersecurity Focus

• GitHub: github.com/ChiomaIroka