# njombart/hping architecture

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

- Interactive diagram: https://gitdiagram.com/njombart/hping
- Repository: https://github.com/njombart/hping

## Overview

##### Project type and purpose
- hping3 is a command‑line network testing and packet‑crafting tool with built‑in scripting capabilities via Tcl/Tk.
- It sends custom TCP/IP packets, handles fragmentation, parses replies, and supports traceroute, firewalk, OS fingerprinting, port scanning, and protocol auditing.
- It embeds a Tcl interpreter (“script.c” plus lib/*.htcl) to allow advanced scripted packet workflows.

##### File structure
- Top‑level C source modules (.c/.h) implement packet construction (send*.c), parsing (datahandler.c, waitpacket.c), utilities (byteorder.c, cksum.c, random.c), scripting glue (script.c, libpcap_stuff.c), and raw‑socket or pcap I/O (opensockraw.c, listen.c).
- “lib/” holds example Tcl scripts and a glue layer (apd.htcl, hpingstdlib.htcl, etc.).
- “docs/” and “RFCs/” contain user and protocol reference material.
- Build: “configure”, “Makefile.in”, “lib/README”, INSTALL.
- Dependencies implied by code and README: libpcap and optional Tcl/Tk.

##### README for additional insights
- Confirms core functionality and scripting API in docs/API.txt.
- Highlights reliance on root privileges for raw sockets and optional Tcl/Tk for scripting.
- Notes external integration points: system’s TCP/IP stack, libpcap capture API.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Frontend
    subgraph "CLI Frontend"
        CLI_main["main.c"]:::core
        CLI_parse["parseoptions.c"]:::core
        CLI_usage["usage.c"]:::core
    end

    %% Scripting Engine
    subgraph "Scripting Engine"
        Script_C["script.c"]:::scripting
        Scripts_lib["lib/*.htcl"]:::scripting
    end

    %% Packet Engine
    subgraph "Packet Engine"
        sendip["sendip.c"]:::core
        sendtcp["sendtcp.c"]:::core
        sendicmp["sendicmp.c"]:::core
        sendudp["sendudp.c"]:::core
        sendrawip["sendrawip.c"]:::core
        sendhcmp["sendhcmp.c"]:::core
        sendc["send.c"]:::core
        ipopt["ip_opt_build.c"]:::core
        sendip_handler["sendip_handler.c"]:::core
        datahandler["datahandler.c"]:::core
        waitpacket["waitpacket.c"]:::core
    end

    %% I/O Layer
    subgraph "I/O Layer"
        opensockraw["opensockraw.c"]:::core
        sockopt["sockopt.c"]:::core
        listen["listen.c"]:::core
        libpcap["libpcap_stuff.c"]:::core
    end

    %% Utility Libraries
    subgraph "Utility Libraries"
        byteorder["byteorder.c/.h"]:::core
        cksum["cksum.c"]:::core
        random_["random.c"]:::core
        sbignum["sbignum.c/.h"]:::core
        memlock["memlock*.c"]:::core
        adbuf["adbuf.c/.h"]:::core
    end

    %% Documentation & Scripts
    subgraph "Documentation & Scripts"
        docs["docs/"]:::external
        rfcs["RFCs/"]:::external
        example_lib["lib/ (Tcl examples)"]:::scripting
    end

    %% External Dependencies
    subgraph "External Dependencies"
        libpcap_ext["libpcap"]:::external
        os_stack["OS Network Stack"]:::external
        tcltk["Tcl/Tk"]:::external,optional
    end

    network["Internet/Network"]:::external

    %% Flows
    CLI_main -->|parses commands| sendip
    CLI_main -->|invokes scripts| Script_C
    Script_C -->|calls Packet API| sendip
    Script_C -->|invokes I/O| opensockraw

    sendip -->|builds packets| ipopt
    sendip -->|uses utils| cksum
    sendip -->|uses utils| byteorder
    sendip -->|uses utils| random_
    sendip -->|sends to I/O| opensockraw
    sendip -->|alternative send| libpcap

    opensockraw -->|injects via raw socket| os_stack
    libpcap -->|injects via libpcap| os_stack
    os_stack --> network

    network -->|incoming replies| listen
    network -->|incoming via pcap| libpcap
    listen --> waitpacket
    libpcap --> waitpacket
    waitpacket --> datahandler
    datahandler -->|returns to CLI| CLI_main
    datahandler -->|returns to scripts| Script_C

    %% Click Events
    click CLI_main "https://github.com/njombart/hping/blob/master/main.c"
    click CLI_parse "https://github.com/njombart/hping/blob/master/parseoptions.c"
    click CLI_usage "https://github.com/njombart/hping/blob/master/usage.c"
    click Script_C "https://github.com/njombart/hping/blob/master/script.c"
    click Scripts_lib "https://github.com/njombart/hping/tree/master/lib/"
    click sendip "https://github.com/njombart/hping/blob/master/sendip.c"
    click sendtcp "https://github.com/njombart/hping/blob/master/sendtcp.c"
    click sendicmp "https://github.com/njombart/hping/blob/master/sendicmp.c"
    click sendudp "https://github.com/njombart/hping/blob/master/sendudp.c"
    click sendrawip "https://github.com/njombart/hping/blob/master/sendrawip.c"
    click sendhcmp "https://github.com/njombart/hping/blob/master/sendhcmp.c"
    click sendc "https://github.com/njombart/hping/blob/master/send.c"
    click ipopt "https://github.com/njombart/hping/blob/master/ip_opt_build.c"
    click sendip_handler "https://github.com/njombart/hping/blob/master/sendip_handler.c"
    click datahandler "https://github.com/njombart/hping/blob/master/datahandler.c"
    click waitpacket "https://github.com/njombart/hping/blob/master/waitpacket.c"
    click opensockraw "https://github.com/njombart/hping/blob/master/opensockraw.c"
    click sockopt "https://github.com/njombart/hping/blob/master/sockopt.c"
    click listen "https://github.com/njombart/hping/blob/master/listen.c"
    click libpcap "https://github.com/njombart/hping/blob/master/libpcap_stuff.c"
    click byteorder "https://github.com/njombart/hping/blob/master/byteorder.c"
    click cksum "https://github.com/njombart/hping/blob/master/cksum.c"
    click random_ "https://github.com/njombart/hping/blob/master/random.c"
    click sbignum "https://github.com/njombart/hping/blob/master/sbignum.c"
    click memlock "https://github.com/njombart/hping/blob/master/memlock.c"
    click adbuf "https://github.com/njombart/hping/blob/master/adbuf.c"
    click docs "https://github.com/njombart/hping/tree/master/docs/"
    click rfcs "https://github.com/njombart/hping/tree/master/RFCs/"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#2196F3,color:#0D47A1
    classDef scripting fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef external fill:#EEEEEE,stroke:#9E9E9E,color:#424242
    classDef optional stroke-dasharray:5 5,color:#424242
```
