# hbn1987/6scan architecture

> Architecture diagram of the GitHub repository hbn1987/6scan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hbn1987/6scan
- Repository: https://github.com/hbn1987/6scan

## Overview

##### Project type and purpose
- This is a full‐stack IPv6 scanning framework (“HMap v1.0”) combining:
–  High‐performance C++ probing binaries (ping, traceroute, various TGA strategies)
–  Python orchestration scripts for seed generation, dispatch, collection, and analysis
–  Helper libraries (ipv6toolkit, libcperm) for address manipulation and permutation
- It produces IPv6 hitlists, applies de‐aliasing, runs Internet‐wide scans, and analyzes results.

##### High‐level component breakdown
A.  CLI Probing Engine (C++, under Htrace6/trace6 & parsers/)
–  Core binaries:
- 6scan (main.cc) – dispatches to ping6, trace6, target‐generation modules
- HMap‐ping6, HMap‐trace6, multiple UDP/TCP/ICMP prober implementations
–  Parsers & utilities: route_path.cc, utils.cc/h – parse and post‐process responses
–  Configuration & build: Bazel BUILD files, autoconf/bootstrap, Makefile.am
B.  Target Generation Algorithms (TGA) (C++, under strategy/)
–  HMap6, 6Scan, 6Hit, 6Tree, 6Gen strategies (strategy/*.cpp/.h)
–  Patricia‐tree and JSON reader modules to load seed sets
C.  Address manipulation libraries
–  ipv6toolkit/tools – raw IPv6 address routines
–  libcperm – prefix permutation, Feistel ciphers for randomized probing
D.  Python Orchestration & Scheduling
–  runner/ – sequential 1Hseed.py, 2Aliasp.py, 3Mseed.py, 4Evalu.py
–  scheduling/ – distributed seeds_dispatch.py, ssh_runner.py, data_pullback.py
–  reflections/, analysis/ – post‐scan analytics (entropy, geo, ASN stats)
E.  External Data & Services
–  RIPE, IPv6hitlist APIs for hitlist, alias lists, country/ASN data
–  Local disk storage: CSVs, JSON, raw output files under analysis/data and output/

##### Interactions & data flow
1.  Seed collection: runner/1Hseed.py calls 6scan -P to probe the hitlist → raw responses
2.  Alias‐prefix extraction: runner/2Aliasp.py loads raw responses → alias list
3.  Seedset generation: runner/3Mseed.py merges hitlist + alias list → seed JSON
4.  Scanning: CLI engine (6scan) + TGA modules read seed JSON → send probes → dump_result
5.  Distributed dispatch: scheduling/seeds_dispatch.py distributes seed JSON to workers
6.  Probe execution: scheduling/ssh_runner.py remotely invokes 6scan → writes per‐worker logs
7.  Data pullback: scheduling/data_pullback.py collects remote results → central storage
8.  Analysis: analysis/*.py loads CSV/JSON → generates statistics, visualizations

##### Architectural patterns & principles
- Modular CLI binaries (single‐responsibility for ping vs. trace vs. TGA)
- Plugin‐style TGA strategies (strategy/ folder): easily add new scanning heuristics
- Library reuse: ipv6toolkit + libcperm separate address math and crypto/permutation
- Orchestration as code: Python scripts glue together C++ binaries for end‐to‐end flow
- Data‐centric: JSON/CSV seed lists and raw logs are the primary “contracts” between components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% C++ Layer
    subgraph "Probing Engine (C++)"
        CLI["6scan CLI & HMap-ping6, trace6 modules"]:::cpp
        Parsers["Parsers & utilities"]:::cpp
        ALT["Alternative Scanner (scanner/)"]:::cpp
        Build["Build & CI (autoconf, Bazel)"]:::ci
    end

    %% TGA Plugins
    subgraph "TGA Strategy Modules"
        TGA["Strategy plugins (strategy/)"]:::cpp
    end

    %% Address Libraries
    subgraph "Address Libraries"
        Lib1["ipv6toolkit/tools"]:::lib
        Lib2["libcperm"]:::lib
    end

    %% Python Orchestration
    subgraph "Python Orchestrator"
        subgraph "Sequential Runner"
            S1["1Hseed.py"]:::py
            S2["2Aliasp.py"]:::py
            S3["3Mseed.py"]:::py
            S4["4Evalu.py"]:::py
        end
        subgraph "Scheduling"
            SD["seeds_dispatch.py"]:::py
            SSH["ssh_runner.py"]:::py
            DP["data_pullback.py"]:::py
        end
    end

    %% Analytics & Others
    subgraph "Post-scan Analytics"
        Analytics["analysis/*.py"]:::py
    end
    subgraph "Reflections & Experimental"
        Ref["reflections/"]:::py
    end
    subgraph "Toy/Prototype Tools"
        Toys["toyscanner/..."]:::py
    end

    %% Data Stores
    subgraph "Storage & Data"
        SeedJSON["Seed JSON"]:::data
        RawOut["Raw Results JSON/CSV"]:::data
        AliasList["Alias List"]:::data
        AnalysisData["analysis/data"]:::data
        Reports["Reports & Visualizations"]:::data
    end

    %% External Services
    subgraph "External Services"
        RIPE["RIPE Data API"]:::external
        Hitlist["IPv6hitlist API"]:::external
        Network["IPv6 Internet (Network)"]:::external
    end

    %% Data Flows
    S1 -->|"invoke 6scan -P with JSON seed"| CLI
    CLI -->|"ICMP6/UDP6 probes"| Network
    Network -->|"responses"| CLI
    CLI -->|"dump raw_result (JSON/CSV)"| RawOut

    S2 -->|"read raw responses"| RawOut
    S2 -->|"write alias list (CSV/JSON)"| AliasList

    S3 -->|"read hitlist + alias"| Hitlist
    S3 -->|"generate seed JSON"| SeedJSON

    SD -->|"distribute seed JSON"| CLI
    SSH -->|"invoke 6scan remotely"| CLI
    CLI -->|"per-worker logs"| RawOut
    DP -->|"collect remote results"| RawOut

    S4 -->|"initiate analysis"| Analytics
    Analytics -->|"read logs & seeds"| RawOut & SeedJSON & AliasList
    Analytics -->|"produce reports"| Reports

    S1 -->|"download hitlist/alias"| RIPE & Hitlist

    CLI -->|"load strategy plugin"| TGA
    TGA -->|"use address APIs"| Lib1 & Lib2
    CLI -->|"use address APIs"| Lib1 & Lib2

    %% Click Events
    click CLI "https://github.com/hbn1987/6scan/tree/master/Htrace6/trace6/"
    click Parsers "https://github.com/hbn1987/6scan/tree/master/Htrace6/parsers/"
    click Build "https://github.com/hbn1987/6scan/tree/master/Htrace6/BUILD"
    click ALT "https://github.com/hbn1987/6scan/tree/master/scanner/"
    click TGA "https://github.com/hbn1987/6scan/tree/master/strategy/"
    click Lib1 "https://github.com/hbn1987/6scan/tree/master/ipv6toolkit/tools/"
    click Lib2 "https://github.com/hbn1987/6scan/tree/master/libcperm/"
    click S1 "https://github.com/hbn1987/6scan/blob/master/runner/1Hseed.py"
    click S2 "https://github.com/hbn1987/6scan/blob/master/runner/2Aliasp.py"
    click S3 "https://github.com/hbn1987/6scan/blob/master/runner/3Mseed.py"
    click S4 "https://github.com/hbn1987/6scan/blob/master/runner/4Evalu.py"
    click SD "https://github.com/hbn1987/6scan/blob/master/scheduling/seeds_dispatch.py"
    click SSH "https://github.com/hbn1987/6scan/blob/master/scheduling/ssh_runner.py"
    click DP "https://github.com/hbn1987/6scan/blob/master/scheduling/data_pullback.py"
    click Analytics "https://github.com/hbn1987/6scan/tree/master/analysis/"
    click Ref "https://github.com/hbn1987/6scan/tree/master/reflections/"
    click Toys "https://github.com/hbn1987/6scan/tree/master/toyscanner/"

    %% Styles
    classDef cpp fill:#cce5ff,stroke:#004085,color:#004085
    classDef py fill:#d4edda,stroke:#155724,color:#155724
    classDef lib fill:#fff3cd,stroke:#856404,color:#856404
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00
    classDef ci fill:#f8d7da,stroke:#721c24,color:#721c24
```
