paqet

paqet - transport over raw packets

paqet is a raw-packet proxy that tunnels traffic inside raw TCP packets. Instead of relying on the host's TCP/IP stack, it crafts and captures packets directly, while KCP provides fast, reliable, encrypted transport.

[!WARNING] This project is in active development. APIs, configuration formats, and interfaces may change without notice. Use with caution in production environments.

The Idea

Conventional applications rely on the host's TCP/IP stack, placing the kernel in the path of every connection, where it tracks each packet.

paqet operates on raw packets instead. It crafts TCP packets directly and uses pcap to capture inbound ones, treating each as a self-contained, stateless datagram. The traffic still looks ordinary on the wire, while KCP and smux provide a fast, reliable, encrypted, and multiplexed transport layer on top. paqet may bypass firewalls that rely on handshakes or connection tracking, which makes it useful for security research. Configuration is more complex than a VPN, but gives you finer control in return.

Getting Started

Prerequisites

• libpcap development libraries must be installed on both the client and server machines.
  • Linux: No prerequisites - binaries are statically linked.
  • macOS: Comes pre-installed with Xcode Command Line Tools. Install with xcode-select --install
  • Windows: Install Npcap. Download from npcap.com.

1. Download a Release

Download the pre-compiled binary for your client and server operating systems from the Releases page.

2. Configure the Connection

Finding Your Network Details

You'll need to find your network interface name, local IP, and the MAC address of your network's gateway (router).

On Linux:

1. Find Interface and Local IP: Run ip a. Look for your primary network card (e.g., eth0, ens3). Its IP address is listed under inet.
2. Find Gateway MAC:
   • First, find your gateway's IP: ip r | grep default
   • Then, find its MAC address with arp -n (e.g., arp -n 192.168.1.1).

On macOS:

1. Find Interface and Local IP: Run ifconfig. Look for your primary interface (e.g., en0). Its IP is listed under inet.
2. Find Gateway MAC:
   • First, find your gateway's IP: netstat -rn | grep default
   • Then, find its MAC address with arp -n (e.g., arp -n 192.168.1.1).

On Windows:

1. Find Interface and Local IP: Run ipconfig /all and note your active network adapter (Ethernet or Wi-Fi):
   • Its IP Address
   • The Gateway IP Address
2. Find Interface device GUID: Windows requires the Npcap device GUID. In PowerShell, run Get-NetAdapter | Select-Object Name, InterfaceGuid. Note the Name and InterfaceGuid of your active network interface, and format the GUID as \Device\NPF_{GUID}.
3. Find Gateway MAC Address: Run: arp -a . Note the MAC address for the gateway.

Client Configuration - SOCKS5 Proxy Mode

The client acts as a SOCKS5 proxy server, accepting connections from applications and dynamically forwarding them through the raw TCP packets to any destination.

Example Client Configuration (config.yaml)

…

Example Server Configuration (config.yaml)

…

Critical Firewall Configuration

Although packets are handled at a low level, the OS kernel can still see incoming packets on the connection port and generate TCP RST packets since it has no knowledge of the connection. These kernel generated resets can corrupt connection state in NAT devices and stateful firewalls, causing instability, packet drops, and premature termination.

You must configure iptables on the server to prevent the kernel from interfering.

[!IMPORTANT] Do not use ports 80, 443, or any other standard ports, because iptables rules can also affect outgoing connections from the server. Choose non-standard ports (e.g., 9999, 8888, or other high-numbered ports) for your server configuration.

Run these commands as root on your server:

…

These rules ensure that only the application handles traffic for the connection port.

3. Run paqet

Make the downloaded binary executable (chmod +x ./paqet_linux_amd64). You will need root privileges to use raw sockets.

On the Server: Place your server configuration file in the same directory as the binary and run:

# Make sure to use the binary name you downloaded for your server's OS/Arch.
sudo ./paqet_linux_amd64 run -c config.yaml

On the Client: Place your client configuration file in the same directory as the binary and run:

# Make sure to use the binary name you downloaded for your client's OS/Arch.
sudo ./paqet_darwin_arm64 run -c config.yaml

