GitHub/witty
3
0
Fork 0
mirror of https://github.com/syssecfsu/witty.git synced 2024-12-24 11:42:34 +01:00
Code Issues Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
syssecfsu 2022-01-17 16:19:53 -05:00 committed by GitHub
parent eab8274988
commit 739673e19e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
README.md
View File

@ -1,8 +1,20 @@
# WiTTY: Web-based interactive TTY # WiTTY: Web-based interactive TTY
This program allows you to use terminal in the browser. Simply run the program and give it the command to execute when users connect via the browser. ___Interestingly___, it allows others to view your interactive sessions as well. This could be useful to provide remote support and/or help. You can use the program to run any command line programs, such as ```bash```, ```htop```, ```vi```, ```ssh```. This following screenshot shows that three interactive session running ```zsh``` on macOS Monterey. <img src="https://github.com/syssecfsu/witty/blob/master/extra/main.png?raw=true" width="800px"> This program allows you to use terminal in the browser. Simply run the program and give it the command to execute when users connect via the browser. The main design goal of this tool is to help teaching courses that use Unix-like CLI environment. WiTTY has the following features that distinguish itself from other similar tools:
With WiTTY, you can also __record and replay your interactive sessions__. The following screenshot shows three recorded sessions. You can replay/download/delete them. 1. It allows others to **view onging interactive sessions**. This is useful for providing live remote support and/or help (only use this after user authentication is implemented).
<img src="https://github.com/syssecfsu/witty/blob/master/extra/view.png?raw=true" width="800px">
A challenge of this use case is that our home networks are almost always behind NAT, making it diffcult to run WiTTY as a publicly accessible server. Security is also a concern. It is generally safer to use WiTTY in a trusted environment.
2. WiTTY allows users to **easily record, replay, and share console sessions** with just a few clicks. This make it a breeze to answer course-related questions, espeically with the source code. Instead of wall of text to describe their questions, students can just send a recorded session.
This repository contains a recorded session in the ```assets/extra``` directory ([M1NXZvHdvA8vSCKp_61e5d60f.rec](extra/M1NXZvHdvA8vSCKp_61e5d60f.rec)) that shows me upgrading pihole. Just put the file under the ```records``` directory, run the server, you should find the recording in the ```Saved Sessions``` tab.
3. More features are planned, including user authentication. Suggestions are welcome.
You can use WiTTY to run any command line programs, such as ```bash```, ```htop```, ```vi```, ```ssh```. This following screenshot shows that three interactive session running ```zsh``` on macOS Monterey. <img src="extra/main.png" width="800px">
The following screenshot shows three recorded sessions. You can replay/download/delete them.
<img src="extra/view.png" width="800px">
Here is a session, where we sshed into a Raspberry Pi running Here is a session, where we sshed into a Raspberry Pi running
@ -10,7 +22,7 @@ Here is a session, where we sshed into a Raspberry Pi running
(```./witty ssh 192.168.1.2 -l pi```, (```./witty ssh 192.168.1.2 -l pi```,
WiTTY runs in a WSL2 VM on Windows) being replayed. You can play/pause the session. WiTTY runs in a WSL2 VM on Windows) being replayed. You can play/pause the session.
<img src="https://github.com/syssecfsu/witty/blob/master/extra/replay.gif?raw=true" width="800px"> <img src="extra/replay.gif?raw=true" width="800px">
<!-- <!--
commands to create high quality gif from mkv/mp4 files commands to create high quality gif from mkv/mp4 files
@ -22,9 +34,9 @@ gifsicle -O3 .\output.gif -o replay.gif
To use the program, you need to provide a TLS cert. You can request a free [Let's Encrypt](https://letsencrypt.org/) cert or use a self-signed cert. The program currently does not support user authentication. Therefore, do not run it in untrusted networks or leave it running. A probably safe use of the program is to run ```ssh```. Please ensure that you do not automatically login to the ssh server (e.g., via key authentication). To use the program, you need to provide a TLS cert. You can request a free [Let's Encrypt](https://letsencrypt.org/) cert or use a self-signed cert. The program currently does not support user authentication. Therefore, do not run it in untrusted networks or leave it running. A probably safe use of the program is to run ```ssh```. Please ensure that you do not automatically login to the ssh server (e.g., via key authentication).
___AGAIN, Do NOT run this in an untrusted network. You will expose your __AGAIN, Do NOT run this in an untrusted network. You will expose your
shell to anyone that can access your network and Do NOT leave shell to anyone that can access your network and Do NOT leave
the server running.___ the server running.__
This program is written in the [go programming language](https://go.dev/), using the This program is written in the [go programming language](https://go.dev/), using the
[Gin web framework](https://github.com/gin-gonic/gin), [gorilla/websocket](https://github.com/gorilla/websocket), [pty](https://github.com/creack/pty), and the wonderful [xterm.js](https://xtermjs.org/)! [Gin web framework](https://github.com/gin-gonic/gin), [gorilla/websocket](https://github.com/gorilla/websocket), [pty](https://github.com/creack/pty), and the wonderful [xterm.js](https://xtermjs.org/)!
@ -34,7 +46,7 @@ window (xterm.js) and create a websocket with the server, which relays the data
## Installation ## Installation
1. Install the [go](https://go.dev/) compiler. Make sure your have go 1.17 or higher. 1. Install the [go](https://go.dev/) compiler. __Make sure your have go 1.17 or higher.__
2. Download the release and unzip it, or clone the repo 2. Download the release and unzip it, or clone the repo
```git clone https://github.com/syssecfsu/witty.git``` ```git clone https://github.com/syssecfsu/witty.git```
@ -57,10 +69,10 @@ window (xterm.js) and create a websocket with the server, which relays the data
```./witty htop``` or ```./witty htop``` or
```./witty ssh <your_server_ip> -l <user_name>``` ```./witty ssh <ssh_server_ip> -l <user_name>```
6. Connect to the server, for example 6. Connect to the server, for example
```https://your_ip_address:8080``` ```https://<witty_server_ip>:8080```
The program has been tested on Linux, WSL2, Raspberry Pi 3B (Debian), and MacOSX using Google Chrome, Firefox, and Safari. The program has been tested on Linux, WSL2, Raspberry Pi 3B (Debian), and MacOSX using Google Chrome, Firefox, and Safari.