<10s
1,000 ports
scan time
scan time
500
Max concurrent
workers
workers
20+
Unit & integration
tests
tests
85%
Code
coverage
coverage
01. Project Overview
What started as a simple Python exercise — "can I scan ports concurrently?" — grew into a multi-threaded network security scanner with service fingerprinting, vulnerability detection, CVE intelligence from NVD, geolocation via IPinfo.io, and structured JSON reporting. Each version was a deliberate learning step, not just feature addition.
The goal was never to replace Nmap. It was to understand what Nmap actually does under the hood — TCP handshakes, banner grabbing, service identification, timeout handling — by building the equivalent from scratch in Python.
02. Development Journey
PHASE 01 — Proof of Concept
Basic socket scanning — TCP connections, banner grabbing
The first version was a tight loop: open a socket, connect to a port, capture whatever text the service sends back (the banner), close. No concurrency, no intelligence — just understanding that a TCP connection is a handshake, and that most services announce themselves.
# Core concept: banner grab on open ports
import socket
def probe_port(host, port, timeout=1.0):
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
s.settimeout(timeout)
if s.connect_ex((host, port)) == 0:
try:
s.send(b'HEAD / HTTP/1.0\r\n\r\n')
return s.recv(1024).decode(errors='ignore')
except:
return "open"
return None
PHASE 02 — Threading for Speed
ThreadPoolExecutor — 200x speed improvement
Sequential socket connections are I/O-bound — most of the time is spent waiting for timeouts. The fix:
concurrent.futures.ThreadPoolExecutor with up to 500 workers, turning a 90-second scan into under 10 seconds for 1,000 ports.from concurrent.futures import ThreadPoolExecutor, as_completed
def scan(host, ports, workers=200):
results = {}
with ThreadPoolExecutor(max_workers=workers) as executor:
futures = {executor.submit(probe_port, host, p): p for p in ports}
for future in as_completed(futures):
port = futures[future]
result = future.result()
if result:
results[port] = result
return results
PHASE 03 — API Integration
Geolocation via IPinfo.io + vulnerability flagging
Added IPinfo.io lookup to contextualise discovered hosts with geolocation, ISP, and network ownership. Added a local vulnerability database flagging dangerous open ports: Telnet (23), SMB (445), RDP (3389), FTP (21), and detection of outdated service versions from banner data.
PHASE 04 — Modular Architecture
Class-based design — five distinct modules
Refactored from a monolithic script into a clean class hierarchy. Each module has a single responsibility and is independently testable.
PortScanner— concurrent scanning, timeout managementVulnerabilityDetector— severity-rated rule matchingCVEProvider— NVD API v2.0 with 7-day TTL cacheGeolocationLookup— IPinfo.io integrationReportGenerator— structured JSON output
03. Version 2.0 — CVE Intelligence
The major upgrade: real-time CVE lookups from the NVD API, so detected services are cross-referenced against known vulnerability data.
5.6×
Faster than v1.0
(45s → 8s)
(45s → 8s)
44%
Memory reduction
(80MB → 45MB)
(80MB → 45MB)
67%
Fewer false positives
(15% → 5%)
(15% → 5%)
95%
API cache
hit rate
hit rate
- NVD API v2.0 integration with CVSS scoring (LOW / MEDIUM / HIGH / CRITICAL)
- 7-day TTL cache for CVE data — avoids repeated API calls for the same services
- CWE IDs, affected products, and reference links included in JSON reports
- Real-time
tqdmprogress bars with live port count - Multi-level logging: DEBUG / INFO / WARNING / ERROR via Python's logging module
04. Quick Start
git clone https://github.com/karim871/cybersecurity-audit-tool.git cd cybersecurity-audit-tool python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt # Basic scan (always test on localhost first) python src/main.py 127.0.0.1 -p 1-1000 # Fast scan with 500 workers + verbose output python src/main.py 127.0.0.1 -p 1-1000 -w 500 -v # Full scan with CVE intelligence + JSON report python src/main.py 127.0.0.1 -p 1-65535 --enable-cve -o reports/scan.json # Common vulnerable services audit python src/main.py 127.0.0.1 -p 21,22,23,25,445,3389 -v
05. What This Project Taught
TECHNICAL SKILLS
Concurrent programming with ThreadPoolExecutor
TCP/IP socket programming at the syscall level
RESTful API integration & rate limiting
JSON parsing and structured report generation
Class-based architecture for testability
Unit & integration testing with pytest
SECURITY CONCEPTS
Port scanning methodology
Service fingerprinting via banner grabbing
Vulnerability assessment and CVSS scoring
CVE correlation and threat intelligence
Ethical use boundaries for security tools
False positive reduction techniques
06. Legal Notice
AUTHORIZED USE ONLY
This tool is for educational purposes and authorized security testing. Only scan systems you own or have explicit written permission to test. Unauthorized network scanning is illegal in most jurisdictions. Safe testing: localhost (127.0.0.1), your own VMs, HackTheBox / TryHackMe labs, and explicitly permitted targets like scanme.nmap.org.