{"id":13645248,"url":"https://github.com/heroku/shaas","last_synced_at":"2025-04-21T13:32:23.587Z","repository":{"id":30787507,"uuid":"34344448","full_name":"heroku/shaas","owner":"heroku","description":"Shell as a Service: API to inspect and execute scripts in a server's environment via HTTP and WebSockets","archived":false,"fork":false,"pushed_at":"2025-04-09T20:31:42.000Z","size":371,"stargazers_count":80,"open_issues_count":7,"forks_count":11,"subscribers_count":93,"default_branch":"master","last_synced_at":"2025-04-09T21:35:20.212Z","etag":null,"topics":["bash","http","rest","shell","testing","websockets"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heroku.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-21T18:21:10.000Z","updated_at":"2025-04-09T20:31:44.000Z","dependencies_parsed_at":"2024-01-14T09:30:12.670Z","dependency_job_id":"415952bc-153b-44e2-80ba-3c6476c14957","html_url":"https://github.com/heroku/shaas","commit_stats":{"total_commits":110,"total_committers":13,"mean_commits":8.461538461538462,"dds":0.4363636363636364,"last_synced_commit":"db27bf8f2cc7bc8a8aa0dd071f7036c4084cf76b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fshaas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fshaas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fshaas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fshaas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heroku","download_url":"https://codeload.github.com/heroku/shaas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250064792,"owners_count":21368973,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","http","rest","shell","testing","websockets"],"created_at":"2024-08-02T01:02:32.084Z","updated_at":"2025-04-21T13:32:23.016Z","avatar_url":"https://github.com/heroku.png","language":"Go","readme":"# shaas\nShell as a Service\n\n## Overview\nAPI to inspect and execute scripts in a server's environment via HTTP and WebSockets.\n\n**This is obviously a *really bad idea* on a server that you care about, but this is a convenience for testing purposes only. This offers no protection whatsoever for the server. This makes the server's entire file system accessible to clients. Please use with great caution.**\n\n## Running\n\nBecause this application gives clients full access to the server, it is highly recommended to run it inside of some kind of containerized environment, such as [Heroku](http://www.heroku.com) or [Docker](https://www.docker.com/). Even in a containerized environment, you may wish to set a username and password, for use via HTTP basic authentication, by setting `BASIC_AUTH=user:password` in the environment before starting. To only allow `GET` requests and disallow websockets, set `READ_ONLY` in the environment.\n\n### Heroku\n\n[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy?template=https://github.com/heroku/shaas)\n\n### Docker\n\nRunning with [Docker Compose](https://docs.docker.com/compose):\n\n    $ docker-compose up -d\n    $ curl http://localhost:5000/\n\n## Usage\n\nSummary of endpoint behavior for all path, method, and protocol combinations:\n\n|           |                 POST                  |         GET         |      PUT/APPEND       |                      WebSocket                      |\n|-----------|---------------------------------------|---------------------|-----------------------|-----------------------------------------------------|\n| File      | runs path in context of its directory | downloads path      | uploads body to path  | interactively runs path in context of its directory |\n| Directory | runs body in context of path          | lists files in path | n/a                   | runs interactive shell in context of path           |\n\n### Executing Commands\n\nTo execute a command in the context of a given directory on the server, simply `POST` the command with the directory as the URL path. For example, running `pwd` in the directory `/usr/bin` returns the path in the response:\n\n    $ curl http://shaas.example.com/usr/bin -i -X POST -d 'pwd'\n    HTTP/1.1 200 OK\n    Date: Tue, 21 Apr 2015 17:22:07 GMT\n    Content-Type: text/plain; charset=utf-8\n    Transfer-Encoding: chunked\n\n    /usr/bin\n\nThis is the most versatile endpoint. The functionality of all the other endpoints could be achieved with a `POST` to a directory path, but are offered as a convenience.\n\n### Executing Scripts\n\nTo execute a script on the server, simply `POST` the script path as the URL path and any input to the script in the body. For example, to find the factors of the number 24:\n\n    $ curl http://shaas.example.com/usr/bin/factor -i -X POST -d '24'\n    HTTP/1.1 200 OK\n    Server: Cowboy\n    Connection: keep-alive\n    Date: Fri, 15 May 2015 16:40:08 GMT\n    Content-Type: text/plain; charset=utf-8\n    Transfer-Encoding: chunked\n    Via: 1.1 vegur\n    \n    24: 2 2 2 3\n    \nBecause `/usr/bin` is on the `PATH`, this could also be run with just the command in the body:\n\n    $ curl http://shaas.example.com/ -i -X POST -d 'factor 24'\n    HTTP/1.1 200 OK\n    Server: Cowboy\n    Connection: keep-alive\n    Date: Fri, 15 May 2015 16:45:43 GMT\n    Content-Type: text/plain; charset=utf-8\n    Transfer-Encoding: chunked\n    Via: 1.1 vegur\n    \n    24: 2 2 2 3\n\n### CGI Environment Variables\n\nAll commands and scripts are automatically run with [CGI](http://en.wikipedia.org/wiki/Common_Gateway_Interface) environment variables for access to HTTP headers, query parameters, and other metadata:\n    \n    $ curl http://shaas.example.com/ -X POST -d 'env | sort'\n    CONTENT_LENGTH=10\n    CONTENT_TYPE=application/x-www-form-urlencoded\n    GATEWAY_INTERFACE=CGI/1.1\n    HTTP_ACCEPT=*/*\n    HTTP_CONNECTION=close\n    HTTP_CONNECT_TIME=5\n    HTTP_CONTENT_LENGTH=10\n    HTTP_CONTENT_TYPE=application/x-www-form-urlencoded\n    HTTP_HOST=shaas.example.com\n    HTTP_TOTAL_ROUTE_TIME=0\n    HTTP_USER_AGENT=curl/7.37.1\n    HTTP_VIA=1.1 vegur\n    HTTP_X_FORWARDED_FOR=73.170.209.186\n    HTTP_X_FORWARDED_PORT=80\n    HTTP_X_FORWARDED_PROTO=http\n    HTTP_X_REQUEST_ID=9003884b-310a-4095-8ff1-0894494aff75\n    HTTP_X_REQUEST_START=1429846020992\n    PATH_INFO=/\n    PWD=/\n    QUERY_STRING=\n    REMOTE_ADDR=10.216.205.205:30916\n    REMOTE_HOST=10.216.205.205:30916\n    REQUEST_METHOD=POST\n    REQUEST_URI=/\n    SCRIPT_FILENAME=/\n    SCRIPT_NAME=/\n    SERVER_NAME=shaas.example.com\n    SERVER_PORT=23389\n    SERVER_PROTOCOL=HTTP/1.1\n    SERVER_SOFTWARE=go\n    SHLVL=1\n    _=/usr/bin/env\n\n### Interactive Sessions\n\nBy accessing the endpoints above via WebSockets, the commands are run interactively. If the path is a directory, an interactive `bash` session is started in that directory. If the path is a script, it is run in an interactive session. For example, using the [wssh](https://github.com/progrium/wssh) client:\n\n    $ wssh ws://shaas.example.com/\n    / $ echo 'hello'\n    echo 'hello'\n    hello\n\n### Listing a Directory\n\nDirectories are listed in JSON format for easy parsing:\n\n\n    $ curl http://shaas.example.com/usr -i -X GET\n    HTTP/1.1 200 OK\n    Server: Cowboy\n    Connection: keep-alive\n    Content-Type: application/json\n    Date: Fri, 15 May 2015 16:52:29 GMT\n    Content-Length: 996\n    Via: 1.1 vegur\n    \n    {\n      \"bin\": {\n        \"size\": 36864,\n        \"type\": \"d\",\n        \"permission\": 493,\n        \"updated_at\": \"2015-03-20T09:28:58.547556085Z\"\n      },\n      \"games\": {\n        \"size\": 4096,\n        \"type\": \"d\",\n        \"permission\": 493,\n        \"updated_at\": \"2014-04-10T22:12:14Z\"\n      }\n    }\n\nIf viewing the directory in a browser (or any client with a `html` in the `Accept` header), the listing will be returned in HTML:\n\n    $ curl http://shaas.example.com/usr -i -X GET -H 'Accept: text/html'\n    HTTP/1.1 200 OK\n    Content-Type: text/html\n    Date: Tue, 21 Apr 2015 17:46:58 GMT\n    Content-Length: 185\n\n    \u003cul\u003e\n        \u003cli\u003e\u003ca href='bin'\u003e/bin\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href='games'\u003e/games\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n\nTo list a directory in plain text, use POST with the `ls` command and options of your choice:\n\n    $ curl http://shaas.example.com/usr -i -X POST -d 'ls -lA'\n      HTTP/1.1 200 OK\n      Server: Cowboy\n      Connection: keep-alive\n      Date: Fri, 15 May 2015 16:54:28 GMT\n      Content-Type: text/plain; charset=utf-8\n      Transfer-Encoding: chunked\n      Via: 1.1 vegur\n      \n      total 72\n      drwxr-xr-x   2 root root 36864 Mar 20 09:28 bin\n      drwxr-xr-x   2 root root  4096 Apr 10  2014 games\n\n### Downloading a File\n\nFiles are returned in their native format:\n\n    $ curl http://shaas.example.com/var/logs/server.log -i -X GET\n    HTTP/1.1 200 OK\n    Date: Tue, 21 Apr 2015 17:31:45 GMT\n    Content-Type: plain/text\n\n    ...\n\n### Uploading a File\n\n`PUT` creates or replaces a file with the request body:\n\n    $ curl http://shaas.example.com/var/logs/server.log -i -X PUT --data-binary 'hello 1'\n    HTTP/1.1 200 OK\n    Date: Tue, 28 Mar 2017 09:13:05 GMT\n    Content-Length: 0\n    Content-Type: text/plain; charset=utf-8\n\n    $ curl http://shaas.example.com/var/logs/server.log -i -X PUT --data-binary 'hello 2'\n    HTTP/1.1 200 OK\n    Date: Tue, 28 Mar 2017 09:13:05 GMT\n    Content-Length: 0\n    Content-Type: text/plain; charset=utf-8\n\n    $ curl localhost:5000/var/logs/server.log -i\n    HTTP/1.1 200 OK\n    Content-Length: 7\n    Date: Tue, 28 Mar 2017 09:13:38 GMT\n    Content-Type: text/plain; charset=utf-8\n\n    hello 2\n\n`APPEND` creates or appends a file with the request body:\n\n    $ curl http://shaas.example.com/var/logs/server.log -i -X APPEND --data-binary 'hello 1'\n    HTTP/1.1 200 OK\n    Date: Tue, 28 Mar 2017 09:13:05 GMT\n    Content-Length: 0\n    Content-Type: text/plain; charset=utf-8\n\n    $ curl http://shaas.example.com/var/logs/server.log -i -X APPEND --data-binary 'hello 2'\n    HTTP/1.1 200 OK\n    Date: Tue, 28 Mar 2017 09:13:05 GMT\n    Content-Length: 0\n    Content-Type: text/plain; charset=utf-8\n\n    $ curl localhost:5000/var/logs/server.log -i\n    HTTP/1.1 200 OK\n    Content-Length: 14\n    Date: Tue, 28 Mar 2017 11:56:43 GMT\n    Content-Type: text/plain; charset=utf-8\n\n    hello-1hello-2\n\n## Overriding HTTP Methods\n\nBecause not all clients support all HTTP methods, particularly `PUT` and the custom `APPEND` method, the method can alternatively be overridden with the `_method` query parameter alongd with the `POST` method. For example, the following are equivalent:\n\n    $ curl http://shaas.example.com/var/logs/server.log -i -X APPEND --data-binary 'hello 1'\n\n    $ curl http://shaas.example.com/var/logs/server.log?_method=APPEND -i -X POST --data-binary 'hello 1'\n\n## Testing\n\nDue to the nature of this application and the access it has to the host machine, testing is done functionality within a [Docker](https://www.docker.com) container. To run tests, be sure Docker is running, [Docker Compose](https://docs.docker.com/compose) is installed, and run:\n\n    $ go test -v ./... -ftest\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheroku%2Fshaas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheroku%2Fshaas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheroku%2Fshaas/lists"}