socks

What is socks?

The 'socks' npm package is a comprehensive Node.js library for working with SOCKS proxies. It supports SOCKS v4, v4a, and v5 protocols and can be used to create both SOCKS proxy clients and servers. It allows for proxying TCP and UDP connections, handling DNS lookups, and provides a way to work with different authentication methods.

What are socks's main functionalities?

Creating a SOCKS client

This code sample demonstrates how to create a SOCKS client that connects to a specified destination through a SOCKS proxy server.

const { SocksClient } = require('socks');

const options = {
  proxy: {
    host: 'host', // ipv4, ipv6, or hostname
    port: 1080,
    type: 5 // Proxy version (4, 5)
  },
  command: 'connect',
  destination: {
    host: 'destinationHost',
    port: 80
  }
};

SocksClient.createConnection(options, (err, info) => {
  if (err) {
    console.log(err);
    return;
  }
  const socket = info.socket;
  console.log('Connected to server through SOCKS proxy');
});

Creating a SOCKS server

This code sample shows how to create a SOCKS server that listens for incoming connections and can handle custom authentication.

const socks = require('socks').SocksServer;

const server = new socks({
  proxy: {
    ipaddress: 'localhost',
    port: 1080,
    type: 5
  },
  authenticate: function(username, password, socket, callback) {
    // Custom authentication logic
    callback();
  }
});

server.listen();

server.on('proxyConnect', (info, destinationSocket) => {
  console.log(`Accepted connection to ${info.host}:${info.port}`);
});

Handling UDP connections

This code sample illustrates how to handle UDP connections through a SOCKS proxy using the 'associate' command.

const { SocksClient } = require('socks');

const options = {
  proxy: {
    host: 'host',
    port: 1080,
    type: 5
  },
  command: 'associate',
  destination: {
    host: '0.0.0.0', // The local interface to bind for UDP association
    port: 0 // A random port will be used
  }
};

SocksClient.createConnection(options, (err, info) => {
  if (err) {
    console.log(err);
    return;
  }
  const udpSocket = info.socket;
  console.log('UDP association has been established.');
});

Other packages similar to socks

node-socks-proxy-agent

This package is similar to 'socks' in that it provides SOCKS proxy support for HTTP and HTTPS requests. It is specifically designed to work with the 'agent-base' API, making it easy to integrate with the built-in 'http' and 'https' modules in Node.js.

socksv5

The 'socksv5' package is another Node.js module that provides similar functionality to 'socks'. It supports the SOCKS v5 protocol and can be used to create both SOCKS clients and servers. It also supports GSS-API authentication, which is not available in the 'socks' package.

http-proxy-agent

While not limited to SOCKS proxies, 'http-proxy-agent' allows Node.js HTTP clients to proxy requests through a specified server. It supports HTTP, HTTPS, and SOCKS proxies, providing a broader range of proxy support compared to the 'socks' package.

README

socks

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

Highlights

• Supports SOCKS 4, 4a, and 5 protocols.
• Supports the CONNECT, BIND, and ASSOCIATE commands.
• Supports callbacks, promises, and events for proxy connection creation flows.
• Supports Proxy chaining (CONNECT only).
• Built in UDP frame creationg & parsing methods.
• Built in TypeScript, typings are provided.

Installing:

yarn add socks

or

npm install socks

Getting Started Example

For this example, say you wanted to grab the html of google's home page.

var Socks = require('socks');

var options = {
    proxy: {
        ipaddress: "202.101.228.108", // Random public proxy
        port: 1080,
        type: 5 // type is REQUIRED. Valid types: [4, 5]  (note 4 also works for 4a)
    },
    target: {
        host: "google.com", // can be an ip address or domain (4a and 5 only)
        port: 80
    },
    command: 'connect'  // This defaults to connect, so it's optional if you're not using BIND or Associate.
};

Socks.createConnection(options, function(err, socket, info) {
    if (err)
        console.log(err);
    else {
        // Connection has been established, we can start sending data now:
        socket.write("GET / HTTP/1.1\nHost: google.com\n\n");
        socket.on('data', function(data) {
            console.log(data.length);
            console.log(data);
        });

        // PLEASE NOTE: sockets need to be resumed before any data will come in or out as they are paused right before this callback is fired.
        socket.resume();

        // 569
        // <Buffer 48 54 54 50 2f 31 2e 31 20 33 30 31 20 4d 6f 76 65 64 20 50 65...
    }
});

