VulnerabilityScanner

Educational Python Vulnerability Scanner Here is a complete, beautifully structured layout ready to copy and paste directly into your GitHub README.md.

This includes a clear project explanation, quick execution steps, and a showcasing of the expected outputs so that visitors (including potential employers) immediately grasp the quality and purpose of your tool.

---

Copy-Paste This Into Your GitHub README.md

# 🛡️ Defensive Web & Port Vulnerability Scanner

A lightweight, modular **educational vulnerability scanner** built in Python 3.12+. This tool is designed as a defensive security utility to conduct safe, non-destructive network configuration audits. 

It probes common TCP ports, evaluates HTTP/S response headers for missing security configurations, validates SSL certificates, checks software version banners against outdated release patterns, and exports clean, professional reports.

> **⚠️ Ethical Use Disclaimer:** This utility is strictly educational. It must only be used on systems you own or have explicit, documented authorization to test. No offensive payloads, brute-force algorithms, or exploitation tools are included.

---

## 🚀 How It Works (Core Architecture)

The project is designed with modular software engineering principles in mind, ensuring code readability and clean separation of concerns:

```text
VulnerabilityScanner/
│
├── scanner.py             # CLI Controller & application orchestrator
├── port_scanner.py        # High-performance concurrent TCP connection prober
├── banner_grabber.py      # Low-level socket reader for service identification
├── web_scanner.py         # HTTP header inspector for defense verification
├── ssl_checker.py         # Certificate details and expiration parser
├── version_checker.py     # Simple signature pattern matching against known legacy products
├── report_generator.py    # Dual text and responsive HTML5 report compilers
├── utils.py               # Shared utility functions (logging, UI formatting, target validation)
└── requirements.txt       # Minimal external package requirements

---

🛠️ Installation & Execution

1. Prerequisites

Ensure you have Python 3.12+ installed.

2. Setup the Workspace

Clone this repository and navigate into the project root:

git clone [https://github.com/YOUR_USERNAME/VulnerabilityScanner.git](https://github.com/YOUR_USERNAME/VulnerabilityScanner.git)
cd VulnerabilityScanner

3. Initialize Virtual Environment & Install Dependencies

# Create environment
python -m venv venv

# Activate on Linux/macOS
source venv/bin/activate

# Activate on Windows
.\venv\Scripts\activate

# Install requirements
pip install -r requirements.txt

4. Execute the Scan

To run the scanner in interactive CLI mode:

python scanner.py

---

🎯 Testing Locally (Safe Mock Server)

You can safely test all aspects of this tool locally without scanning live external systems:

1. In a separate terminal window, launch the mock server (which deliberately runs an older signature banner and omits essential security headers):

python mock_server.py

2. Run python scanner.py in your main terminal.
3. Enter localhost as the target when prompted.

---

📊 Expected Output & Outcomes

1. Terminal Output

Running the scan provides live, colorized status logs detailing exactly what is being audited:

============================================================
       EDUCATIONAL VULNERABILITY PORTAL & SCANNER          
   [Defensive Training Tool & System Audit Core]            
============================================================
WARNING: Run only against hosts you own or are authorized to audit.
    
Enter target domain or IP: localhost
2026-07-15 12:21:10 [INFO] Target successfully resolved to: 127.0.0.1
Confirm you possess authorization to audit localhost (127.0.0.1)? [y/N]: y

2026-07-15 12:21:11 [INFO] Starting port scan on 127.0.0.1 for 12 target ports...
2026-07-15 12:21:12 [INFO]  Found Open Port: 8080 (HTTP-ALT)
2026-07-15 12:21:13 [INFO] Checking HTTP/S security headers on: http://localhost:8080

==================================================
                 SCAN FINDINGS SUMMARY
==================================================
[HIGH] Legacy Software Detected: Apache
  Description: Port 8080 displayed the following banner: 'Apache/2.4.41'. This signature matches a known legacy software release.
  Remediation: Update APACHE to the latest stable production releases.

[MEDIUM] Missing Content-Security-Policy Header
  Description: The web application does not return the security-hardened 'Content-Security-Policy' header. Prevents cross-site scripting (XSS) and injection attacks.
  Remediation: Implement a robust Content-Security-Policy header outlining trusted script sources.

[LOW] Missing X-Frame-Options Header
  Description: The web application does not return the security-hardened 'X-Frame-Options' header. Protects users against Clickjacking attacks.
  Remediation: Configure X-Frame-Options to DENY or SAMEORIGIN.

==================================================
2026-07-15 12:21:14 [INFO] Plaintext summary exported to: reports/report.txt
2026-07-15 12:21:14 [INFO] Interactive HTML dashboard exported to: reports/report.html
2026-07-15 12:21:14 [INFO] Scan completed successfully!

2. HTML Security Dashboard Report

Upon completion, the application auto-generates a responsive HTML dashboard inside reports/report.html.

• Visual Highlights: It breaks down open ports and details vulnerabilities categorized using standard risk badges (Critical, High, Medium, Low, Info), mapping out the explicit root causes and remediation recommendations.

---

🎓 Educational Learning Objectives Met

• Network & Socket Programming: Implementing direct TCP connection handshakes and non-destructive banner grabbing.
• Defensive Web Architecture: Deep understanding of server response headers (CSP, HSTS, nosniff) designed to mitigate Client-Side injection vectors.
• Secure Transport Layer Handshakes: Programmatic analysis of SSL/TLS certificate fields and CA trust path validation.
• Clean Code Standards: Highly typed structures using Python Type Hints, structured object serialization, thread concurrency, and PEP 8 alignment.