Dispatcher - 4poc/rccvm GitHub Wiki

(planning document)

The dispatcher runs as a HTTP service within the qemu vm, its a generic backend to run programs and receiving their responses through a REST interface. The dispatcher is blocking requests until the response is available so make sure to setup timeouts carefully. Requests and responses are JSON encoded objects. It will return either a 200 response or 500 if an error occurred, in which case a JSON with the error description will be included.

POST /execute

Will execute commands and return their response.

• creates a temporary directory
• write files specified in the request
• execute commands
  • as a different non-privileged user
  • with the working directory changed to temp
  • with the specified environment variables merged
• respond with the collected stderr/stdout and return codes

If the client or something else terminates the HTTP connection, spawned commands will be forcibly stopped.

Request Object

Property	Type	Default	Description
command	mixed		Specify a string that is executed as a shell command or a array of such shell commands that are executed in order.
env	object		Environment variables to execute with.
output.join	boolean	true	Joins the output (stdout/stderr/retcode) of all executed commands together, any return code unlike 0 will take precedence.
output.type	string	"plaintext"	Specify encoding used in the OutputObjects.
files	object		Object of filename, input object pairs that are written before execution. Filenames are relative to the temporary directory.

Response Object

Property	Type	Default	Description
output	mixed		Either array or object depends on output.join in the response.

POST /session/new

Creates a new interactive session, it returns a sessionId and the "initial prompt" output.

Request Object

Property	Type	Default	Description
command	string		Specify a shell command that starts a interactive prompt.
env	object		Environment variables to execute with.
output.type	string	"plaintext"	Specify encoding used in the OutputObjects.

Response Object

Property	Type	Default	Description
sessionId	string		Session identifier used to control the session.
output.stdout	OutputObject		The stdout output of the interactive command.
output.stderr	OutputObject		The stderr output of the interactive command.

POST /session/execute

Execute a command within the session and return its response. If possible it tries to omit the prompt.

POST /session/delete

Closes a session.

InputObject

You may provide input data for STDIN or files in UTF-8 encoded plaintext or Base64 binary.

Property	Type	Default	Description
type	string	"plaintext"	Input encoding plaintext or base64.
data	string		Input content in the encoding specified.

Examples

{
    "type": "plaintext",
    "data": "print('Hello World')"
}

The default value of type is plaintext so you may omit it:

{
    "data": "print('Hello World')"
}

{
    "type": "base64",
    "data": "sOmEBaSe64=="
}

OutputObject

You may request a specific output encoding in your request.

Property	Type	Default	Description
type	string	"plaintext"	Output encoding plaintext or base64.
data	string		Output content in the encoding specified.

Examples

{
    "type": "plaintext",
    "data": "Hello World\n"
}

{
    "type": "base64",
    "data": "sOmEBaSe64=="
}