BIND Example:

When sending the BIND command to a SOCKS proxy server, this will cause the proxy server to open up a new tcp port. Once this port is open, you, another client, application, etc, can then connect to the SOCKS proxy on that tcp port and communications will be forwarded to each connection through the proxy itself.

var options = {
    proxy: {
        ipaddress: "202.101.228.108",
        port: 1080,
        type: 4,
        command: "bind" // Since we are using bind, we must specify it here.
    },
    target: {
        host: "1.2.3.4", // When using bind, it's best to give an estimation of the ip that will be connecting to the newly opened tcp port on the proxy server.
        port: 1080
    }
};

Socks.createConnection(options, function(err, socket, info) {
    if (err)
        console.log(err);
    else {
        // BIND request has completed.
        // info object contains the remote ip and newly opened tcp port to connect to.
        console.log(info);

        // { port: 1494, host: '202.101.228.108' }

        socket.on('data', function(data) {
            console.log(data.length);
            console.log(data);
        });

        // Remember to resume the socket stream.
        socket.resume();
    }
});

At this point, your original connection to the proxy server remains open, and no data will be received until a tcp connection is made to the given endpoint in the info object.

For an example, I am going to connect to the endpoint with telnet:

Joshs-MacBook-Pro:~ Josh$ telnet 202.101.228.108 1494
 Trying 202.101.228.108...
 Connected to 202.101.228.108.
 Escape character is '^]'.
 hello
 aaaaaaaaa

Note that this connection to the newly bound port does not need to go through the SOCKS handshake.

Back at our original connection we see that we have received some new data:

8
<Buffer 00 5a ca 61 43 a8 09 01>  // This first piece of information can be ignored.

7
<Buffer 68 65 6c 6c 6f 0d 0a> // Hello <\r\n (enter key)>

11
<Buffer 61 61 61 61 61 61 61 61 61 0d 0a> // aaaaaaaaa <\r\n (enter key)>

As you can see the data entered in the telnet terminal is routed through the SOCKS proxy and back to the original connection that was made to the proxy.

Note Please pay close attention to the first piece of data that was received.

<Buffer 00 5a ca 61 43 a8 09 01>

        [005a] [PORT:2} [IP:4]

This piece of data is technically part of the SOCKS BIND specifications, but because of my design decisions that were made in an effort to keep this library simple to use, you will need to make sure to ignore and/or deal with this initial packet that is received when a connection is made to the newly opened port.

Associate Example:

The associate command sets up a UDP relay for the remote SOCKS proxy server to relay UDP packets to the remote host of your choice.

var options = {
    proxy: {
        ipaddress: "202.101.228.108",
        port: 1080,
        type: 5,
        command: "associate" // Since we are using associate, we must specify it here.
    },
    target: {
        // When using associate, either set the ip and port to 0.0.0.0:0 or the expected source of incoming udp packets.
        // Note: Some SOCKS servers MAY block associate requests with 0.0.0.0:0 endpoints.
        // Note: ipv4, ipv6, and hostnames are supported here.
        host: "0.0.0.0",
        port: 0
    }
};


Socks.createConnection(options, function(err, socket, info) {
    if (err)
        console.log(err);
    else {
        // Associate request has completed.
        // info object contains the remote ip and udp port to send UDP packets to.
        console.log(info);
        // { port: 42803, host: '202.101.228.108' }

        var udp = new dgram.Socket('udp4');

        // In this example we are going to send "Hello" to 1.2.3.4:2323 through the SOCKS proxy.

        var pack = Socks.createUDPFrame({ host: "1.2.3.4", port: 2323}, new Buffer("hello"));

        // Send Packet to Proxy UDP endpoint given in the info object.
        udp.send(pack, 0, pack.length, info.port, info.host);
    }
});

Now assuming that the associate request went through correctly. Anything that is typed in the stdin will first be sent to the SOCKS proxy on the endpoint that was provided in the info object. Once the SOCKS proxy receives it, it will then forward on the actual UDP packet to the host you you wanted.

