How h1ldrum/studio2-scanops-portscanner works
Project Type and Purpose
• This is a modular command-line port-scanning tool written in Python.
• It supports TCP and HTTP scans, network mapping (pinging), OS detection, and flexible reporting (console, banner, JSON).
• The user invokes a single binary (main.py/scanops), passes in command-line arguments, and the tool dispatches to pluggable scanner and reporter modules.
High-Level Architectural Components
a. CLI Frontend
• main.py (entry point)
• app_args.py (argument parser, subcommand dispatch)
b. Core Engine
• Scanner Framework (scanners/scanner.py defines interface)
• Reporter Framework (reporters/reporter.py defines interface)
c. Scanner Implementations
• tcp_scanner.py (raw TCP connect or SYN scans)
• http_port_scanner.py (HTTP-based scanning)
• scapy_scanner.py (packet crafting via Scapy)
• connect_scanner.py, tcp_scanner.py under scanners/
d. Support Modules
• network_mapping (ping.py, pinger.py, scapy_ping.py, utils.py)
• osdetection (osdetect.py)
e. Reporting Modules
• cli_reporter.py (interactive progress bars, console output)
• banner.py (ASCII art/status banner)
• json_reporter.py (structured JSON output)
• reporter_cp.py (checkpoint or cumulative progress)
f. Data & Configuration
• requirements.txt, Makefile, scripts.py
• benchmark_results/ (CSV and JSON files for performance measurements)
• output.json (default scan output file)
Component Interactions and Data Flow
• User types scanops tcp_scan -t TARGET -p PORTS -c N -T TIMEOUT
→ CLI Frontend parses arguments → instantiates
• a Scanner module (factory pattern via scanners/scanner.py)
• a Reporter module (factory pattern via reporters/reporter.py)
• Core Engine drives a scanning loop or thread‐pool:
for each port:
→ network_mapping.ping/pinger to pre-check host reachability
→ scanner.perform_scan(port) (TCP or HTTP)
→ osdetection.osdetect(port, response) (optional fingerprint)
→ reporter.report_progress(port, status)
end loop
• At completion: reporter.report_summary(results) → writes to console or JSON.
Architectural Patterns and Principles
• Plugin/Interface pattern: scanners and reporters adhere to their interface base classes.
• Single Responsibility: each module does one thing (mapping, scanning, reporting).
• Dependency Injection: main injects chosen scanner and reporter into engine.
• Concurrency: scanner implementations can launch parallel workers (thread or async).