Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jeffreytse/cactus-tunnel

🌵 A charming TCP tunnel over WebSocket and Browser.
https://github.com/jeffreytse/cactus-tunnel

awesome browser bypass cli fast http nodejs port-forward proxy proxy-server reverse-proxy socks-proxy ssh ssh-tunnel tcp tcp-proxy tcp-tunnel tunnel typescript websocket

Last synced: about 19 hours ago
JSON representation

🌵 A charming TCP tunnel over WebSocket and Browser.

Awesome Lists containing this project

README 

        


  



  

    cactus-tunnel logo

  



  
Cactus Tunnel








  🌵 A charming TCP tunnel over WebSocket and Browser.






  

    build

  



  

    NPM Version

  



  

    License: MIT

  



  

    Donate (Liberapay)

  



  

    Donate (Patreon)

  



  

  Donate (Ko-fi)

  






  Built with ❤︎ by

  jeffreytse and

  contributors 

  








Hey, nice to meet you, you found this charming tool. Here the _Cactus Tunnel_

is a TCP tunnel tool over WebSocket and Browser. It can help you open a TCP

tunnel to another side of the world through the browser in an extremely

restricted environment, just like a cactus under the scorching sun to absorb

nutrients in the endless desert. **If you are a thirsty and honey geek and

focus on finding new hydration, don't miss it.**





Like this charming tool? You can give it a star or sponsor me!


I will respect your crucial support and say THANK YOU!







  Tunnel Structure






## Installation



Install the tool from [NPM](https://www.npmjs.com/package/cactus-tunnel):



```sh

npm install -g cactus-tunnel

```



## Usages



The help instructions of this tool:



```sh

$ cactus-tunnel help



Usage: cactus-tunnel help [command]



TCP tunnel over websocket and browser



Options:

  -V, --version                       output the version number

  -h, --help                          display help for command



Commands:

  client [options]    runs cactus-tunnel in client mode

  server [options]                    runs cactus-tunnel in server mode

  help [command]                      display help for command

```



### Tunnel Server



The help instructions of tunnel server:



```sh

$ cactus-tunnel help server



Usage: cactus-tunnel server [options]



runs cactus-tunnel in server mode



Options:

  -p, --port          tunnel server listening port (default: 7800)

  -h, --hostname 
  tunnel server listening hostname (default: "0.0.0.0")

  -v, --verbose             enable verbose output

  --help                    display help for command

```



Start a tunnel server:



```sh

cactus-tunnel server



```



### Tunnel Client



The help instructions of tunnel client:



```sh

$ cactus-tunnel help client



Usage: cactus-tunnel client [options]  



runs cactus-tunnel in client mode



Arguments:

  server                            tunnel server url, empty is bridge mode, e.g.

                                    ws://your-tunnel-server:7800

  target                            tunnel target url, e.g. your-linux-ssh-server:22



Options:

  -p, --port                  tunnel client listening port (default: 7700)

  -h, --hostname 
          tunnel client listening hostname (default: "127.0.0.1")

  -b, --bridge-mode                 enable tunnel bridge mode

  -nb, --no-browser                 disable auto open browser when in bridge mode

  -bp, --bridge-port          tunnel bridge listening port (default: 7900)

  -bh, --bridge-hostname 
  tunnel bridge listening hostname (default: "0.0.0.0")

  -v, --verbose                     enable verbose output

  --help                            display help for command

```



### Request External API Services



Start a tunnel client:



```sh

cactus-tunnel client -b ws://:7800 ip-api.com:80

```



This command will start a server at address `localhost:7700` in bridge mode,

and open the tunnel bridge on the web browser.



```sh

curl http://localhost:7700/json/8.8.8.8

```



When you connect to the port `7700`, it will auto connect to the specified

tunnel server `:7800` and connect to target host

`ip-api.com:80`, you will get your server ip address through [the IP API lookup service](https://ip-api.com/),

the response content is similar as below:



```sh

$ curl http://localhost:7700/json/8.8.8.8 | jq

{

  "status": "success",

  "country": "United States",

  "countryCode": "US",

  "region": "VA",

  "regionName": "Virginia",

  "city": "Ashburn",

  "zip": "20149",

  "lat": 39.03,

  "lon": -77.5,

  "timezone": "America/New_York",

  "isp": "Google LLC",

  "org": "Google Public DNS",

  "as": "AS15169 Google LLC",

  "query": "8.8.8.8"

}

```



### SSH SOCKS5 Proxy



Start a tunnel client:



```sh

cactus-tunnel client -b ws://:7800 :22

```



This command will start a server at address `localhost:7700` in bridge mode,

and open the tunnel bridge on the web browser.



```sh

ssh -p 7700 -D 3128 -C -N @localhost

```



- `-D 3128`: open a SOCKS5 proxy on local port `3128`

- `-C`: compress data in the tunnel, save bandwidth

- `-N`: do not execute remote commands, useful for just forwarding ports



When you connect to the port `7700`, it will auto connect to the specified

tunnel server `localhost:7800` and connect to target host `:22`

Now you have an SSH tunnel between your computer and the remote host, in

this example `:22`.



### Import the package



A simple example:



```js

import cactusTunnel from "cactus-tunnel";



const options = {

  port: 1234,

  hostname: localhost,

};



const server = new cactusTunnel.Server({

  listen: {

    port: options.port,

    hostname: options.hostname,

  },

  logger: {

    silent: options.verbose ? false : true,

  },

});



console.info(`server listening at: http://${options.hostname}:${options.port}`);

```



## Development



To set up your environment to develop this tool, run `npm install`.



Your environment is setup just like a normal node project! To test your

project, run `npm start:cli help`. This shows help instructions of CLI

tool. You can edit the source code under `src`, `bin`, `test`, etc. like

normal to test NodeJS project. As you make modifications to the source

code and configuration files, you need to rerun the command and you

should see the changes, just like normal.



## Contributing



Issues and Pull Requests are greatly appreciated. If you've never

contributed to an open source project before I'm more than happy to walk

you through how to create a pull request.



You can start by [opening an issue](https://github.com/jeffreytse/cactus-tunnel/issues/new)

describing the problem that you're looking to resolve and we'll go from there.



## Credits



- [express](https://github.com/expressjs/express) - Fast, unopinionated, minimalist web framework for node.

- [websocket-stream](https://github.com/maxogden/websocket-stream) - WebSockets with the node stream API.

- [pump](https://github.com/mafintosh/pump) - Pipe streams together and close all of them if one of them closes.

- [winston](https://github.com/winstonjs/winston) - A logger for just about everything.



## License



This theme is licensed under the [MIT license](https://opensource.org/licenses/mit-license.php) © JeffreyTse.