1.2.3.4:2323 should now receive our relayed UDP packet from 202.101.228.108 (SOCKS proxy)

// <Buffer 68 65 6c 6c 6f>

Using socks as an HTTP Agent

You can use socks as a http agent which will relay all your http connections through the socks server.

The object that Socks.Agent accepts is the same as Socks.createConnection, you don't need to set a target since you have to define it in http.request or http.get methods.

The second argument is a boolean which indicates whether the remote endpoint requires TLS.

var socksAgent = new Socks.Agent({
    proxy: {
        ipaddress: "202.101.228.108",
        port: 1080,
        type: 5,
    }},
    true, // we are connecting to a HTTPS server, false for HTTP server
    false // rejectUnauthorized option passed to tls.connect(). Only when secure is set to true
);

http.get({ hostname: 'google.com', port: '443', agent: socksAgent}, function (res) {
    // Connection header by default is keep-alive, we have to manually end the socket
    socksAgent.encryptedSocket.end();
});

Api Reference:

There are only three exported functions that you will ever need to use.

Socks.createConnection( options, callback(err, socket, info) )

Object Object containing options to use when creating this connection

function Callback that is called when connection completes or errors

Options:

var options = {

    // Information about proxy server
    proxy: {
        // IP Address of Proxy (Required)
        ipaddress: "1.2.3.4",

        // TCP Port of Proxy (Required)
        port: 1080,

        // Proxy Type [4, 5] (Required)
        // Note: 4 works for both 4 and 4a.
        type: 4,

        // SOCKS Connection Type (Optional)
        // - defaults to 'connect'

        // 'connect'    - establishes a regular SOCKS connection to the target host.
        // 'bind'       - establishes an open tcp port on the SOCKS for another client to connect to.
        // 'associate'  - establishes a udp association relay on the SOCKS server.
        command: "connect",


        // SOCKS 4 Specific:

        // UserId used when making a SOCKS 4/4a request. (Optional)
        userid: "someuserid",

        // SOCKS 5 Specific:

        // Authentication used for SOCKS 5 (when it's required) (Optional)
        authentication: {
            username: "Josh",
            password: "somepassword"
        }
    },

    // Information about target host and/or expected client of a bind association. (Required)
    target: {
        // When using 'connect':    IP Address or hostname (4a and 5 only) of a target to connect to.
        // When using 'bind':       IP Address of the expected client that will connect to the newly open tcp port.
        // When using 'associate':  IP Address and Port of the expected client that will send UDP packets to this UDP association relay.

        // Note:
        // When using SOCKS 4, only an ipv4 address can be used.
        // When using SOCKS 4a, an ipv4 address OR a hostname can be used.
        // When using SOCKS 5, ipv4, ipv6, or a hostname can be used.
        host: "1.2.3.4",

        // TCP port of target to connect to.
        port: 1080
    },

    // Amount of time to wait for a connection to be established. (Optional)
    // - defaults to 10000ms (10 seconds)
    timeout: 10000
};

Callback:

// err:  If an error occurs, err will be an Error object, otherwise null.
// socket: Socket with established connection to your target host.
// info: If using BIND or associate, this will be the remote endpoint to use.

function(err, socket, info) {
  // Hopefully no errors :-)
}

Socks.createUDPFrame( target, data, [frame] )

Object Target host object containing destination for UDP packet

Buffer Data Buffer to send in the UDP packet

Number Frame number in UDP packet. (defaults to 0)

Creates a UDP packet frame for using with UDP association relays.

returns Buffer The completed UDP packet container to be sent to the proxy for forwarding.

target:

// Target host information for where the UDP packet should be sent.
var target =
    {
        // ipv4, ipv6, or hostname for where to have the proxy send the UDP packet.
        host: "1.2.3.4",

        // udpport for where to send the UDP packet.
        port: 2323
    }

Socks.Agent( options, tls) )

Object Object containing options to use when creating this connection (see above in createConnection)

boolean Boolean indicating if we upgrade the connection to TLS on the socks server

Further Reading:

Please read the SOCKS 5 specifications for more information on how to use BIND and Associate. http://www.ietf.org/rfc/rfc1928.txt

License

This work is licensed under the MIT license.