timetoogo / tunshell

Remote shell into ephemeral environments 🐚 🦀

Tunshell

https://tunshell.com

Tunshell is a simple and secure method to remote shell into ephemeral environments such as deployment pipelines or serverless functions. The project is predominately written in Rust.

Why?

Why would I use this over my well-established SSH client?

Good question, you wouldn't! The use case for tunshell is predominantly quick, ad-hoc remote access to hosts which you may not have SSH access to, or even the ability to install an SSH daemon at all. The beauty of tunshell is that its client is a statically-linked, pre-compiled binary which can be installed by downloading it with a one-liner script. This makes it ideal to debug environments you normally wouldn't have shell access to, some examples:

Debugging Deployment Pipelines

Tunshell allows you to remote shell into GitHub Actions, BitBucket Pipelines etc by inserting a one-liner into your build scripts. If you've ever spent hours trying to track down an issue on a deployment pipeline that you couldn't replicate locally because of subtle environmental differences, this could come in handy.

Serverless Functions

Tunshell even supports extremely limited environments such as AWS Lambda or Google Cloud Functions. As these platforms often only allow for execution of code in a configured language, a variety of install scripts among popular languages are provided. This could be helpful to diagnose networking or connectivity issues which are specific to these environments.

Unsavory Use-cases

Tunshell could also be used as an exploitation tool to gain unauthorized access to remote hosts. Personally, I hope that this tool is not misused for nefarious purposes. If it becomes apparent that tunshell is helping malicious actors go about their activities, the free service will be discontinued.

How does it work?

Tunshell is comprised of 3 main components:

• Relay Server: a server which is able to coordinate with clients to establish connectivity
• Client Binary: a portable binary acting as a shell server or client.
• Website: The user interface for configuring a remote shell session with the relay server and providing install scripts for the client.

Install Script

The process is kicked off using tunshell.com. One can generate a "session" which represents a remote shell connection from one client to another.

For each session the website generates one install script for each side of the connection. Below is a diagram illustrating the noteworthy components embedded in each script.

• Installer script URL: A url pointing to a script which will install the client binary on the executing machine. These scripts detect the host's OS and CPU architecture to download the correct pre-compiled executable.
• Mode argument: can be target mode (T) or local mode (L). These instruct the client to operate as a shell server or client respectively.
• Session keys: a pair of random strings generated by the relay server corresponding to a session. Upon initialisation, these keys are passed back to the relay server. When a pair of clients have sent a corresponding keys, the relay server will begin establishing connectivity between the clients.
• Encryption secret: a random secret which is generated locally using javascript on the website. This secret is used to generate a unique encryption key to secure data transmission between the two clients.

Establishing Connectivity

After the install scripts have executed and the two clients have validated their session keys with the relay server, the following process of attempting to establish a network connection between the two begins.

There are three networking models supported that are attempted and used in the following priority order:

1. TCP: The clients will attempt to connect to the peer over TCP directly. If both clients are behind a firewall or NAT device, this will likely fail.

2. UDP: The implementation also contains thin TCP-like protocol built on UDP. In some cases this can help establish a direct connection if at least of the clients are behind a more permissive NAT device.

3. Relayed: In the case where no direct connection succeeds, the clients will fallback to proxying data through the relay server. The relay server will traffic packets between the clients using the existing TLS connections initiated by each client.

The relayed connection is also used for connections where one of the clients is running in a web browser. In which case a Web Socket is used between the client and the relay server on top of TLS.

In-built Shell

In some restricted environments the client will not have permission to allocate a PTY. This means that running the native shell in an interactive session is not going to be possible. The client has a bare-bones (read: incomplete) implementation of a VT100-style shell which does not require a PTY and is used as a fallback in such cases. This is still WIP.

Security Considerations

Before using tunshell is important to understand inherent risks. The nature of the application and installation method should trigger alarm bells in any developer's head given we are exposing shell access over a network. Although a lot of thought has gone into the limiting the attack surface there are is still a lot of room for improvement.

