🛡️ VulnScope

A Full-Stack Network Vulnerability Scanning Platform

Scan. Score. Report. — Built with Flask, Nmap, and SQLAlchemy.

---

📖 Overview

VulnScope is a self-hosted web application that turns raw Nmap scan output into an authenticated, per-user vulnerability management dashboard. Users register an account, launch scans against a target (host, IP, or CIDR range) with configurable probes (TCP/UDP, OS detection, service/version detection, aggressive mode), and VulnScope parses the results into structured host, port, service, and vulnerability records — cross-referencing detected services against a local CVE knowledge base to produce a security score and risk rating for every scan.

Every scan is stored in a SQL database, browsable through a searchable/filterable history page, and exportable as a PDF, HTML, or JSON report. The UI is a hand-built dark/light glassmorphism theme (no CSS framework) with a live-progress scan console and a Chart.js-powered dashboard.

This project was built as a final-year BCA project to demonstrate applied, hands-on security engineering: safe use of an OS-level scanning tool from a web backend, input validation against command-injection, session/CSRF hardening, and a clean service-layer architecture — rather than just a CRUD app with security features bolted on.

---

✨ Key Features

• 🔍 Real network scanning — wraps the actual nmap binary via python-nmap, not a simulated/mocked scanner
• ⚙️ Configurable scan profiles — toggle TCP connect scan, UDP scan, OS fingerprinting, service/version detection, and aggressive (-A) mode per scan
• 🧠 Local vulnerability knowledge base — detected services (Apache, SSH, FTP, MySQL, Redis, HTTP/S, SMTP) are mapped to known CVEs with CVSS scores, severity, and remediation advice
• 📊 Automated risk scoring — every scan is reduced to a 0–100 security score and a Low/Medium/High/Critical risk level based on open ports, vulnerability count, OS exposure, and critical service presence
• 📈 Interactive dashboard — Chart.js visualization of severity distribution across recent scans, plus recent activity and recent vulnerability feeds
• 🕘 Scan history with filtering — search by target/hostname/IP, and filter by severity, date, or protocol
• 📄 Multi-format reporting — generate and download PDF (ReportLab), HTML, or JSON reports per scan, with ownership-checked downloads
• 🌗 Persisted dark/light theme — theme choice is saved per user account and rendered server-side on first paint (no flash of unstyled theme)
• 🔐 Authenticated, per-user data isolation — every scan, report, and setting is scoped to the signed-in account via Flask-Login
• 🛡️ Security-conscious by design — see Security Disclaimer below for the specifics

---

🧰 Technology Stack

Layer	Technology
Backend Framework	Flask 3 (application-factory pattern, Blueprints)
ORM / Database	SQLAlchemy 2 · SQLite (default, swappable via DATABASE_URL)
Authentication	Flask-Login (session-based), Werkzeug password hashing
Security Middleware	Flask-WTF (CSRF protection), Flask-Cors (origin allow-listing), limits (rate limiting)
Scan Engine	python-nmap (wraps the system nmap binary)
Report Generation	ReportLab (PDF), native HTML/JSON writers
Frontend	Jinja2 templates, hand-written CSS (custom dark/light glassmorphism design system), vanilla JavaScript
Data Visualization	Chart.js (loaded via CDN)
Configuration	python-dotenv (.env-based config)

---

🏗️ Project Architecture

VulnScope follows a layered Flask application-factory architecture that separates HTTP routing, business logic, and data access:

                ┌─────────────────────────┐
                │   Browser (Jinja2 UI)   │
                │  templates + CSS + JS   │
                └────────────┬────────────┘
                             │ HTTP / fetch (CSRF-protected)
                ┌────────────▼────────────┐
                │   Blueprints (Routes)   │
                │  main · auth · api      │
                └────────────┬────────────┘
                             │
                ┌────────────▼────────────┐
                │     Service Layer       │
                │  ScanEngine · rate_limit│
                └────────────┬────────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
     ┌────────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐
     │  nmap binary   │ │ SQLAlchemy │ │  ReportLab  │
     │ (subprocess)   │ │  (SQLite)  │ │ (PDF/HTML)  │
     └────────────────┘ └────────────┘ └────────────┘

Design highlights:

• create_app() factory (app/__init__.py) wires up config, CSRF, CORS, the SQLAlchemy engine, and blueprint registration in one place, and self-heals the SQLite schema (ensure_schema) so existing databases pick up new columns without a manual migration step.
• ScanEngine (app/services/scan_engine.py) is the single point of contact with nmap. It validates the scan target against an allow-list regex before it ever reaches a subprocess call, builds the correct nmap argument set from the requested options, gracefully falls back to a safer scan if the primary one fails, and normalizes raw nmap XML output into Port, Service, and Vulnerability rows.
• Blueprints (main, auth, api) keep page rendering, authentication, and the JSON API cleanly separated.
• rate_limit.py wraps the limits package into a one-line is_rate_limited() helper used to throttle login/register attempts.

---

📁 Folder Structure

