witty/docs/en.search-data.min.6b854d792c3149a3e9d7fea498d4a129d5bb011901e75102f72de2c52e379737.json

[{"id":0,"href":"/docs/install/","title":"Installation","section":"Table of content","content":"Installation #  WiTTY runs on Linux (ARM and x86), macOS, and WSL2 (Windows subsystem for Linux, basically Linux). You can install from the pre-built binary or from the source code.\nFrom Binary   Visit the release page of WiTTY at https://github.com/syssecfsu/witty/releases\n  Download the release for your system\n  Decompress the binary with the following command at selected location.\ntar -xzvf witty_vx.x.x_xxx.tar.gz\n For example, use tar -xzvf witty_v1.1.1_linux_amd64.tar.gz to decompress release v1.1.1 for Linux on AMD64.\n   From Source Code   Install the go compiler. Make sure you have go 1.17 or higher.\n  Download the source code release and unzip it, or clone the repo\ngit clone https://github.com/syssecfsu/witty.git\n  Go to the root directory of the source code and build the program with\n./build.sh\nThis shell script will build WiTTY and copy the binary with other needed files to the release/ directory. You can move the release/ directory to other places you want. Run WiTTY from this directory.\n  macOS users can install go with homebrew. Note that macOS has its own version of golang installed. Do not remove it. Just add the path of newly installed golang at the beginning of the PATH environment variable.  WiTTY uses go:embed to embed assets in the binary. Remember to re-build WiTTY after changing templates.   Post-installation Configuration #    WiTTY uses TLS to protect its traffic. You can request a free Let\u0026rsquo;s Encrypt cert or use a self-signed cert. Here is how to create a self-signed cert in the tls sub-directory:\n# Generate a private key for a curve\nopenssl ecparam -name prime256v1 -genkey -noout -out private-key.pem\n# Create a self-signed certificate\nopenssl req -new -x509 -key private-key.pem -out cert.pem -days 360\n  Add a user to the user accounts, follow the instructions on screen to provide the password\n./witty adduser \u0026lt;username\u0026gt;\nWiTTY uses sub-commands for different functions. See details here    Start the server and specify the command-line (CLI) program to run when user connects.\n./witty run bash\nIf so desired, you can disable user authenticate with -n/-naked, (not recommended). In the following example, WiTTY will run the ls command without user authentication:\n./witty run -naked ls\n WiTTY normally listens on port 8080. It can be overridden with the -p/-port option:    Connect to the server with your browser at port 8080 or the one specified in step 3, for example\nhttps://\u0026lt;witty_server_ip\u0026gt;:8080\n  Example Use Case #  WiTTY doesn\u0026rsquo;t support Windows because Windows doesn\u0026rsquo;t have PTY. You can still use WiTTY to access Windows terminal through a proxy.\nHere is how to do it. We can run WiTTY on a Raspberry Pi running Raspbian (at address 192.168.1.2). When a user connects via browser to https://192.168.1.2:9000, WiTTY will start a new ssh session to the Windows machine (at address 192.168.1.3) running a SSH server. The command to run WiTTY on the RPI is as follows:\n./witty run -p 9000 ssh 192.168.1.3 -l user_name\nThe user can use any compatible browsers, such as that on a phone, to connect to the Windows machine without install a SSH client.\n mermaid.initialize({ \"flowchart\": { \"useMaxWidth\":true }, \"theme\": \"default\" } ) graph LR A[user on a phone] -- browser -- B[RPI: 192.168.1.2 runs WiTTY] B -- ssh -- C[Windows: 192.168.1.3 runs SSH server ] "},{"id":1,"href":"/docs/ui/","title":"User Interface","section":"Table of content","content":"Sub-commands #  Similar to git and apt, WiTTY uses sub-commands for its various functions. WiTTY currently supports the following sub-commands: adduser, deluser, listusers, replay, merge, run.\n   Sub-command Description     adduser Add/update an authenticated user with their password   deluser Delete an authenticated user   listusers List all the authenticated users   replay Replay a recorded session (set your terminal to 120x36 first)   merge Merge several recorded sessions into one session   run Run a specified CLI program when user connects with browser    Some sub-commands have options. Use -h to find out more. e.g.,\n$ ./witty run -h Usage of run: -n Run WiTTY without user authentication -naked Run WiTTY without user authentication -p uint Port number to listen on (default 8080) -port uint Port number to listen on (default 8080) -w uint Max wait time between outputs (default 1000) -wait uint Max wait time between outputs (default 1000) User Authentication #  WiTTY uses username/password based authentication. The user database is stored in user.db under the main directory of WiTTY. The passwords are salted with 64 bytes of random characters and then hashed using SHA256. In addition, passwords must be 12 bytes or longer. WiTTY provides three sub-commands to manage user.db.\n witty adduser \u0026lt;username\u0026gt; witty deluser \u0026lt;username\u0026gt; witty listusers  They are pretty self-explanatory. Just follow the instructions on screen.\nWeb Interface (witty run) #  The web interface of WiTTY is mostly self-explanatory. After login, the user is presented with the main interface, as shown in this screenshot:\nThere are two tabs that list live and recorded sessions, respectively. You can click New Session to create a new interactive session, which opens in a new browser tab. The main window will list the newly created interactive session similar to the follows:\nWiTTY randomly names an interactive session as its unique ID. You can click the icon of an interactive session to open a read-only view of that session.\nOn the interactive terminal window, you can record an ongoing session by clicking the record button.\nAfter a session has been recorded, the main window\u0026rsquo;s Recorded Sessions will list the records, as shown below. You can replay , download , rename , and delete recorded sessions.\nHere is a screencast where we replay a recorded session that updates the pi-hole system. You can fully control the playback using the progress bar. Clicking on the progress bar stops the replay and fast-forwards (or fast-backwards) the screen to that location. You can scroll the screen to view the history when replay is stopped and resume the replay.\n"},{"id":2,"href":"/docs/record/","title":"Record Sessions","section":"Table of content","content":"Record Sessions #  You can record an ongoing session in the interactive terminal window.\nRecorded sessions will be listed in the main window of WiTTY. You can click the button to rename a recorded session. By default, a recorded session is named based on its session ID and the current time, not very meaningful for human. Rename them to something easy to remember, such as task1, task2,\u0026hellip;\nWiTTY provides two sub-commands to merge and replay recorded sessions.\n witty merge -o \u0026lt;output_file\u0026gt; \u0026lt;record1\u0026gt; \u0026lt;record2\u0026gt; ... witty replay -w \u0026lt;wait_time\u0026gt; \u0026lt;recorded_session\u0026gt;  Recorded sessions often have long delay between outputs. You can set wait_time of the replay command to limit the maximum wait time between outputs, to speed up the replay.\nThe following screenshot shows how to use witty merge to merge three recorded sessions into alltasks.scr.\nThe intended use of this is to record a separate session for each individual task, rename and merge them into a final session for submission to a project.  All the recorded sessions are located under the records directory.  "},{"id":3,"href":"/docs/vm/","title":"VirtualBox","section":"Table of content","content":"Use WiTTY with SEED VM #  The SEED labs provides a number of security hands-on labs. It is a popular security lab course taught at many universities. The SEED labs use VirtualBox to run its VMs (because VirtualBox is cross-platform.)\nBy default, the SEED VM uses only NAT-based network, which means that the VM can access the Internet but not the host machine (i.e., the machine that runs VirtualBox is called the host, and the VM is often called the guest.) We need to add a second, host-only network adaptor in order to run WiTTY in the guest and access WiTTY from a browser in the host.\nTo do that, first open the Host Network Manager and create a host network if there is not one already, as shown below (on macOS.): Then, open the setting for the SEED VM, go to the Network setting, and enable the second adaptor, choose the host-only adaptor. Leave the first adaptor as is.\nAfter this, start the VM and list all the adaptors using the command ifconfig in a terminal. Look for the adaptor with an IP address starting with 192.168.. You should be able to ssh into the guest using this IP address from the host. Follow the instruction here to install and use WiTTY.\nIf the host runs Windows, make sure virtualbox host adapter is not disabled in the Windows network settings if VirtualBox cannot find the host-only Ethernet adapter.  "},{"id":4,"href":"/docs/about/","title":"About","section":"Table of content","content":"About WiTTY #  WiTTY is written in the go programming language, using the Gin web framework, gorilla/websocket, pty, and the wonderful xterm.js! The workflow is simple, the client initiates a terminal window (xterm.js) and creates a websocket with the server, which relays the data between pty and xterm.\nThe program has been tested on Linux, WSL2, Raspberry Pi 3B (Debian), and MacOSX using Google Chrome, Firefox, and Safari.\nMost icons were provided by fontawesome under this license.\n"},{"id":5,"href":"/menu/","title":"Index","section":"Introduction","content":" Installation User Interface Record Sessions VirtualBox About   "}]