transparent-proxy

    1.8.5 • Public • Published

    Intro

    transparent-proxy extends the native net.createServer and it acts as a real transparent http-proxy.

    This module was built on top of TCP-level to avoid header-stripping problem of nodejs http(s)-modules.

    It allows to upstream client-request dynamically to other proxies, or to certain iFace, and more...

    It supports Basic Proxy-Authentication.

    Quick Start

    Install

    npm i transparent-proxy

    Use

    const ProxyServer = require('transparent-proxy');
    
    //init ProxyServer
    const server = new ProxyServer();
    
    //starting server on port 8080
    server.listen(8080, '0.0.0.0', function () {
        console.log('TCP-Proxy-Server started!', server.address());
    });

    Options Object

    Param Type Description
    options Object The options object.
    [options.auth] Function Activate/Handle Proxy-Authentication. Returns or solves to Boolean.
    [options.upstream] Function The proxy to be used to upstreaming requests. Returns String.
    [options.tcpOutgoingAddress] Function The localAddress to use while sending requests. Returns String
    [options.injectData] Function The edited data to upstream. Returns Buffer or string
    [options.injectResponse] Function The edited response to return to connected client. Returns Buffer or string
    [options.keys] Function The keys to use while handshake. It will work only if intercept is true. Returns Object or false
    [options.verbose] Boolean Activate verbose mode.
    [options.intercept] Boolean Activate interception of encrypted communications. False as default.

    upstream, tcpOutgoingAddress, injectData & injectResponse Options

    The options are functions having follow parameters:

    Param Type Description
    data Buffer The received data.
    session Session Object containing info/data about Tunnel
    • upstream-Function need to return a String with format -> IP:PORT or USER:PWD@IP:PORT of used http-proxy. If 'localhost' is returned, then the host-self will be used as proxy.
    • tcpOutgoingAddress-Function need to return a String with format -> IP.

    Note: These functions will be executed before first tcp-socket-connection is established.

    • injectData-Function need to return a String or buffer for the new spoofed data. This will be upstreamed as request.
    • injectResponse-Function need to return a String or buffer for the new received data.

    Upstream to other proxies

    If you don't want to use the host of active instance self, then you need to upstream connections to another http-proxy. This can be done with upstream attribute.

    const ProxyServer = require('transparent-proxy');
    
    const server = new ProxyServer({
        upstream: function () {
              return 'x.x.x.x:3128'; // upstream to other proxy
        }
    });
    
    //starting server on port 8080
    server.listen(8080, '0.0.0.0', function () {
        console.log('TCP-Proxy-Server started!', server.address());
    });

    The auth Function

    This activate basic authorization mechanism. The Auth-function will be executed while handling Proxy-Authentications.

    Param Type Description
    username String The client username.
    password String The client password
    session Session Object containing info/data about Tunnel

    Note: It needs to return True/False or a Promise that resolves to boolean (isAuthenticated).

    const ProxyServer = require('transparent-proxy');
    
    const server = new ProxyServer({
        auth: function (username, password) {
            return username === 'bar' && password === 'foo';
        }
    });
    
    //starting server on port 8080
    server.listen(8080, '0.0.0.0', function () {
        console.log('TCP-Proxy-Server started!', server.address());
    });

    Interception

    The callbacks injectData & injectResponse could be used to intercept/spoof communication. These functions are executed with the data and session arguments.

    Intercepting HTTPS

    The boolean attribute intercept allows to break SSL-Communication between Source & Destination.

    This will activate Security-Alarm by most used browsers.

    The keys Function

    This function will work only if intercept is set to true.

    If activated needs to return an Object {key:'String', cert:'String'} like native tls_connect_options.key & tls_connect_options.cert or false statement.

    If no object is returned, then default keys will be used to update communication.

    Param Type Description
    session Session Object containing info/data about Tunnel

    Note: This function will be executed before TLS-Handshake.

    Session-Instance

    The Session-Instance is a Object containing info/data about Tunnel. It has following useful attributes/methods:

    • isHttps - Is session encrypted.
    • getTunnelStats() - Get Stats for this tunnel
    • getId() - Get Own ID-Session
    • isAuthenticated() - Is the session authenticated by user or not.

    .getBridgedConnections()

    const ProxyServer = require('transparent-proxy');
    const server = new ProxyServer();
    
    //starting server on port 8080
    server.listen(8080, '0.0.0.0', function () {
        console.log('Proxy-Server started!', server.address());
    });
    
    setInterval(function showOpenSockets() {
        const bridgedConnections = server.getBridgedConnections();
        console.log([new Date()], 'OPEN =>', Object.keys(bridgedConnections).length)
    }, 2000);

    Examples

    This example upstreams only requests for ifconfig.me to another proxy, for all other requests will be used localhost.

    const ProxyServer = require('transparent-proxy');
    
    const server = new ProxyServer({
        upstream: function (data, session) {
            if (~(data.toString().indexOf('ifconfig.me'))) {
                return 'x.x.x.x:3128'; // upstream to other proxy
            } else {
                return 'localhost'; //upstream to localhost
            }
        },
    });
    
    //starting server on port 8080
    server.listen(8080, '0.0.0.0', function () {
        console.log('TCP-Proxy-Server started!', server.address());
    });

    Testing with curl:

    curl -x 127.0.0.1:8080 https://ifconfig.me
    x.x.x.x
    curl -x 127.0.0.1:8080 https://ifconfig.co
    y.y.y.y

    For more examples look here.

    Install

    npm i transparent-proxy

    DownloadsWeekly Downloads

    343

    Version

    1.8.5

    License

    ISC

    Unpacked Size

    37.5 kB

    Total Files

    14

    Last publish

    Collaborators

    • avatar