The RESTful shell

This is a RESTful shell that gives you command line access to a server that does not provide another means of shell access. If you are limited to an API to interact with your server, this tool may work for you.

Features

Shell access to a server that does not offer shell access.
Run commands remotely without using the system’s built in authentication system.
Not malware. You already have permission to execute code on the server.
Interactive shell lets you scroll through history.
Authentication and SSL encryption.
Readline support.

Installation

Installation is easy with pip, but you may need some OpenSSL development header files:

apt-get install libssl-dev
pip install git+https://github.com/treytabner/rest-shell.git

Components

There are two components, the server and the client.

The server is written in Python using Flask and is the application that you upload to your server for execution. Once it’s running, the API will be available at the specified port.

To connect to the API you can use the client, also written in Python. Supply the URL endpoint and you will be prompted to start entering commands.

Server

To start the server, use rest-shell with the server option and supply the URL for your endpoint. You will want to set the TOKEN environment variable for authentication purposes. For example:

TOKEN=hackme rest-shell --server localhost:8080

Client

To connect to the API with the command line client, use rest-shell and supply the URL for your endpoint. You will also need to set the TOKEN environment variable here to match the server, otherwise you won’t get access. For example:

TOKEN=hackme rest-shell localhost:8080
Welcome to the RESTful shell!
[https://trey@localhost:8080] df -h /boot
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1       228M   43M  173M  20% /boot
[https://trey@localhost:8080] uptime
23:00:07 up 6 days,  6:16,  6 users,  load average: 0.15, 0.19, 0.14
[https://trey@localhost:8080] ps
PID TTY          TIME CMD
  989 pts/2    00:00:00 bash
 5386 pts/2    00:00:00 rest-shell
 6084 pts/2    00:00:00 sh
 6085 pts/2    00:00:00 ps
[https://trey@localhost:8080] python -V 2>&1 | toilet -f smmono9
▗▄▄      ▗  ▐                ▄▄     ▗▄▄▖    ▗▄▄
▐ ▝▌▗ ▗ ▗▟▄ ▐▗▖  ▄▖ ▗▗▖     ▝ ▝▌      ▐▘    ▐    ▗
▐▄▟▘▝▖▞  ▐  ▐▘▐ ▐▘▜ ▐▘▐       ▗▘      ▞     ▝▀▚▖ ▐
▐    ▙▌  ▐  ▐ ▐ ▐ ▐ ▐ ▐      ▗▘      ▗▘        ▌▀▜▀▘
▐    ▜   ▝▄ ▐ ▐ ▝▙▛ ▐ ▐     ▗▙▄▖ ▐   ▞   ▐  ▝▄▟▘ ▐
     ▞
    ▝▘
[https://trey@localhost:8080] exit

API

Currently only JSON is supported.

Execute command

The /execute location provides the ability to execute a command. A sample request would look like:

{
    "command": "uname -sr"
}

A sample response would look like:

{
    "output": "Linux 3.10-1-amd64\n",
    "status": 0
}

Headers required are:

Content-Type, set to “application/json”
X-Auth-Token, set to the value for TOKEN specified on the server

With the endpoint at https://localhost:8080/execute, an example using cURL would look like:

curl -s -k -H 'Content-Type: application/json' -H 'X-Auth-Token: hackme' -d '{"command": "uname -sr"}' https://localhost:8080/execute

An example using HTTPie:

echo '{"command": "uname -sr"}' | http --verify=no https://localhost:8080/execute X-Auth-Token:hackme

Todo

In some order of priority:

Ability to fork off server into background
Add support for timing out on the server side
Ability to change remote and local directories (with prompt updates)
Ability ability to upload and download files in the client
Shell completion and history commands
Option to return stdout and stderr separately instead of combined in the server API
Deal with stdin limitations (currently limited to shell pipelining)

letssudormrf/rest-shell