This repository is now archived and no longer maintained. This was simply a small side project of mine. You'd be better off using Cockpit, which is much more mature and feature-rich.

carrotsh

A lightweight and secure remote access server that allows clients to connect through a browser.

Table of Contents

• Introduction
• Prerequisites
• Installation
• Usage
• Configuration
• Encryption
• Two-Factor Authentication
• Blocklists
• Start on boot
• Reverse proxies
• Todo
• Contributing

Introduction [^]

carrotsh is a lightweight and secure remote access server that uses the websocket protocol, with full https support for encrypted connections. It aims to provide an ssh-like experience, but through a browser. xterm.js is used as the frontend terminal. No installation of extensions or userscripts is necessary on the client side to access a carrotsh instance, only a modern browser with javascript support is required.

Security features:

• HTTPS support
• Two-Factor authentication
• Automatic and manual IP blocklisting

~~Try the interactive demo~~ (Currently down)

Prerequisites [^]

Supported operating systems:

• macOS (Tested on Big Sur)
• GNU/Linux (Tested on Arch, Debian Bullseye, and RHEL 9)
• BSD (Tested on FreeBSD 13.1 and OpenBSD 7.1)
• musl/Linux (Tested on Alpine 3.16)
• Android (Tested on Android 11 and 12 using Termux)

Required software:

• node.js v16 or above
• npm v6 or above
• python v3.7 or above
• python-poetry v1 or above
• pyotp v2.8.0 or above
• make and g++ (Linux, Android) or Xcode (MacOS) - (For building node-pty during installation)
• rustc - (Required only if there isn't a pre-built cryptography package for your architecture)

Installation [^]

# Clone the repository
git clone https://github.com/AnnikaV9/carrotsh.git
 
# Change the working directory
cd carrotsh

# Install the dependencies
python3 csh install-deps

# Edit the configuration file
vim config.yaml

# Activate the virtualenv
poetry shell

# Set the server password
python3 csh setpass

Note: Do not install or run carrotsh as root. It is unnecessary and only reduces security.

Usage [^]

Note: Make sure to run poetry shell before interacting with the carrotsh cli.

$ python3 csh --help

usage: python3 csh <COMMAND> [args]

commands:

    help                                  show this message
    version                               output the version information
    start                                 run a syntax check and start the carrosh server
    stop                                  stop the carrotsh server
    status                                show the current status of the server
    setpass                               set the server password
    setup-2fa                             setup 2-factor authentication
    clear-auto-blocklist                  clear the auto blocklist
    clear-user-blocklist                  clear the user blocklist
    add-blocklist-address <address>       add an address to the user blocklist
    install-blocklist </path/to/list>     copy addresses in a file to the user blocklist
    config-dump                           dump all configuration options to the terminal
    install-deps                          install npm and pip dependencies

Configuration [^]

config.yaml is the primary configuration file.

Available options:

Most of these options can be changed without requiring you to restart carrotsh.

The below options however, do require a restart:

• port
• python_path
• https
• https_options

Encryption [^]

carrotsh requires proper usage and configuration in order to be secure. Make sure to set up https, so connections are encrypted and cannot be sniffed. Here's an example openssl command for creating a self-signed ssl certificate:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout key.pem -out cert.pem

Enable https and add the two .pem files in the configuration.

An alternative to https would be a secure and trustable VPN.

Two-Factor Authentication [^]

To set up TOTP 2fa, first enable it in the configuration. Then run:

python3 csh setup-2fa

This will save a base32 secret key and print it to the console. Add this secret key to your preferred authenticator app and keep another copy somewhere safe in case you ever lose or reset your device.

A recommended open source authenticator app for android is Aegis

Blocklists [^]

Blocklists allow you to prevent clients with blocked remote addresses from ever reaching the login prompt. There are two blocklists carrotsh uses:

auto_blocklist.json

The auto blocklist is used when auto_blocklist in the configuration is set to true. It will automatically add addresses when clients perform a set number of incorrect password attempts (Default: 5), and remove them from the list after a set period (Default: 1 week). The auto blocklist should only be modified if there are false positives. (eg. You get yourself blocked after entering the incorrect password)

To clear the auto blocklist:

python3 csh clear-auto-blocklist

user_blocklist.json

The user blocklist is for you to edit and add addresses manually. To add a single address:

python3 csh add-blocklist-address <address>

To add a list with multiple addresses:

python3 csh install-blocklist </path/to/list>

This will append the addresses in the list to the user blocklist, removing any # comments.

The user blocklist can be cleared the same way as the auto blocklist:

python3 csh clear-user-blocklist

Start on boot [^]

Note: This method has only been tested to work with systemd.

To start carrotsh's process manager on boot:

sudo ./node_modules/pm2/bin/pm2 startup -u $USER --hp $HOME

And after starting up carrotsh normally, run:

./node_modules/pm2/bin/pm2 save

Now pm2 wil start on system boot and run carrotsh. If you ever restart carrotsh manually, run the save command again.

Reverse proxies [^]

carrotsh currently does not have proper support for use with reverse proxies like nginx. It may work, but the auto blocklist may end up blocking everyone from connecting since it only sees the proxy's address. Using X-Forwarded-For requires a significant change to the code, as the header can be easily spoofed when connecting directly past the proxy. Until a proper solution is implemented, it is not recommended to run carrotsh behind a reverse proxy. If you do have a working solution, feel free to contribute.

Todo [^]

• Reverse proxy mode that only accepts connections from the configured proxy address
• Client side theme/font configuration interface   |   Currently WIP
• Updater that doesn't break the config and blocklists
• Optional built-in shell with command access controls and other features that improve security

Contributing [^]

All contributions are welcome, just create a pull request!

Credits to everyone here