First and foremost, one must always be wary when running scripts from remote sources. The installation method of the tunshell client relies on the execution of a 3rd party script and binary on the host machine. If these were to be compromised so would your host. So it's critical that these are produced and delivered in a secure and transparent process. In summary, the artifacts are generated directly from the source in this repo, stored in AWS S3 and served via CloudFront CDN.

The next consideration is the operation of the client binary, which exposes shell access over a network channel. It is important to state that, although the traffic between clients can be passed through the relay server, effort has gone into ensuring that the relay server is not able to inspect, modify or forge traffic between any two clients. This is currently achieved by generating an encryption secret independently of the relay server which is then known to each of the clients.

In addition to the secret, during the connection establishment phase, the relay server will generate a unique nonce for each connection pair and send this nonce to each client. The clients use the encryption secret and nonce to derive an encryption key using PBKDF2-SHA256. The resulting key is unique to this connection and only known to the both clients. The traffic between the clients is then end-to-end encrypted and authenticated using AES-GCM-256.

It is important that the session and encryption keys remain secret. Exposing these parameters could allow attackers who obtain these keys to takeover hosts which have an active tunshell client.

Supported Targets for Client

The following is list of the supported platforms and architectures for the tunshell client:

Target	Builds	Tested
x86_64-unknown-linux-musl	Y	Y
armv7-unknown-linux-musleabihf	Y	N
arm-unknown-linux-musleabi	Y	Y
aarch64-unknown-linux-musl	Y	Y
arm-linux-androideabi	Y	N
i686-unknown-linux-musl	Y	Y
i586-unknown-linux-musl	Y	Y
x86_64-apple-darwin	Y	Y
x86_64-apple-ios	Y	N
x86_64-pc-windows-msvc	Y	Y
i686-pc-windows-msvc	Y	N

• Builds: indicates whether the client successfully built for the target
• Tested: indicates whether the test suites succeeds for the target, clients with N listed may be inoperable

These targets are managed by the build pipeline.

Self-hosted relay server

For additional security or customisation it is possible to self-host the relay server on your own infrastructure. The details of doing so can be found here.

tunshell's Issues

Not able to import TerminalEmulator from website/services/wasm/tunshell_client

I need to integrate the website part into my site, i am not able to import TerminalEmulator from website/services/wasm/tunshell_client since the wasm folder is not found inside the services folder. I have tried with cargo build, was not able to get the wasm folder inside services folder. Can you pls help me on this, to get this website up and running inside my website.

does Tunshell support peer to peer via local LAN without internet connectivity?

does Tunshell support peer to peer via local LAN without internet connectivity?

[question] secrets expiration time?

thanks for this awesome project!

newbie question: How long does a pair of secrets work? (I.e. for how long would I be able to use a pair of secrets generated on the public tunshell relay or on my own?) Is it somehow possible to use them indefinitely?

[Feature Request] Generate session via command line

I use this service quite often and think it would be very convenient to be able to generate sessions through a command line tool. Maybe the syntax could be something like:
$ tunshell curl
and then it would output the command to run on the remote host (or copy it directly to the clipboard if applicable) and start waiting for the peer connection.

For reference, the way I currently use Tunshell is through a GitHub Actions workflow_dispatch trigger with a command input, which is executed by the runner.

Thanks for running this service, it's really helped me out! 😃

Add a separate website page for direct connecting with peer key and encryptionSecret

Thanks for your brilliant work. I'm currently investigating the possibility to use tunshell in Github Actions in a better way.
With a simple POST, people can simply retrive a pair of peer-key, but with peer key, users cannot make use of tunshell's browser shell. At the same time, tmate will give a direct URL to open a shell.

I've reviewed tunshell website's code and the only place to show a xterm is by clicking the button, which doesn't allow manually specification of keys & secrets, thus users can't use a URL to directly start a session.