VulnScope/
├── app/
│   ├── __init__.py            # Application factory, config, schema bootstrap
│   ├── database/
│   │   └── models.py          # SQLAlchemy models: User, Scan, Port, Service,
│   │                           #   Vulnerability, Report, Setting
│   ├── routes/
│   │   ├── main.py            # Page routes: dashboard, history, reports, settings
│   │   ├── auth.py            # Login, register, logout (rate-limited)
│   │   └── api.py             # JSON API: /api/scan, /api/history, /api/report, ...
│   ├── services/
│   │   ├── scan_engine.py     # Nmap orchestration, parsing, scoring, exports
│   │   └── rate_limit.py      # Login/register brute-force throttling
│   ├── static/
│   │   ├── css/style.css      # Dark/light design system
│   │   └── js/app.js          # Scan console, dashboard charts, settings sync
│   └── templates/             # Jinja2 templates (landing, dashboard, new_scan,
│                                #   history, reports, settings, about, 404, ...)
├── screenshots/                # App screenshots used in this README
├── reports/                    # Generated PDF/HTML/JSON reports (per scan)
├── instance/                   # SQLite database (created at runtime)
├── app.py                      # Entry point
├── requirements.txt
├── .env.example
└── README.md

---

🚀 Installation Guide

Prerequisites

• Python 3.10+
• The nmap command-line tool installed on the host OS. python-nmap is a wrapper around the real nmap binary — it does not bundle it.
  • Debian/Ubuntu: sudo apt install nmap
  • macOS (Homebrew): brew install nmap
  • Windows: install from nmap.org/download.html and ensure nmap.exe is on your PATH. Also install Npcap alongside it — the official Windows installer offers this by default; without it, nmap can exit "successfully" while returning no scan data.
• Some scan options (OS detection, aggressive -A mode) need raw-socket access and may require elevated/administrator privileges — otherwise VulnScope automatically falls back to a safer TCP-connect scan.

Setup

# 1. Clone the repository
git clone https://github.com/gokulkrishnan-s/VulnScope.git
cd VulnScope

# 2. (Recommended) create a virtual environment
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate

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

# 4. Configure environment variables
cp .env.example .env
# then open .env and set SECRET_KEY, e.g.:
python -c "import secrets; print(secrets.token_hex(32))"

# 5. Run the app
python app.py

The app starts at http://127.0.0.1:5000 by default (configurable via FLASK_HOST / FLASK_PORT in .env).

---

🖥️ Usage Instructions

1. Register an account from the landing page, then log in.
2. Start a scan — go to New Scan, enter a target (IP, hostname, or CIDR), choose which probes to run (TCP, UDP, OS detection, version/service detection, aggressive mode), and hit Start. The scan console shows a live progress bar and timeline while the scan runs server-side.
3. Review results — open ports, detected services, and any matched CVEs (with CVSS score and remediation advice) appear in the results panel as soon as the scan completes.
4. Check the Dashboard — see your total scan count, severity distribution chart, recent activity, and recently discovered vulnerabilities at a glance.
5. Browse History — search past scans by target/hostname/IP, or filter by severity, date, or protocol; delete scans you no longer need.
6. Generate Reports — from History or the Reports page, export any scan as a PDF, HTML, or JSON file and download it directly.
7. Adjust Settings — switch between dark/light theme, set your default export format, and toggle notifications. Preferences are saved per account.

---

📸 Screenshots

Screenshots live in the /screenshots folder. Add your own PNGs there with the file names below and they'll render automatically on GitHub.

Dashboard	New Scan

Scan History	Reports

---

🔭 Future Improvements

• Integrate a live CVE feed (e.g. the NVD API) instead of the static local knowledge base
• Move scan execution to a background task queue (Celery/RQ) for long-running or scheduled scans
• Real-time scan progress via WebSockets instead of a client-side estimated progress bar
• Redis-backed rate limiting for multi-worker/production deployments (the current in-memory limiter is per-process, by design, for single-instance use)
• Role-based access control for team/multi-analyst usage
• Dockerfile and docker-compose setup for one-command deployment
• Automated test suite and CI pipeline

---

⚠️ Security & Disclaimer

VulnScope is built with security-conscious defaults, including:

• Command-injection-safe target validation — scan targets are checked against a strict allow-list pattern before ever being passed to nmap, rejecting flag-injection and shell metacharacters.
• CSRF protection on all state-changing requests (Flask-WTF).
• Rate-limited authentication — login and registration are throttled per client IP to slow brute-force attempts.
• Hardened sessions — HttpOnly and SameSite=Lax cookies by default, with Secure cookies configurable for production over HTTPS.
• No hardcoded secret key — if SECRET_KEY isn't set, a random ephemeral key is generated per process (with a warning) rather than falling back to a static default.
• Explicit CORS origin allow-listing for the /api/* routes instead of a wildcard origin.
• Per-user data isolation — scans, reports, and settings are always scoped to current_user, and report downloads verify ownership before serving a file.

That said: this tool actively probes network hosts using Nmap. Only scan systems and networks you own or have explicit, written authorization to test. Unauthorized scanning of third-party systems may violate the law (e.g. the U.S. Computer Fraud and Abuse Act, the UK Computer Misuse Act, and equivalent laws elsewhere) and the acceptable-use policies of most networks and cloud providers. This project is intended for educational use, personal lab environments, and authorized security assessments only. The author assumes no liability for misuse.

---

👤 Author

Gokul Krishnan S Final-year BCA student focused on offensive security & web application security

• GitHub: @gokulkrishnan-s

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.