IPsec-Automated-NAT-Traversal

Scripts made in conjunction with my master's thesis at NTNU. The topic is IPsec tunnels between end-user devices behind NAT.

A toolkit for establishing site-to-site strongSwan IPsec tunnels between hosts that both sit behind NAT, without requiring either side to have a static public IP or manually configured port forwarding. A lightweight UDP rendezvous server performs peer discovery and UDP hole punching so the two peers can learn each other's public-facing IP:port and open the NAT mappings needed for IKE/NAT-T to flow.

The GNS3 project exports used throughout the project can be found here.

How it works

The core problem this solves is that two machines behind NAT cannot normally reach each other directly, as neither knows its own public address, and inbound packets are dropped unless a mapping already exists. This project works around that with a two-stage flow:

Peer discovery Each client sends a UDP registration packet to the rendezvous server from the same local port that strongSwan will later use for IKE/NAT-T (4500 by default). The server observes the packet's source address, learns the client's NAT-mapped public IP and port, and reports them back along with the list of other registered peers.
Tunnel establishment Once a client picks a peer, a swanctl config is generated from a template using the discovered addresses and ports, strongSwan is restarted, and the IKE/child SAs are initiated.

The tunnel uses IKEv2 with PSK authentication, aes256-sha256-modp2048 proposals, and runs with encap = yes (force UDP encapsulation) and mobike = yes so the connection survives NAT rebinding.

Repository layout

Path	Purpose
`autoconnect/rendezvous.py`	Rendezvous/signalling server. Run this on a publicly reachable host.
`autoconnect/forwarding_client.py`	Client registration and discovery logic. Binds the IKE port and reports the observed public address to the server.
`autoconnect/generate_config.py`	Fills `swanctl.template` with local/remote addresses and ports and writes a per-connection file to `/etc/swanctl/conf.d/`.
`autoconnect/auto_connect.py`	End-to-end orchestrator. Stops strongSwan, discovers peers, generates config, restarts strongSwan, and initiates the tunnel.
`autoconnect/cleanup_script.py`	Removes generated connection configs and terminates tunnels created by `auto_connect.py`.
`autoconnect/swanctl.template`	StrongSwan configuration template used by `generate_config.py`.
`autoconnect/requirements.txt`	Python dependencies for the main toolkit.
`mapping-test/`	NAT traversal tests with sample client/server scripts used for classification and measuring.
`docker-images/`	Docker assets for NAT experiments, including containerized autoconnect tooling and NAT topology helpers used in the gns3 testing phase.
`gns3-exports/`	Exported GNS3 project files for NAT topology and testbed setup.
`results/`	Experimental data from the thesis work and analysis notebook used for the thesis results.

Requirements

strongSwan with the swanctl interface configuration, not the legacy ipsec.conf. On Debian/Ubuntu:

sudo apt install strongswan strongswan-swanctl

Python 3.7+ (uses asyncio).
Root privileges on clients to bind the IKE port, write to /etc/swanctl/conf.d/, and control the strongSwan service.
A publicly reachable rendezvous host that is not behind the same NAT as either peer.

Install Python dependencies for the main toolkit:

pip install -r autoconnect/requirements.txt

If you want to run the sample NAT experiments in mapping-test/, install that directory's own requirements:

pip install -r mapping-test/requirements.txt

Usage

1. Start the rendezvous server

On the publicly reachable server, run:

python3 autoconnect/rendezvous.py

It will prompt for a port (default 50055). Ensure the UDP port is open in the host firewall and any cloud security groups.

2. Connect from each peer

On each client machine, run the connection orchestrator with root privileges:

sudo python3 autoconnect/auto_connect.py

The script will:

Stop strongSwan so the IKE port (4500) is free to bind for discovery.
Detect the local IP.
Prompt for the rendezvous server IP and port.
Register and display discovered peers.
Let you choose a peer or refresh the peer list.
Generate the config, restart strongSwan, and initiate the tunnel.

Run both peers close together in time so both remain registered, and use the same PSK on both ends.

3. Verify

sudo swanctl --list-sas

You should see an established IKE SA and child SA for the configured tunnel.

4. Tear down

sudo python3 autoconnect/cleanup_script.py

This removes generated configs and terminates the created connection.

Docker and experimental assets

docker-images/custom-script/ contains a container-friendly version of the autoconnect toolkit and supporting scripts. This is used for the rendezvous server and autoconnect routers in the gns3 exports.
docker-images/nat1/, docker-images/nat2/, docker-images/restricted-1/, and docker-images/restricted-2/ contain Docker NAT images and iptables configuration used for topology testing.
gns3-exports/ contains exported GNS3 project files for NAT scenario reproduction.

Results

The results/ directory contains thesis experimental output, including CSV data and a Jupyter notebook for analysis and figure generation.

Notes & caveats

NAT type matters. UDP hole punching works reliably with full-cone, restricted-cone, and port-restricted-cone NATs. It is unreliable or impossible behind symmetric NATs, where the public port may differ per destination. Carrier-grade NAT (CGNAT) frequently behaves like symmetric NAT.
Timing. NAT mappings and server registration TTLs expire. If a connection attempt fails, refresh discovery and retry so both peers have current NAT mappings.
PSK security. The pre-shared key is the only authentication. Use a strong, randomly generated key and share it out of band. Generated configs are written to /etc/swanctl/conf.d/ in plaintext and should remain root-only.
Firewalls. Both peers need outbound UDP access to the rendezvous server, and the rendezvous host needs its chosen UDP port open inbound.

ie-iik/2026-thesis-sindrrsv

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages