rest-commander

A Rest-Application which can execute and manage processes.

API

• Authentication

  1. Login
  2. Logout

• Process

  1. List Process
  2. Start Process
  3. Start Process (as admin)
  4. Signal
  5. Input
  6. Status
  7. Output

Login

Login as a user.

• URL

  /auth/login

• Method:

  POST

• Header:

  Required:

  Content-Type: application/json

• Data Params

  {
    "username": "root",
    "password": "toor"
  }

• Success Response:

  • Code: 200
    Content:

    { 
      "token":"<token>"
    }

• Error Response:

  • Code: 400 Bad Request
    Content:

    {
      "message":"Username or password are incorrect!"
    }

• Sample Call:

  curl -X POST -H 'Content-Type: application/json' http://localhost:8080/auth/login --data '{"username": "root", "password": "toor"}'

Logout

Logout a user.

• URL

  /auth/logout

• Method:

  POST

• Header:

  Required:

  x-auth-token=[token]

• Success Response:

  • Code: 200

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
      "error":"Unauthorized", 
      "message":"Authentication Failed: Invalid token - <token>"
    }

• Sample Call:

  curl -X POST -H 'x-auth-token: <token>' http://localhost:8080/auth/logout

List Process

Gets a list of all running processes.

• URL

  /process

• Method:

  GET

• Header:

  Required:

  x-auth-token=[token]

• Success Response:

  A list of all running processes

  • Code: 200
    Content:

    [{ 
      "id": "1",
      "parent": "1",
      "commandline": "/bin/init",
      "user": "root",
      "environment": {
          "env1": "value1",
          "env2": "value2"
      },
      "running": true,
      "returnCode": null
    },{ 
      "id": "2",
      "parent": "1",
      "commandline": "/bin/sh",
      "user": "root",
      "environment": {
          "env1": "value1",
          "env2": "value2"
      },
      "running": true,
      "returnCode": null
    }]

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
      "error":"Unauthorized", 
      "message":"Authentication Failed: Invalid token - <token>"
    }

  • Code: 403 FORBIDDEN
    Content:

    {
      "error":"Forbidden", 
      "message":"Access Denied"
    }

• Sample Call:

  curl -H 'x-auth-token: <token>' http://localhost:8080/process

Start Process

Starts a process. The owner of the process is the user which starts it.

• URL

  /process

• Method:

  POST

• Header:

  Required:

  x-auth-token=[token]

  Content-Type=application/json

• Data Params

  {
    "environment":{
      "env1":"value1",
      "env2":"value2"
    },
    "workDirectory": "/tmp/",
    "command":"/bin/sh",
    "arguments":[
      "<arg1>", "<arg2>"
    ]
  }

• Success Response:

  • Code: 200
    Content:

    {
        "pid": "1312",
    	"created": true
    }

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
      "error":"Unauthorized", 
      "message":"Authentication Failed: Invalid token - <token>"
    }

  • Code: 403 FORBIDDEN
    Content:

    {
      "error":"Forbidden", 
      "message":"Access Denied"
    }

• Sample Call:

  curl -X POST -H 'x-auth-token: <token>' -H 'Content-Type: application/json' http://localhost:8080/process \
    --data '{"environment":{ "env1":"value1" }, "workDirectory": "/tmp/", "command":"/bin/sh", "arguments":[ "-c", "date" ]}'

Start Process (as admin)

Starts a process. The owner of the process is the user which starts the server application.

• URL

  /process/admin

• Method:

  POST

• Header:

  Required:

  x-auth-token=[token]

  Content-Type=application/json

• Data Params

  {
    "environment":{
      "env1":"value1",
      "env2":"value2"
    },
    "workDirectory": "/tmp/",
    "command":"/bin/sh",
    "arguments":[
      "<arg1>", "<arg2>"
    ]
  }

• Success Response:

  • Code: 200
    Content:

    {
        "pid": "1312",
    	"created": true
    }

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
      "error":"Unauthorized", 
      "message":"Authentication Failed: Invalid token - <token>"
    }

  • Code: 403 FORBIDDEN
    Content:

    {
      "error":"Forbidden", 
      "message":"Access Denied"
    }

• Sample Call:

  curl -X POST -H 'x-auth-token: <token>' -H 'Content-Type: application/json' http://localhost:8080/process/admin \
    --data '{"environment":{ "env1":"value1" }, "workDirectory": "/tmp/", "command":"/bin/sh", "arguments":[ "-c", "date" ]}'

Signal

Send signal to running process. Only the user which created the process can send a signal to them. Expected a user which is an admin! If you sends a signal to a foreign process, you will get a 404 (ProcessNotFound).

• URL

  /process/{pid}/{signal}

  pid=[string] signal=[string]

• Method:

  POST

• Header:

  Required:

  x-auth-token=[token]

• Success Response:

  • Code: 200
    Content:

    {
        "returnCode": 0
    }

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
      "error":"Unauthorized", 
      "message":"Authentication Failed: Invalid token - <token>"
    }

  • Code: 403 FORBIDDEN
    Content:

    {
      "error":"Forbidden", 
      "message":"Access Denied"
    }

  • Code: 404 NOT FOUND
    Content:

    {
      "error":"Not Found", 
      "message":"No process found for <pid>"
    }

• Sample Call:

    curl -X POST -H 'x-auth-token: <token>' http://localhost:8080/process/1312/9

• Notes:

  If you want to know which signals are supported on your system, execute the following command in a shell:

  kill -l

  You can use the numeric signal value as well as the name of the signal.

Input

Send a input string to a running process. Only the user which created the process can send input to them. Expected a user which is an admin! If you sends input to a foreign process, you will get a 404 (ProcessNotFound).

• URL

  /process/{pid}

  pid=[string]

• Method:

  POST

• Header:

  Required:

  x-auth-token=[token]

  Content-Type=application/json

• Data Params

  {
    "input": "Hello World!\n"
  }

  OR

  {
    "raw": "SGVsbG8gV29ybGQK"
  }

• Success Response:

  • Code: 200

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
      "error":"Unauthorized", 
      "message":"Authentication Failed: Invalid token - <token>"
    }

  • Code: 403 FORBIDDEN
    Content:

    {
      "error":"Forbidden", 
      "message":"Access Denied"
    }

  • Code: 404 NOT FOUND
    Content:

    {
      "error":"Not Found", 
      "message":"No process found for <pid>"
    }

• Sample Call:

  curl -X POST -H 'x-auth-token: <token>' -H 'Content-Type: application/json' http://localhost:8080/process/1312 --data '{"input": "Hello World!\n"}'

  OR

  curl -X POST -H 'x-auth-token: <token>' -H 'Content-Type: application/json' http://localhost:8080/process/1312 --data '{"raw": "SGVsbG8gV29ybGQK"}'

• Notes:

  If you are using the "input" special characters will be interpreting. If you are using the "raw" you have to send base64 encoded string. In raw-mode no characters will be interpreting.

Status

Gets process information.

• URL

  /process/{pid}

  pid=[string]

• Method:

  GET

• Header:

  Required:

  x-auth-token=[token]

• Success Response:

  • Code: 200
    Content:

    { 
      "id": "1",
      "parent": "1",
      "commandline": "/bin/init",
      "user": "root",
      "environment": {
          "env1": "value1",
          "env2": "value2"
      },
      "running": true,
      "returnCode": null
    }

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
      "error":"Unauthorized", 
      "message":"Authentication Failed: Invalid token - <token>"
    }

  • Code: 403 FORBIDDEN
    Content:

    {
      "error":"Forbidden", 
      "message":"Access Denied"
    }

  • Code: 404 NOT FOUND
    Content:

    {
      "error":"Not Found", 
      "message":"No process found for <pid>"
    }

• Sample Call:

  curl -H 'x-auth-token: <token>' http://localhost:8080/process/1

Output

Read the output/error from a process which where started before. Only the user which created the process can read the data. Expected a user which is an admin! If you try to read a foreign process - or an process which where not started from the server-application, you will get a 404 (ProcessNotFound).

• URL

  /process/{pid}/{stream}

  pid=[string] stream=[out|err]

• Method:

  GET

• Header:

  Required:

  x-auth-token=[token] Accept: application/octet-stream Range:[range]

  Range looks like this: <start>-. Where start is the start index to read.

• Success Response:

  • Code: 206
    Content: the raw output
    Header
    • Content-Type: application/octet-stream
    • Accept-Ranges: bytes
    • Content-Range: <start>-<read>/*

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
      "error":"Unauthorized", 
      "message":"Authentication Failed: Invalid token - <token>"
    }

  • Code: 403 FORBIDDEN
    Content:

    {
      "error":"Forbidden", 
      "message":"Access Denied"
    }

  • Code: 404 NOT FOUND
    Content:

    {
      "error":"Not Found", 
      "message":"No process found for <pid>"
    }

  • Code: 416 Requested range not satisfiable
    If the Range-Header is invalid!

• Sample Call:

  curl -H 'x-auth-token: <token>' -H 'Accept: application/octet-stream' -H 'Range: 0-' http://localhost:8080/process/1/out

  OR

  curl -H 'x-auth-token: <token>' -H 'Accept: application/octet-stream' -H 'Range: 13-' http://localhost:8080/process/1/err