# samyk/pwnat architecture

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

- Interactive diagram: https://gitdiagram.com/samyk/pwnat
- Repository: https://github.com/samyk/pwnat

## Overview

pwnat establishes direct client-to-server tunnels through NATs: the client uses a local TCP listener and UDP tunnel, while the server discovers clients with ICMP and bridges UDP traffic to an allowed or selected TCP destination. The graph preserves those documented stages and the sampled client, message, socket, packet, and state-management layers. Some server-loop details and other modules were not excerpted; edges for those are limited to README descriptions or visible references.

Main entry points: [`src/udpserver.c`](https://github.com/samyk/pwnat/blob/master/src/udpserver.c) (Server mode), [`src/udpclient.c`](https://github.com/samyk/pwnat/blob/master/src/udpclient.c) (Client mode), [`src/client.c`](https://github.com/samyk/pwnat/blob/master/src/client.c) (Client state), [`src/socket.c`](https://github.com/samyk/pwnat/blob/master/src/socket.c) (Socket transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Program entry"]
  node_pwnat["Mode dispatcher<br/>[pwnat.c]"]
  node_cli["Option parsing<br/>[xgetopt.c]"]
end

subgraph group_tunnel["Tunnel endpoints"]
  node_client_mode["Client mode<br/>[udpclient.c]"]
  node_server_mode["Server mode<br/>[udpserver.c]"]
  node_client_state["Client state<br/>[client.c]"]
  node_destination["Destination rules<br/>[destination.c]"]
end

subgraph group_protocol["Protocol and discovery"]
  node_messages["UDP messages<br/>[message.c]"]
  node_icmp["ICMP discovery<br/>[packet.c]"]
end

subgraph group_runtime["Runtime support"]
  node_sockets["Socket transport<br/>[socket.c]"]
  node_client_list["Client registry<br/>[list.c]"]
  node_common["Shared definitions<br/>[common.h]"]
  node_time["Time support<br/>[gettimeofday.c]"]
end

node_user(("Tunnel operator"))

node_user -->|"selects mode"| node_pwnat
node_pwnat -->|"parses options"| node_cli
node_pwnat -.->|"dispatches client"| node_client_mode
node_pwnat -.->|"dispatches server"| node_server_mode
node_client_mode -->|"opens TCP/UDP"| node_sockets
node_client_mode -->|"creates clients"| node_client_state
node_client_mode -.->|"exchanges messages"| node_messages
node_server_mode -->|"sends discovery"| node_icmp
node_server_mode -->|"loads restrictions"| node_destination
node_server_mode -->|"tracks clients"| node_client_list
node_server_mode -->|"handles client state"| node_client_state
node_server_mode -.->|"opens UDP/TCP"| node_sockets
node_server_mode -->|"handles tunnel messages"| node_messages
node_client_state -->|"sends protocol data"| node_messages
node_client_state -->|"uses client sockets"| node_sockets
node_client_list -->|"stores clients"| node_client_state
node_messages -->|"transfers packets"| node_sockets
node_icmp -->|"sends raw packets"| node_sockets
node_client_mode -.->|"checks timers"| node_time
node_server_mode -.->|"checks timers"| node_time
node_client_mode -->|"uses shared definitions"| node_common
node_server_mode -->|"uses shared definitions"| node_common

click node_pwnat "https://github.com/samyk/pwnat/blob/master/src/pwnat.c"
click node_cli "https://github.com/samyk/pwnat/blob/master/src/xgetopt.c"
click node_client_mode "https://github.com/samyk/pwnat/blob/master/src/udpclient.c"
click node_server_mode "https://github.com/samyk/pwnat/blob/master/src/udpserver.c"
click node_client_state "https://github.com/samyk/pwnat/blob/master/src/client.c"
click node_destination "https://github.com/samyk/pwnat/blob/master/src/destination.c"
click node_messages "https://github.com/samyk/pwnat/blob/master/src/message.c"
click node_icmp "https://github.com/samyk/pwnat/blob/master/src/packet.c"
click node_sockets "https://github.com/samyk/pwnat/blob/master/src/socket.c"
click node_client_list "https://github.com/samyk/pwnat/blob/master/src/list.c"
click node_common "https://github.com/samyk/pwnat/blob/master/src/common.h"
click node_time "https://github.com/samyk/pwnat/blob/master/src/gettimeofday.c"

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_pwnat,node_cli toneBlue
class node_client_mode,node_server_mode,node_client_state,node_destination toneAmber
class node_messages,node_icmp toneMint
class node_sockets,node_client_list,node_common,node_time toneRose
class node_user toneIndigo
```

## Components

### Program entry

- [Mode dispatcher](https://github.com/samyk/pwnat/blob/master/src/pwnat.c): `src/pwnat.c`
- [Option parsing](https://github.com/samyk/pwnat/blob/master/src/xgetopt.c): `src/xgetopt.c`

### Tunnel endpoints

- [Client mode](https://github.com/samyk/pwnat/blob/master/src/udpclient.c): `src/udpclient.c`
- [Server mode](https://github.com/samyk/pwnat/blob/master/src/udpserver.c): `src/udpserver.c`
- [Client state](https://github.com/samyk/pwnat/blob/master/src/client.c): `src/client.c`
- [Destination rules](https://github.com/samyk/pwnat/blob/master/src/destination.c): `src/destination.c`

### Protocol and discovery

- [UDP messages](https://github.com/samyk/pwnat/blob/master/src/message.c): `src/message.c`
- [ICMP discovery](https://github.com/samyk/pwnat/blob/master/src/packet.c): `src/packet.c`

### Runtime support

- [Socket transport](https://github.com/samyk/pwnat/blob/master/src/socket.c): `src/socket.c`
- [Client registry](https://github.com/samyk/pwnat/blob/master/src/list.c): `src/list.c`
- [Shared definitions](https://github.com/samyk/pwnat/blob/master/src/common.h): `src/common.h`
- [Time support](https://github.com/samyk/pwnat/blob/master/src/gettimeofday.c): `src/gettimeofday.c`

### Other components

- **Tunnel operator**

## Connections

- Tunnel operator → Mode dispatcher: selects mode (evidence: `README.md`)
- Mode dispatcher → Option parsing: parses options (evidence: `src/pwnat.c`)
- Mode dispatcher → Client mode: dispatches client
- Mode dispatcher → Server mode: dispatches server
- Client mode → Socket transport: opens TCP/UDP (evidence: `src/udpclient.c`)
- Client mode → Client state: creates clients (evidence: `src/udpclient.c`)
- Client mode → UDP messages: exchanges messages
- Server mode → ICMP discovery: sends discovery (evidence: `README.md`)
- Server mode → Destination rules: loads restrictions (evidence: `src/udpserver.c`)
- Server mode → Client registry: tracks clients (evidence: `src/udpserver.c`)
- Server mode → Client state: handles client state (evidence: `src/udpserver.c`)
- Server mode → Socket transport: opens UDP/TCP
- Server mode → UDP messages: handles tunnel messages (evidence: `src/udpserver.c`)
- Client state → UDP messages: sends protocol data (evidence: `src/client.c`)
- Client state → Socket transport: uses client sockets (evidence: `src/client.c`)
- Client registry → Client state: stores clients
- UDP messages → Socket transport: transfers packets (evidence: `src/message.c`)
- ICMP discovery → Socket transport: sends raw packets (evidence: `src/packet.c`)
- Client mode → Time support: checks timers
- Server mode → Time support: checks timers
- Client mode → Shared definitions: uses shared definitions (evidence: `src/udpclient.c`)
- Server mode → Shared definitions: uses shared definitions (evidence: `src/udpserver.c`)
