tessl/npm-socks

Fully featured SOCKS proxy client supporting SOCKSv4, SOCKSv4a, and SOCKSv5 with Bind and Associate functionality.

—

Pending

Overview

Eval results

Files

UDP Frame Handling

Name: tessl/npm-socks
Author: tessl

SOCKS v5 UDP frame creation and parsing functionality for use with the ASSOCIATE command. This enables UDP data transmission through SOCKS proxies with proper frame encapsulation.

Capabilities

UDP Frame Creation

Creates a properly formatted SOCKS v5 UDP frame for transmission through a SOCKS proxy.

/**
 * Creates a SOCKS UDP Frame for SOCKS v5 ASSOCIATE command
 * @param options - Frame configuration including remote host and data
 * @returns Buffer containing the formatted UDP frame
 */
static createUDPFrame(options: SocksUDPFrameDetails): Buffer;

interface SocksUDPFrameDetails {
  /** Frame number identifier (optional) */
  frameNumber?: number;
  /** Remote host information (destination) */
  remoteHost: SocksRemoteHost;
  /** UDP packet data to encapsulate */
  data: Buffer;
}

interface SocksRemoteHost {
  /** IPv4, IPv6 address, or hostname */
  host: string;
  /** Port number (0-65535) */
  port: number;
}

Usage Example:

import { SocksClient } from "socks";

const udpData = Buffer.from("Hello UDP!");
const frame = SocksClient.createUDPFrame({
  frameNumber: 1,
  remoteHost: {
    host: "example.com",
    port: 53
  },
  data: udpData
});

// Send frame through established ASSOCIATE connection
associateSocket.write(frame);

UDP Frame Parsing

Parses a received SOCKS v5 UDP frame to extract the remote host information and data payload.

/**
 * Parses a SOCKS UDP frame received from a SOCKS proxy
 * @param data - Buffer containing the UDP frame data
 * @returns Parsed frame details including remote host and payload
 */
static parseUDPFrame(data: Buffer): SocksUDPFrameDetails;

Usage Example:

import { SocksClient } from "socks";

// Receive UDP frame from SOCKS proxy
associateSocket.on('data', (frameData: Buffer) => {
  const parsedFrame = SocksClient.parseUDPFrame(frameData);
  
  console.log('Frame number:', parsedFrame.frameNumber);
  console.log('From:', parsedFrame.remoteHost.host, ':', parsedFrame.remoteHost.port);
  console.log('Data:', parsedFrame.data.toString());
});

UDP Frame Structure

SOCKS v5 UDP frames follow this binary structure:

+------+------+------+----------+----------+----------+
| RSV  | FRAG | ATYP | DST.ADDR | DST.PORT |   DATA   |
+------+------+------+----------+----------+----------+
|  2   |  1   |  1   | Variable |    2     | Variable |
+------+------+------+----------+----------+----------+

RSV (2 bytes): Reserved, must be 0x0000
FRAG (1 byte): Fragment number (frameNumber parameter)
ATYP (1 byte): Address type (IPv4=0x01, Hostname=0x03, IPv6=0x04)
DST.ADDR (Variable): Destination address
DST.PORT (2 bytes): Destination port in network byte order
DATA (Variable): UDP payload data

Address Type Handling

The frame creation and parsing automatically handles different address types:

IPv4 addresses: Encoded as 4-byte binary representation
IPv6 addresses: Encoded as 16-byte binary representation
Hostnames: Encoded as length-prefixed strings (max 255 bytes)

Complete ASSOCIATE Example

import { SocksClient } from "socks";

// Establish ASSOCIATE connection
const info = await SocksClient.createConnection({
  proxy: {
    host: '127.0.0.1',
    port: 1080,
    type: 5
  },
  command: 'associate',
  destination: {
    host: '0.0.0.0',  // Placeholder for UDP
    port: 0
  }
});

const udpSocket = info.socket;

// Create and send UDP frame
const frame = SocksClient.createUDPFrame({
  frameNumber: 1,
  remoteHost: {
    host: "8.8.8.8",
    port: 53
  },
  data: Buffer.from([/* DNS query bytes */])
});

udpSocket.write(frame);

// Parse received UDP frames
udpSocket.on('data', (data: Buffer) => {
  const parsedFrame = SocksClient.parseUDPFrame(data);
  console.log('UDP response from:', parsedFrame.remoteHost.host);
  // Process parsedFrame.data
});

Install with Tessl CLI