Could you please add a webpage to achieve functionality like tmate? Thanks!

curl | sh installer is poorly executed.

https://lets.tunshell.com/init.sh is poorly implemented.

• It will execute whatever happens to be at /tmp/tunshell/client and on most systems /tmp is world-writable.
• It is not wrapped in a function so incomplete downloads may have surprising results.

Possible fixes:

• Don't. Ideally an SSH port would just be provided and an ssh command line can be shown.
• Download the client to somewhere user owned such as $XDG_CACHE_HOME.
• Check that the /tmp/tunshell directory is owned by the current user before executing code from it.

Unexpected response returned by server

Unexpected response returned by server: Close

Connecting to relay server...
Waiting for peer to join...
42.106.4.6 joined the session
Negotiating connection...
Attempting direct connection to 42.106.4.6
[2023-11-16T09:41:34Z ERROR client] Error occurred: Unexpected response returned by server: Close

when i turn on IP filter in my remote device
i am getting this issue

i have allowed *.tunshell.com and my shell system IP in IP filter

do i need to allow any other IP?
can you please explain ?

Fails on Windows Github CI with powershell

Hi,
I have tried a task like this:

- name: tunshell
      run: |
        [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12; &$([scriptblock]::Create((New-Object System.Net.WebClient).DownloadString('https://lets.tunshell.com/init.ps1'))) xxxxx au.relay.tunshell.com
      shell: powershell

And I also tried shell: pwsh but they both give the following error on my side or the web browser version.

[2022-08-03T04:11:54Z ERROR client] Error occurred: shell server returned an error

    Caused by:
        expected value at line 1 column 1

Any ideas why?

FreeBSD

Please add support for FreeBSD. Currently it just says "Unsupported system".

curl -sSf https://lets.tunshell.com/init.sh | sh /dev/stdin T ... ... eu.relay.tunshell.com
Unsupported system (FreeBSD)

Reference:
cirruslabs/cirrus-ci-docs#432 (comment)

Pty on android

The client avoids creating a pty shell on android. What is the reason for that?

custom setup

Hi, I'm very interested in this solution, thanks for making it. The problem that I would like to solve using tunshell is managing potential thousands of IOT devices in private network (behind firewall).

I would like to know:

1. Is it easy to setup my custom relay server for generating peer keys? Do you plan to make details guide on it?
2. How can I execute custom command instead of having an interactive shell?
3. What's the current arch list supported? (basically I would like to use on x86_64 and mips )

Thanks in advance

Remote support use case

tunshell could be a promising way to do remote support, in case we only need to do some commands on remote computer, no need for full remote desktop solution like VNC or Teamviewer.

There is one missing piece only is: the remote user should be able to see what the remote support person is doing, i.e tunshell echos what is currently typing and the result of the command on the remote server.

@TimeToogo what is your thought about this?

Reverse Proxy

What a very nice library. I wonder could it be possible to use as a reverse proxy.
For example: https://www.howtoforge.com/reverse-ssh-tunneling

In-Browser Session Support

Hi, I'm user of action-tmate, which is another relay tool being widely used in Github Actions.
I'm wondering if tunshell have any plan to implement a terminal in browser just like tmate.io.

And I'm actually curious about the wasm build: can it be used in browser to implement this idea?

API appears down

When using tunshell.com:

An error occurred while calling the Tunshell API, please try again later.

Allow more than one connection (like ssh does)

Getting [ERROR client] Error occurred: Connection has already been joined by another host when trying to open more than one tunshell into a machine. Being able to do so would be extremely useful for debugging. For example, one could launch a problematic process in shell number 1 and debug it from shell number 2.

"An error occurred while calling the Tunshell API"

After clicking the "generate session" button on the website, the following message is returned:

An error occurred while calling the Tunshell API, please try again later.
If this issue persist please create a ticket here.