sanidhya19/Port-Scanner-Vulnerability-Assessment

# Port Scanner A multithreaded TCP/UDP port scanner with service fingerprinting, CVE lookup, and HTML reporting — built in Python using only the standard library. ##  ## Features - **Multithreaded TCP scanning** — up to 100 concurrent connections using `ThreadPoolExecutor` - **UDP scanning** — protocol-specific probes for DNS, NTP, SNMP, NetBIOS and more - **Banner grabbing** — reads service banners to fingerprint SSH, HTTP, FTP, SMTP, MySQL, Redis, and more - **CVE lookup** — queries the NIST NVD API to find known vulnerabilities for each detected service version - **HTML report** — dark-mode report with open ports, banners, severity-rated CVEs, and clickable NVD links - **JSON export** — machine-readable output for scripting or further analysis - **Flexible port input** — ranges (`1-1024`), lists (`22,80,443`), or presets (`common`) ## Project Structure port_scanner/ ├── port_scanner.py # Core scanner — TCP/UDP scanning, CLI, orchestration ├── report.py # HTML report generator ├── cve_lookup.py # NIST NVD CVE lookup and service fingerprinting └── README.md ## Requirements - Python 3.10+ - No third-party dependencies — uses only the Python standard library ## Installation git clone https://github.com/sanidhya19/Port-Scanner-Vulnerability-Assessment.git cd port-scanner That's it. No `pip install` needed. ## Usage ### Basic TCP scan python3 port_scanner.py -p ### Examples # Scan common ports on localhost python3 port_scanner.py 127.0.0.1 # Scan a port range and save an HTML report python3 port_scanner.py 192.168.56.101 -p 1-9999 --html report.html # Scan specific ports with CVE lookup python3 port_scanner.py 192.168.56.101 -p 22,80,443,3306 --cve --html report.html # TCP + UDP scan with full reporting sudo python3 port_scanner.py 192.168.56.101 -p 1-9999 --udp --cve --html report.html # Fast scan — no banner grabbing, more threads python3 port_scanner.py 192.168.56.101 -p 1-65535 --threads 200 --no-banner --timeout 0.5 # Save results as JSON python3 port_scanner.py 192.168.56.101 -p common -o results.json ### All options | Flag | Default | Description | |------|---------|-------------| | `target` | required | Hostname or IP address | | `-p`, `--ports` | `common` | Ports to scan: `80`, `1-1024`, `22,80,443`, or `common` | | `-t`, `--threads` | `100` | Number of concurrent threads | | `--timeout` | `1.0` | Socket timeout in seconds | | `--no-banner` | off | Skip banner grabbing (faster) | | `--udp` | off | Also scan common UDP ports (requires sudo) | | `--udp-ports` | `common-udp` | UDP ports to scan: `53,123,161` or `common-udp` | | `--cve` | off | Look up CVEs via NIST NVD API | | `--api-key` | none | NVD API key for higher rate limits | | `-o`, `--output` | none | Save JSON report | | `--html` | none | Save HTML report | ## How It Works ### TCP scanning Each port is checked by attempting a full TCP three-way handshake using `socket.create_connection()`. A completed handshake means the port is open. A `ConnectionRefusedError` means closed. A timeout means filtered — a firewall is silently dropping packets. ### UDP scanning UDP has no handshake, so detection works differently. The scanner sends protocol-specific probe bytes (a real DNS query to port 53, a real NTP request to port 123, etc.) and listens for a response. A response means open. An ICMP "port unreachable" message means closed. Silence means `open|filtered` — we can't tell without more context. ### Banner grabbing ### CVE lookup The extracted version string is sent to the [NIST NVD API](https://nvd.nist.gov/developers/vulnerabilities). Results are sorted by CVSS score and displayed with severity ratings (CRITICAL / HIGH / MEDIUM / LOW). The scanner respects NVD's rate limit of 5 requests per 30 seconds automatically. ## Legal Only scan hosts you own or have explicit written permission to test. Unauthorised port scanning may violate the Computer Fraud and Abuse Act (US), the Computer Misuse Act (UK), or equivalent laws in your jurisdiction. Safe targets for practice: - `127.0.0.1` — your own machine - `scanme.nmap.org` — Nmap's public test host, scanning explicitly permitted - Your own VPS or home network - Intentionally vulnerable VMs such as [Metasploitable](https://sourceforge.net/projects/metasploitable/) running locally ## Tested Against - `scanme.nmap.org` — Nmap's public sandbox - Metasploitable 2 — intentionally vulnerable VM running in an isolated VirtualBox host-only network ## Running Tests The project includes 41 unit tests covering the core scanner logic, banner parsing, UDP scanning, and CVE lookup. Install pytest (one-time): pip3 install pytest Run the tests: python3 -m pytest tests.py -v Or without pytest: python3 tests.py ### What is tested | Test Class | What it covers | |------------|---------------| | `TestParsePorts` | Port ranges, lists, duplicates, whitespace, `common` preset | | `TestGetServiceName` | Known ports, unknown ports, SSH, HTTP | | `TestGrabBanner` | Connection failure, banner length cap, first-line extraction, HTTP probe | | `TestScanPort` | Closed port returns None, open port returns correct dict, no banner when skipped | | `TestScanUdpPort` | ICMP unreachable, timeout → `open\|filtered`, response → `open` | | `TestBuildKeyword` | Banner parsing for SSH, Apache, nginx, MySQL, Redis, FTP | | `TestParseCve` | CVE ID, score, severity, year, description trimming, missing metrics | ## Possible Extensions - OS detection via TTL analysis - HTML report light/dark mode toggle - CSV export - Scan comparison — diff two reports to spot new open ports - Scheduled scanning with change alerts