# h1ldrum/studio2-scanops-portscanner architecture

> Architecture diagram of the GitHub repository h1ldrum/studio2-scanops-portscanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/h1ldrum/studio2-scanops-portscanner
- Repository: https://github.com/h1ldrum/studio2-scanops-portscanner

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: User & CLI
    User["User"]:::external
    subgraph "Layer 1: User & CLI"
        Main["main.py"]:::cli
        AppArgs["app_args.py"]:::cli
    end
    User -->|"scanops command"| Main
    Main -->|"parses args"| AppArgs

    %% Layer 2: Core Engine & Factories
    subgraph "Layer 2: Core Engine & Factories"
        Engine["port_scanner.py"]:::core
        ScannerFactory["scanners/scanner.py"]:::framework
        ReporterFactory["reporters/reporter.py"]:::framework
    end
    AppArgs -->|"init scanner"| ScannerFactory
    AppArgs -->|"init reporter"| ReporterFactory
    ScannerFactory -->|"provides scanner"| Engine
    ReporterFactory -->|"provides reporter"| Engine

    %% Layer 3: Plugins
    subgraph "Layer 3: Plugins"
        subgraph "Scanners"
            TCP["tcp_scanner.py"]:::scanner
            Connect["connect_scanner.py"]:::scanner
            HTTP["http_port_scanner.py"]:::scanner
            Scapy["scapy_scanner.py"]:::scanner
        end
        subgraph "Support Modules"
            Ping["ping.py"]:::support
            Pinger["pinger.py"]:::support
            ScapyPing["scapy_ping.py"]:::support
            Utils["utils.py"]:::support
            OSDetect["osdetect.py"]:::support
        end
        subgraph "Reporters"
            CLIReporter["cli_reporter.py"]:::reporter
            Banner["banner.py"]:::reporter
            JSONRep["json_reporter.py"]:::reporter
            Checkpoint["reporter_cp.py"]:::reporter
        end
    end
    Engine -->|"perform_scan(port)"| TCP
    Engine -->|"perform_scan(port)"| Connect
    Engine -->|"perform_scan(port)"| HTTP
    Engine -->|"perform_scan(port)"| Scapy
    Engine -->|"ping host"| Ping
    Engine -->|"ping host"| Pinger
    Engine -->|"ping host"| ScapyPing
    Engine -->|"utils for mapping"| Utils
    Engine -->|"os fingerprint"| OSDetect
    Engine -->|"report progress"| CLIReporter
    Engine -->|"report progress"| Banner
    Engine -->|"report progress"| JSONRep
    Engine -->|"report progress"| Checkpoint

    %% Layer 4: Data & External
    subgraph "Layer 4: Data & External"
        Output["output.json"]:::data
        Bench["benchmark_results/"]:::data
        Requirements["requirements.txt"]:::config
        MakefileNode["Makefile"]:::config
        Scripts["scripts.py"]:::config
        ScapyLib["Scapy"]:::external
        Stdlib["Python stdlib"]:::external
    end
    Requirements -->|"dependency list"| AppArgs
    MakefileNode -->|"build scripts"| AppArgs
    Scripts -->|"helper scripts"| AppArgs
    JSONRep -->|"writes summary"| Output
    Engine -->|"reads/writes"| Bench
    ScapyLib -->|"library use"| Scapy
    ScapyLib -->|"library use"| ScapyPing
    Stdlib -->|"core modules"| Engine
    Stdlib -->|"core modules"| TCP
    Stdlib -->|"core modules"| Connect
    Stdlib -->|"core modules"| HTTP
    Stdlib -->|"core modules"| Scapy
    Stdlib -->|"core modules"| CLIReporter

    %% Click Events
    click Main "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/main.py"
    click AppArgs "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/app_args.py"
    click Engine "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/port_scanner.py"
    click ScannerFactory "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/scanners/scanner.py"
    click ReporterFactory "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/reporters/reporter.py"
    click TCP "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/scanners/tcp_scanner.py"
    click Connect "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/scanners/connect_scanner.py"
    click HTTP "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/scanners/http_port_scanner.py"
    click Scapy "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/scanners/scapy_scanner.py"
    click Ping "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/network_mapping/ping.py"
    click Pinger "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/network_mapping/pinger.py"
    click ScapyPing "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/network_mapping/scapy_ping.py"
    click Utils "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/network_mapping/utils.py"
    click OSDetect "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/osdetection/osdetect.py"
    click CLIReporter "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/reporters/cli_reporter.py"
    click Banner "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/reporters/banner.py"
    click JSONRep "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/reporters/json_reporter.py"
    click Checkpoint "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/reporters/reporter_cp.py"
    click Requirements "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/requirements.txt"
    click MakefileNode "https://github.com/h1ldrum/studio2-scanops-portscanner/tree/main/Makefile"
    click Scripts "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/scripts.py"
    click Output "https://github.com/h1ldrum/studio2-scanops-portscanner/blob/main/output.json"
    click Bench "https://github.com/h1ldrum/studio2-scanops-portscanner/tree/main/benchmark_results/"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef framework fill:#bfb,stroke:#333,stroke-width:1px
    classDef scanner fill:#fbf,stroke:#333,stroke-width:1px
    classDef reporter fill:#ffb,stroke:#333,stroke-width:1px
    classDef support fill:#fb8,stroke:#333,stroke-width:1px
    classDef data fill:#8ff,stroke:#333,stroke-width:1px
    classDef config fill:#8f8,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#333,stroke-dasharray: 5 5,stroke-width:1px
```
