# amitheffect/port-scanner-tool architecture

> Architecture diagram of the GitHub repository amitheffect/port-scanner-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amitheffect/port-scanner-tool
- Repository: https://github.com/amitheffect/port-scanner-tool

## Overview

##### Project type and purpose
- Type: Single-file CLI network utility (open‑source tool) — a Python-based TCP port scanner intended for authorized security testing and network discovery.
- Purpose: Given a target (IP/hostname or CIDR) the tool concurrently probes TCP ports, identifies open ports and known services, optionally grabs banners, and prints/saves a human-readable report.

##### File-structure analysis
- Top level: LICENSE, README.md, port_scanner.py — the entire implementation lives in one script.
- No frontend/backend split, no external services or containers.
- Implicit modules / functional areas (from README): argument parsing, target resolution (CIDR expansion / DNS), thread pool scanning, socket connect probes, service mapping, optional banner grabbing, reporting/output.
- Runtime & deployment: Python 3.10+, no external dependencies; runs locally (CLI). Possible runtime resources: network stack, system resolver (DNS), file system for output.

##### README insights to capture
- Concurrency model: ThreadPoolExecutor (configurable --threads, default 100).
- Scanning method: TCP connect (socket.connect_ex), timeout parameter.
- Inputs and modes: single IP/hostname, CIDR range, port ranges/list, --top-ports mode.
- Outputs: terminal (colorized), optional file output.
- Service detection: built-in mappings + socket.getservbyport fallback.
- Banner grabbing flow: reconnect to open port to read greeting.
- Limitations: TCP-only, IPv4-only, no raw sockets.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% High-level Component Diagram (top-down, local -> OS/Network -> Remote)
    subgraph "User"
        direction TB
        User["User / Operator\n(CLI)"]:::actor
    end

    subgraph "Local Runtime (Single-file CLI Tool)"
        direction TB
        CLI["CLI Argument Parser\n(parse flags, --threads, --ports, --timeout)"]:::process
        Controller["Scanner Controller / Orchestrator\n(config object, knobs)"]:::process
        Resolver["Target Resolver\n(DNS lookup, CIDR expansion)"]:::process
        PortParser["Port Range Parser\n(ranges, lists, --top-ports)"]:::process
        Scheduler["Scan Scheduler\nThreadPoolExecutor\n(N threads, default 100)"]:::concurrency
        Workers["Worker / Probe Task\n(stateless per-probe)"]:::process
        SocketLayer["TCP Socket Layer\nsocket.connect_ex(), timeout, retry\nOptional Banner Grabber"]:::io
        ServiceDetect["Service Detector\nbuiltin mapping -> getservbyport() fallback"]:::process
        Aggregator["Result Aggregator\n(thread-safe queue, collects results)"]:::process
        Reporter["Reporter / Formatter\nANSI color output, sorting, summary"]:::process
        FileOut["FileWriter (optional)\nWrites report to filesystem"]:::storage
        RuntimeNotes["Runtime: Python 3.10+, stdlib modules:\nsocket, concurrent.futures, ipaddress, argparse,\ndatetime, os/pathlib"]:::note
    end

    subgraph "OS / System"
        direction TB
        OSNet["OS Network Stack & Resolver\n(kernel TCP/IP, system DNS resolver)"]:::os
        FileSys["Local File System\n(write/read report files)"]:::os
    end

    subgraph "Remote / External"
        direction TB
        DNS["External DNS Server\n(optional)"]:::external
        Targets["Remote Targets (Host(s))\n(IPs from Resolver / CIDR)\nRemote Services (open ports & banners)"]:::external
    end

    %% High-level flow connections (vertical)
    User -->|"exec port_scanner.py with flags"| CLI
    CLI -->|"build config"| Controller
    Controller -->|"resolve targets"| Resolver
    Resolver -->|"calls system resolver"| OSNet
    OSNet -->|"DNS query/response"| DNS
    Controller -->|"parse ports"| PortParser
    Controller -->|"start scan"| Scheduler
    Scheduler -->|"dispatch tasks (N threads)"| Workers
    Workers -->|"connect_ex(IP:port)"| SocketLayer
    SocketLayer -->|"SYN/ACK/RESET or timeout"| OSNet
    OSNet -->|"network packets"| Targets
    Targets -->|"response (established / reset / banner)"| OSNet
    OSNet -->|"socket result"| SocketLayer
    SocketLayer -->|"detect service, read banner?"| ServiceDetect
    ServiceDetect -->|"annotated result"| Aggregator
    Workers -->|"push result"| Aggregator
    Aggregator -->|"format & print"| Reporter
    Reporter -->|"terminal output (colorized)"| User
    Reporter -->|"optional write"| FileOut
    FileOut -->|"write file"| FileSys

    %% Optional / dashed flows
    SocketLayer -.->|"banner grabbing (optional --banner)"| SocketLayer
    Reporter -.->|"if --output specified"| FileOut

    %% Concurrency & limits annotation
    Scheduler ---|"IO-bound; thread pool size configurable (--threads)\nTimeouts govern per-probe lifecycle"| RuntimeNotes
    RuntimeNotes -.->|"Resource constraints: file descriptors, network rate limits"| Controller

    %% Per-probe result object (cylinder-like)
    ResultObj["{target_ip, port, state, service_name, banner?, timestamp}"]:::data
    Aggregator -->|"stores result"| ResultObj

    %% Refactor suggestion (future modular split - dashed)
    subgraph "Suggested Refactor (logical modules - future)" 
        direction TB
        mod_core["scanner/core.py"]:::suggest
        mod_workers["scanner/workers.py"]:::suggest
        mod_io["scanner/io.py"]:::suggest
        mod_services["scanner/services.py"]:::suggest
        mod_cli["cli.py"]:::suggest
    end
    Controller -.->|"could map to"| mod_core
    Workers -.->|"could map to"| mod_workers
    FileOut -.->|"could map to"| mod_io
    ServiceDetect -.->|"could map to"| mod_services
    CLI -.->|"could map to"| mod_cli

    %% Sequence Diagram (lower-level, one target, small port list)
    subgraph "Sequence: Single scan lifecycle"
        direction TB
        S1["1) User runs CLI"]:::seq
        S2["2) CLI parses args"]:::seq
        S3["3) Resolver resolves host -> IP(s)"]:::seq
        S4["4) Scheduler submits tasks to ThreadPool"]:::seq
        S5["5) Worker: socket.connect_ex() -> OS network stack"]:::seq
        S6["6) Remote target responds (open/closed)"]:::seq
        S7["7) If open && --banner: banner grab"]:::seq
        S8["8) ServiceDetect annotates result"]:::seq
        S9["9) Aggregator receives result"]:::seq
        S10["10) Reporter prints & optionally writes file"]:::seq

        S1 --> S2
        S2 --> S3
        S3 --> S4
        S4 --> S5
        S5 --> S6
        S6 --> S7
        S7 --> S8
        S8 --> S9
        S9 --> S10
    end

    %% Click Events (map to project files as provided)
    click CLI "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click Controller "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click Resolver "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click PortParser "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click Scheduler "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click Workers "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click SocketLayer "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click ServiceDetect "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click Aggregator "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click FileOut "https://github.com/amitheffect/port-scanner-tool/blob/main/port_scanner.py"
    click RuntimeNotes "https://github.com/amitheffect/port-scanner-tool/blob/main/README.md"
    click LICENSE "https://github.com/amitheffect/port-scanner-tool/tree/main/LICENSE"

    %% Styling: colors, shapes, dashed for optional
    classDef actor fill:#D0E8FF,stroke:#1B6FBF,stroke-width:1px,rounded;
    classDef process fill:#E8F3FF,stroke:#0B5FA5,stroke-width:1px,rounded;
    classDef concurrency fill:#E6F7E6,stroke:#2E9E2E,stroke-width:1px,rounded;
    classDef io fill:#FFF3E0,stroke:#D87A00,stroke-width:1px,rounded;
    classDef storage fill:#F3E8FF,stroke:#7B39B5,stroke-width:1px,rounded;
    classDef os fill:#FFEFEF,stroke:#C62828,stroke-width:1px,rounded;
    classDef external fill:#FFEFEF,stroke:#A31515,stroke-width:1px,cloud;
    classDef note fill:#F0F8FF,stroke:#4A77B7,stroke-width:1px,rounded,dashed;
    classDef data fill:#FFFBE6,stroke:#B58A00,stroke-width:1px,cylinder;
    classDef suggest fill:#F7F7F7,stroke:#999999,stroke-width:1px,rounded,dashed;
    classDef seq fill:#FFFFFF,stroke:#444444,stroke-width:1px,rounded;

    class User actor
    class CLI,Controller,Resolver,PortParser,Workers,ServiceDetect,Aggregator,Reporter process
    class Scheduler concurrency
    class SocketLayer io
    class FileOut storage
    class OSNet,FileSys os
    class DNS,Targets external
    class RuntimeNotes note
    class ResultObj data
    class mod_core,mod_workers,mod_io,mod_services,mod_cli suggest
    class S1,S2,S3,S4,S5,S6,S7,S8,S9,S10 seq

    %% Annotations / Legend
    subgraph "Legend & Knobs"
        direction TB
        L1["Config knobs: --threads, --timeout, --banner, --ports, --top-ports, --output"]:::note
        L2["Constraints: IPv4-only, TCP-only, no raw sockets"]:::note
        L3["Concurrency model: ThreadPoolExecutor for IO-bound probes"]:::note
    end

    L1 --- RuntimeNotes
    L2 --- Controller
    L3 --- Scheduler
```