4. Test the Connection

Once the client and server are running, test the SOCKS5 proxy:

# Test with curl using the SOCKS5 proxy
curl -v https://httpbin.org/ip --proxy socks5h://127.0.0.1:1080

This request will be proxied over raw TCP packets to the server, and then forwarded according to the client mode configuration. The output should show your server's public IP address, confirming the connection is working.

Command-Line Usage

paqet is a multi-command application. The primary command is run, which starts the proxy, but several utility commands are included to help with configuration and debugging.

The general syntax is:

sudo ./paqet  [arguments]

Configuration Reference

paqet uses unified YAML configuration for client and server. The role field must be explicitly set to either "client" or "server".

For complete parameter documentation, see the example files:

• example/client.yaml.example - Client configuration reference
• example/server.yaml.example - Server configuration reference

Encryption Modes

The transport.kcp.block parameter determines the encryption method.

[!WARNING] none and null modes disable authentication, anyone with your server IP and port can connect.

• none - Plaintext with protocol header (protocol-compatible)
• null - Raw data, no header (highest performance, least secure)

TCP Flag Cycling

The network.tcp.local_flag and network.tcp.remote_flag arrays cycle through flag combinations to vary traffic patterns. Common patterns: ["PA"] (standard data), ["S"] (connection setup), ["A"] (acknowledgment).

Architecture & Security Model

The pcap Approach and Firewall Bypass

Understanding why standard firewalls are bypassed is key to using this tool securely.

A normal application uses the OS's TCP/IP stack. When a packet arrives, it travels up the stack where netfilter (the backend for ufw/firewalld) inspects it. If a firewall rule blocks the port, the packet is dropped and never reaches the application.

      +------------------------+
      |   Normal Application   |  <-- Data is received here
      +------------------------+
                   ^
      +------------------------+
      |    OS TCP/IP Stack     |  <-- Firewall (netfilter) runs here
      |  (Connection Tracking) |
      +------------------------+
                   ^
      +------------------------+
      |     Network Driver     |
      +------------------------+

paqet uses pcap to hook in at a much lower level. It requests a copy of every packet directly from the network driver, before the main OS TCP/IP stack and firewall get to process it.

      +------------------------+
      |    paqet Application   |  <-- Gets a packet copy immediately
      +------------------------+
              ^       \
 (pcap copy) /         \  (Original packet continues up)
            /           v
      +------------------------+
      |     OS TCP/IP Stack    |  <-- Firewall drops the original packet,
      |  (Connection Tracking) |      but paqet already has its copy.
      +------------------------+
                  ^
      +------------------------+
      |     Network Driver     |
      +------------------------+

This means a rule like ufw deny will have no effect on the proxy's operation, as paqet receives and processes the packet before ufw can block it.

Troubleshooting

1. Permission Denied: Ensure you are running with sudo.
2. Connection Times Out:
   • Transport Configuration Mismatch:
     • KCP: Ensure transport.kcp.key is exactly identical on client and server
   • iptables Rules: Did you apply the firewall rules on the server?
   • Incorrect Network Details: Double-check all IPs, MAC addresses, and interface names.
   • Cloud Provider Firewalls: Ensure your cloud provider's security group allows TCP traffic on your listen.addr port.
   • NAT/Port Configuration: For servers, ensure listen.addr and network.ipv4.addr ports match. For clients, use port 0 in network.ipv4.addr for automatic port assignment to avoid conflicts.
3. Use ping and dump: Use paqet ping -c config.yaml to test the connection. Use paqet dump -p on the server to see if packets are arriving.

Acknowledgments

This work implements an idea from gfw_resist_tcp_proxy by GFW-knocker, which explored the use of raw sockets to circumvent certain forms of network filtering. This project is a Go implementation of that approach.

• Uses pcap for low-level packet capture and injection
• Uses gopacket for raw packet crafting and decoding
• Uses kcp-go for reliable transport with encryption
• Uses smux for connection multiplexing

License

This project is licensed under the MIT License. See the see LICENSE file for details.