Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/max1220/cgi_command

CGI script and JS library for arbitrary command execution. Supports streaming responses using Server Sent Events.
https://github.com/max1220/cgi_command

bash cgi-script javascript-library

Last synced: 14 days ago
JSON representation

CGI script and JS library for arbitrary command execution. Supports streaming responses using Server Sent Events.

Awesome Lists containing this project

README 

        
# cgi_command



This library and CGI script is designed to execute arbitrary commands via CGI.



It is designed to provide simple shell script-like administration/automation

functionality for the browser with a dead-simple bash CGI-based backend.



The JavaScript part of this library makes common operations

(such as getting a complete response from a command, streaming a response,

uploading/downloading files from the server, etc.)

easy, and the CGI script serves as the backend for this.



The CGI script is designed to be as flexible as possible,

and can set any response headers, including content-type, allows setting

environment variables and changing directories before executing,

supports various encodings(such as an unmodified, event stream, base64),

and allows all HTTP methods(parameters are always URL-encoded).



# cgi-bin/cgi_command.sh



This is the server-side CGI script that runs the command and encodes the output.



## !!! WARNING !!!



Warning: Leaving this CGI script runnable unprotected is obviously very dangerous!



It should almost always be protected by some sort of authentication.

Giving access to this script should be treated the same as giving access to

a shell belonging to the user that runs the CGI script.



## Requirements



This CGI script just requires basic shell tools(bash, coreutils), and a

CGI capable webserver.



For testing, it is convenient to use the BusyBox httpd server.

An example configuration `busybox_httpd.conf` file is provided.



You can start a test instance like this(from this directory):



```

busybox httpd -v -f -p 127.0.0.1:8080 -c busybox_httpd.conf

```



You should change the default username/password(`user`/`password`) in `busybox_httpd.conf`.



## nginx



If you want to use nginx to host this script, you can use fcgiwrapd to listen

for fcgi requests on a unix socket, and have that run the CGI script.

This makes it easy to export the shell as another user as well

(www-data probably has shell access disabled). Make sure fcgiwrapd has multiple

processes preforked.



You need to make sure to disable buffering as well, or you can't properly

stream the responses using the server-sent events/EventSource mechanism.



See the included `nginx.conf` for an example.



## QUERY_STRING parameters



Supported parameters in the QUERY_STRING. Some options can be specified multiple times.



 * `cmd` - command to run(required, can be specified multiple times to supply arguments)

 * `encoding` - One of "eventstream_bytes", "eventstream_lines", "base64" or "none"(required)

 * `header` - A header to include(complete "Header: value" line, can be specified multiple times)

 * `env` - Export an environment variable(in exports "ENV_VAR=value" format)

 * `cwd` - Change working directory before running command

 * `content_type` - If set, respond with the specified Content-Type. Defaults to text/plain

 * `merge_stderr` - If set to true, stderr is merged with stdout



# CgiCommand.js



This JavaScript library contains the base functionality for generating URLs and

executing requests to the CGI script.



## `CgiCommand` Constructor



The constructor arguments are put into the properties, and never used directly.



```

CgiCommand(command, base_url=CGI_BACKEND, encoding="none", headers=[], env=[], content_type="text/plain", merge_stderr=true)

```



## Properties



 * command

 * base_url

 * encoding

 * headers

 * env

 * merge_stderr

 * content_type



## Methods



All methods make use of properties, not constructor arguments directly.



 * get_url()

   - Return the URL base on the current properties

 * xhr_sync(method="GET", body)

   - Perform a synchronous XHR, and return the request

 * xhr(method="GET", body, resp_cb, progress_cb)

   - Perform an asynchronous XHR, and register the callback(returns the request immediately)

 * stream(open_cb, data_cb, ret_cb)

   - Start streaming events using the Server-Sent Events/EventSource() mechanism.



# ShellUtils.js



This JavaScript library contains shell related utillity functions.



These basic utillity functions use synchronous XHRs and are intended to provide

simple shell script-like administration/automation functionality for the browser.



## escape_shell(str) 



escape shell special characters in str.



## `ShellUtils` Constructor



You need to provide the URL to the `cgi_command.sh` script as the only parameter.



```

ShellUtils(base_url)

```



## Properties



The only property of a ShellUtils instance is `base_url`, which is used for

creating the requests.



## Methods



All methods use synchronous XHRs.



 * run(cmd, body)

   - Runs the command(array of strings), optionally with body sent to stdin

 * run_script(script_str)

   - Runs the script_str by providing it on stdin to bash.

 * upload_to_path(data, path)

   - Upload the specified data(string) to path

 * get_file_url(path, content_type="application/octet-stream")

   - Get a URL to this file on the server(`cat $path` with content_type)

 * get_env()

   - Get the parsed environment the CGI script runs with(`printenv`)