How janidu-dm/net_scanner works
Project type and purpose
• This is a Python-based command-line network scanner utility (net_scn.py) whose purpose is to discover live hosts on the local network, collect their IP/MAC addresses, look up their vendor details (either via a local CSV file or an online API), and render the results in a human-readable table.
File structure
• Top-level files:
– net_scn.py: orchestrator script containing CLI, scanning logic, vendor lookup logic, and output formatting.
– mac-vendors-export.csv: static dataset for “fast” (offline) vendor lookups.
– query/ : likely a package or module that encapsulates calls to the external MAC lookup API.
• Config/build/deployment files (.gitattributes, LICENSE, README.md) are present but do not affect runtime architecture.
README for additional insights
• Two scan modes:
– Fast Scan (local CSV lookup)
– Advanced Scan (one-second-throttled API calls via the external service)
• Dependencies: scapy (for ARP scanning), requests (for API calls), psutil/socket/ipaddress (for interface detection), pyfiglet (optional UI flourish), csv/time.
Main components
a. User Interface (CLI)
– Accepts user input (mode selection, exit).
– Displays prompts and renders final results.
b. Network Discovery Engine
– Uses scapy (ARP requests) plus psutil/socket/ipaddress to enumerate local IP range and detect live hosts.
c. Vendor Lookup Engine
– Local Lookup Module
• Reads mac-vendors-export.csv using the csv library.
– Remote API Module (query/)
• Issues HTTP requests via requests.
• Honors the API rate limit (time.sleep to enforce 1s interval).
d. Data Stores & External Services
– Local Dataset: mac-vendors-export.csv
– External MAC Vendor API (over HTTP/HTTPS)
e. Output Formatter
– Formats and prints a table of IP, MAC, Vendor.
– Optionally uses pyfiglet for headers/styling.
Interactions and data flows
1. User runs “python net_scn.py” → CLI component starts.
2. CLI queries user for scan mode selection.
3. CLI invokes Network Discovery Engine:
• Scans IP range → returns list of (IP, MAC).
4. For each detected host, CLI passes MAC address to Vendor Lookup Engine:
• If Fast Scan → Local Lookup Module queries CSV.
• If Advanced Scan → Remote API Module calls external service.
5. Vendor Lookup Engine returns vendor string(s) → aggregator collects results.
6. Output Formatter renders final table to the console.
Architectural patterns & design principles
• Single-process, modular design—separate functional concerns into:
– Input (CLI)
– Processing (Scanning + Lookup)
– Data Access (CSV file, HTTP API)
– Presentation (Console output)
• Clear separation of offline vs. online lookup paths.
• Rate-limiting logic isolated in the Remote API Module.
Essential elements
• Clear component labels (CLI, Scanner, Local Lookup, Remote Lookup, Formatter).
– Internal modules
– Local dataset
– External API