# hackerschoice/gsocket architecture

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

- Interactive diagram: https://gitdiagram.com/hackerschoice/gsocket
- Repository: https://github.com/hackerschoice/gsocket

## Overview

Global Socket lets programs behind NAT or firewalls establish an encrypted TCP connection using a shared secret rather than peer addresses. The principal workflow is: a user starts a toolkit command, derives a temporary Global Socket identity, connects through the relay network, negotiates SRP/TLS encryption, then exchanges application streams. The sampled code covers the connection engine, nonblocking event loop, packet dispatch, gs-netcat forwarding, file transfer, console control, and preload-based socket hijacking. Other documented tools are represented only at their enclosing tools directory.

Main entry points: [`tools/4_gs-netcat.c`](https://github.com/hackerschoice/gsocket/blob/master/tools/4_gs-netcat.c) (gs-netcat), [`lib/gsocket-engine.c`](https://github.com/hackerschoice/gsocket/blob/master/lib/gsocket-engine.c) (Connection Engine), [`tools/pkt_mgr.c`](https://github.com/hackerschoice/gsocket/blob/master/tools/pkt_mgr.c) (Packet Manager), [`tools/gsocket_dso.c`](https://github.com/hackerschoice/gsocket/blob/master/tools/gsocket_dso.c) (Socket Hijacking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Core Runtime"]
  node_secret["Secret Identity<br/>[gsocket-util.c]"]
  node_engine["Connection Engine<br/>[gsocket-engine.c]"]
  node_event_loop["Select Event Loop<br/>[gs-select.h]"]
end

subgraph group_security["Secure Transport"]
  node_ssl["SRP TLS Layer<br/>[gsocket-ssl.c]"]
end

subgraph group_protocol["Application Protocol"]
  node_packet["Packet Codec<br/>[packet.c]"]
  node_packet_manager["Packet Manager<br/>[pkt_mgr.c]"]
end

subgraph group_tools["Toolkit Features"]
  node_netcat["gs-netcat<br/>[4_gs-netcat.c]"]
  node_file_transfer["File Transfer<br/>[filetransfer.c]"]
  node_console["Interactive Console<br/>[console.c]"]
end

subgraph group_integration["System Integration"]
  node_socket_hijack["Socket Hijacking<br/>[gsocket_dso.c]"]
  node_other_tools["SFTP Mount Blitz"]
end

node_user_a(("User A"))
node_user_b(("User B"))
node_local_program["Local Program"]
node_gsrn{{"Relay Network"}}
node_openssl["OpenSSL"]
node_tor{{"TOR SOCKS"}}
node_filesystem[("Local Filesystem")]
node_shell["Shell Process"]

node_user_a -->|"starts command"| node_netcat
node_user_b -->|"starts command"| node_netcat
node_netcat -->|"derives identity"| node_secret
node_netcat -->|"opens socket"| node_engine
node_engine -->|"connects relay"| node_gsrn
node_engine -->|"waits for I/O"| node_event_loop
node_engine -->|"negotiates TLS"| node_ssl
node_ssl -->|"uses crypto"| node_openssl
node_engine -->|"returns connection"| node_netcat
node_netcat -->|"dispatches traffic"| node_packet_manager
node_packet_manager -->|"encodes packets"| node_packet
node_packet_manager -->|"dispatches files"| node_file_transfer
node_netcat -->|"handles console"| node_console
node_netcat -->|"forwards shell"| node_shell
node_file_transfer -->|"reads writes"| node_filesystem
node_netcat -->|"forwards TCP"| node_local_program
node_user_a -->|"runs wrapper"| node_socket_hijack
node_socket_hijack -->|"intercepts sockets"| node_local_program
node_socket_hijack -->|"spawns forwarder"| node_netcat
node_other_tools -.->|"uses library"| node_engine
node_engine -.->|"routes optionally"| node_tor

click node_secret "https://github.com/hackerschoice/gsocket/blob/master/lib/gsocket-util.c"
click node_engine "https://github.com/hackerschoice/gsocket/blob/master/lib/gsocket-engine.c"
click node_event_loop "https://github.com/hackerschoice/gsocket/blob/master/include/gsocket/gs-select.h"
click node_ssl "https://github.com/hackerschoice/gsocket/blob/master/lib/gsocket-ssl.c"
click node_packet "https://github.com/hackerschoice/gsocket/blob/master/lib/packet.c"
click node_packet_manager "https://github.com/hackerschoice/gsocket/blob/master/tools/pkt_mgr.c"
click node_netcat "https://github.com/hackerschoice/gsocket/blob/master/tools/4_gs-netcat.c"
click node_file_transfer "https://github.com/hackerschoice/gsocket/blob/master/tools/filetransfer.c"
click node_console "https://github.com/hackerschoice/gsocket/blob/master/tools/console.c"
click node_socket_hijack "https://github.com/hackerschoice/gsocket/blob/master/tools/gsocket_dso.c"
click node_other_tools "https://github.com/hackerschoice/gsocket/tree/master/tools"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_secret,node_engine,node_event_loop,node_user_a,node_user_b toneBlue
class node_ssl,node_filesystem toneAmber
class node_packet,node_packet_manager toneMint
class node_netcat,node_file_transfer,node_console toneRose
class node_socket_hijack,node_other_tools,node_local_program,node_gsrn,node_openssl,node_tor,node_shell toneIndigo
```

## Components

### Core Runtime

- [Secret Identity](https://github.com/hackerschoice/gsocket/blob/master/lib/gsocket-util.c): `lib/gsocket-util.c`
- [Connection Engine](https://github.com/hackerschoice/gsocket/blob/master/lib/gsocket-engine.c): `lib/gsocket-engine.c`
- [Select Event Loop](https://github.com/hackerschoice/gsocket/blob/master/include/gsocket/gs-select.h): `include/gsocket/gs-select.h`

### Secure Transport

- [SRP TLS Layer](https://github.com/hackerschoice/gsocket/blob/master/lib/gsocket-ssl.c): `lib/gsocket-ssl.c`

### Application Protocol

- [Packet Codec](https://github.com/hackerschoice/gsocket/blob/master/lib/packet.c): `lib/packet.c`
- [Packet Manager](https://github.com/hackerschoice/gsocket/blob/master/tools/pkt_mgr.c): `tools/pkt_mgr.c`

### Toolkit Features

- [gs-netcat](https://github.com/hackerschoice/gsocket/blob/master/tools/4_gs-netcat.c): `tools/4_gs-netcat.c`
- [File Transfer](https://github.com/hackerschoice/gsocket/blob/master/tools/filetransfer.c): `tools/filetransfer.c`
- [Interactive Console](https://github.com/hackerschoice/gsocket/blob/master/tools/console.c): `tools/console.c`

### System Integration

- [Socket Hijacking](https://github.com/hackerschoice/gsocket/blob/master/tools/gsocket_dso.c): `tools/gsocket_dso.c`
- [SFTP Mount Blitz](https://github.com/hackerschoice/gsocket/tree/master/tools): `tools`

### Other components

- **User A**
- **User B**
- **Local Program**
- **Relay Network**
- **OpenSSL**
- **TOR SOCKS**
- **Local Filesystem**
- **Shell Process**

## Connections

- User A → gs-netcat: starts command
- User B → gs-netcat: starts command
- gs-netcat → Secret Identity: derives identity
- gs-netcat → Connection Engine: opens socket
- Connection Engine → Relay Network: connects relay
- Connection Engine → Select Event Loop: waits for I/O
- Connection Engine → SRP TLS Layer: negotiates TLS
- SRP TLS Layer → OpenSSL: uses crypto
- Connection Engine → gs-netcat: returns connection
- gs-netcat → Packet Manager: dispatches traffic
- Packet Manager → Packet Codec: encodes packets
- Packet Manager → File Transfer: dispatches files
- gs-netcat → Interactive Console: handles console
- gs-netcat → Shell Process: forwards shell
- File Transfer → Local Filesystem: reads writes
- gs-netcat → Local Program: forwards TCP
- User A → Socket Hijacking: runs wrapper
- Socket Hijacking → Local Program: intercepts sockets
- Socket Hijacking → gs-netcat: spawns forwarder
- SFTP Mount Blitz → Connection Engine: uses library
- Connection Engine → TOR SOCKS: routes optionally
