Skip to content

API

Jump to bottom
Lucas Morris edited this page Feb 17, 2015 · 32 revisions

Overview

The following documentation exists to provide documentation for the RESTful API used to communicate with the queue. The API is divided into the following key areas:

Terminology

  • Resource – Individual servers / systems running that control tools and resources for the Queue Manager.
  • Tool – An external command or internal process that uses a specific type of resource, takes in a group of arguments and hashes, and attempts to crack these hashes.
  • Queue – The master queue that all jobs: running, paused, and stopped are kept in. This is the master controller for the entire envrionment.
  • Job – An individual job within the queue that is passed to individual Resource Clients

Notes

The API is hosted on the Queue at https:///api and must be accessed over HTTPS. As noted below, all requests must be authenticated utilizing the token provided through the login resource as described below. In the case of GET requests, parameters will be expected within the query string. In the case of POST requests, properties should be submitted as a JSON hash (don't forget to set Content-Type: application/json)!

For all requests, a response code and message is provided whether it is successful or failed. For additional information, see [../wiki/API-Status-Codes] on the specific codes returned.

API Documentation

Users / Credentials

Login

Resource Name: /login

Allows the user to send a username and password and provides them with an authentication token to utilize for all further communications with the server.

Methods Accepted: POST

Arguments:

  • username: [string] - A username configured in the system
  • password: [string] - The user's password

Return Value

  • status: [int] - The return code for our function, see API-Status-Codes.
  • message: [string] - A message based on the return code.
  • token: [string] - Provided by server to authenticate all future system activities.

Example Request

POST /api/login

{
  "username": "jdoe",
  "password": "P@ssw0rdExample",
}

Example Return

{  
  "status": 200,
  "message": "Login successful",
  "token": "29edk1930d0129d910d91029d81",
}

Logout

Resource Name: /logout

This function allows a user to deactivate their token and log out from the system.

Methods Accepted: GET
Arguments:

  • token: [string] - User authentication token.

Return Value

  • status: [int] - The return code for our function, see API-Status-Codes.
  • message: [string] - A message based on the return code.

Example Request

GET /api/logout?token=3kd91209dlkjdflkj1209u

Example Return

{  
  "status": 200,
  "message": "OK",
}

Tools

List

Resource Name: /tool/list

This will return a list of all tools configured within the system that could be used.

Methods Accepted: GET
Arguments:

  • token: [string] - User authentication token.

Return Value

  • status: [int] - The return code for our function, see API-Status-Codes.
  • message: [string] - A message based on the return code.
  • tools: [array] - The returned value is a JSON array of the names of all available tools.

Example Request

GET /api/tool/list?token=2lkj1325098ek12lg98231

Example Return

}
  "status": 200,
  "message": "OK",
  "tools": [ 
    "Hashcat - Dictionary",
    "John - Brute",
  ]
}

Job

List

Resource Name: /job/list

This will return a list of all jobs in the queue with some basic statistics about each job.

Methods Accepted: GET
Arguments:

  • token: [string] - User authentication token.

Return Value

  • status: [int] - The return code for our function, see API-Status-Codes.
  • message: [string] - A message based on the return code.
  • jobs: [array] - The returned value is a JSON array for all of the jobs in the queue with each item containing the following:
    • jobid: [string] – ID of the Job
    • name: [string] – Name of the job
    • status: [string] - The status of the job (running, paused, stopped, none)
    • resourceid: [string] – Resource the job is running on
    • owner: [string] - The username of the creator of the job
    • starttime: [timestamp] – UNIX Timestamp for the start time of the Job
    • crackedhashes: [int] – Number of hashes that have been cracked.
    • totalhashes: [int] - Number of hashes that were submitted
    • percentage: [int] – Percentage of job completion

Example Request

GET /api/job/list?token=2lkj1325098ek12lg98231

Example Return

}
  "status": 200,
  "message": "OK",
  "jobs": [ 
    {   
      "jobid": "29d0109d2098d98109dk1lk35",
      "name": "Crack for ABC",
      "status": "running",
      "resourceid": "3939d91jdk1d90alq291209dl21",
      "owner": "lucas.morris",
      "starttime": 1424041099,
      "crackedhashes": 12,
      "totalhashes": 211,
      "percentage": 32,
    }  
  ]
}

Form

Resource Name: /job/create/form

TODO

Methods Accepted: POST
Arguments:

TODO

Return Value

TODO

Example Request



Example Return


{  
  "status": 200,
  "message": "OK",
}  


Create 



Resource Name:   /job/create


Create a Job to be added to the Queue.  Takes three static pieces of information, the user token, tool, and name.  The remaining item is a list of form information produced from the job/create/form function.


Methods Accepted: POST

Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • toolid: [string] - ID of the tool to be used
    • 

  • name: [string] - Name used to track the job
    • 

  • params: [string] - JSON of parameters from new job form
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 

  • jobid: [string] - The UUID of the job that was created.
    • 



Example Request




Example Return


{  
  "status": 200,
  "message": "OK",
  "jobid": "29d0109d2098d98109dk1lk35"
}  


Read 



Resource Name:  /job/read


Get a detailed status on a specific job


Methods Accepted: POST

Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • jobid: [string] – ID of the Job
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
TODO - should be ALL THE THINGS!
    • 



Example Request




Example Return


{  
  "status": 200,
  "message": "OK",
}  


Reorder 



Resource Name:  /job/reorder


Take the listing of jobs within the queue and reorder the stack.


Methods Accepted: POST
Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • joborder: [array] - An array, in order, of job IDs based on their priority in the queue.
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 



Example Request


POST /api/job/reorder

{
  "token": "2ldljk120o89fgh31wlk12",
  "joborder": [
    "3kewlk31lkt3j13tklj13",
    "dklj2109ut319u21rlk21",
    "209cld1290dfglk2129d9",
    "z0312lkj2kmj12125bew3",
  ]
}


Example Return


{  
  "status": 200,
  "message": "OK",
}  


Pause 



Resource Name:  /job/pause


Pause a currently running job.


Methods Accepted: POST

Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • jobid: [string] – ID of the Job
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 



Example Request


POST /api/job/pause

{
  "token": "2ldljk120o89fgh31wlk12",
  "jobid": "3kewlk31lkt3j13tklj13",
}


Example Return


{  
  "status": 200,
  "message": "OK",
}  


Delete



Resource Name:  /job/delete


Delete a job from the queue.


Methods Accepted: POST

Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • jobid: [string] – ID of the Job
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 



Example Request


POST /api/job/delete

{
  "token": "2ldljk120o89fgh31wlk12",
  "jobid": "3kewlk31lkt3j13tklj13",
}


Example Return


{  
  "status": 200,
  "message": "OK",
}  


Resources


List 



Resource Name:  /resource/list


List all resources currently configured within the Queue


Methods Accepted: GET

Arguments:


    

  • token: [string] -  User authentication token.
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 

  • resources: [array] - An array of resources that includes the following information:

      

    • resourceid: [string] - String ID of the resource
      • 

    • status: [string] - Current status of the resource (enabled, disabled, shutdown, etc.)
      • 

    • tools: [array] - An array of strings with the name of each tool on this resource
      • 

    

    • 



Example Request


GET /resource/list?token=ld91209ugfelk212lkj2


Example Return


{  
  "status": 200,
  "message": "OK",
  "resources": 
  [
   {
     "resourceid": "2390309g1kdlk12109ge1209u13",
     "status": "running",
     "tools": [
       "Hashcat - Dictionary", 
       "Hashcat - Brute Force",
       "John the Ripper - Brute",
     ],
   }
  ]
}  


Create 



Resource Name:  /resource/create


Connect a resource to the queue for use.  This works by providing the IP address of the resource that we should connect to, at which point the queue will then connect to the resource and add it to the queue.


Methods Accepted: POST

Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • key: [string] - Connection key configured on the resource.  Note: This is only used during intitial connection, not to secure the ongoing connection.
    • 

  • host: [string] - The IP address or hostname to connect to.
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 



Example Request


POST /api/resource/create

{
  "token":"dk239e09dk12lkjfge",
  "key":"supers3cretk3y",
  "host": "192.168.1.2",
}


Example Return


{  
  "status": 200,
  "message": "OK",
}  


Read 



Resource Name:  /resource/read


Get all information about a resource.


Methods Accepted: POST
Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • resourceid: [string] – ID of the Job
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 



Example Request


POST /api/resource/read

{
  "token":"dk239e09dk12lkjfge",
  "resourceid":"32lkjd0912309g30190j",
}


Example Return


{  
  "status": 200,
  "message": "OK",
  "hardware": [
    "gpu": [
      {
        "timestamp": "1424133520",
        "usage": "0.2"
      },
      {
        "timestamp": "1424144520",
        "usage": "0.3"
      },
    ],
    "cpu": [
      {
        "timestamp": "1424133520",
        "usage": "0.9"
      },
      {
        "timestamp": "1424144520",
        "usage": "0.72"
      },
    ],
  ],
  "tools": [
    "Hashcat - Brute",
    "Hashcat - Dictionary",
    "John - Brute",
  ]
  "status": "running",
}  


Pause 



Resource Name:  /resource/pause


Pause all jobs on the resource


Methods Accepted: POST

Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • resourceid: [string] – ID of the Job
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 



Example Request


POST /api/resource/pause

{
  "token":"dk239e09dk12lkjfge",
  "resourceid":"32lkjd0912309g30190j",
}


Example Return


{  
  "status": 200,
  "message": "OK",
}  


Shutdown 



Resource Name:  /resource/shutdown


Shutdown a resource, which will result in any jobs running on that resource being stopped.  The resource will remain configured.


Methods Accepted: POST

Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • resourceid: [string] – ID of the Job
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 



Example Request


POST /api/resource/shutdown

{
  "token":"dk239e09dk12lkjfge",
  "resourceid":"32lkjd0912309g30190j",
}


Example Return


{  
  "status": 200,
  "message": "OK",
}  


Delete 



Resource Name:  /resource/delete


Completely delete a resource from our system, stopping all jobs, deleting all data, and removing everything associated with it.


Methods Accepted: POST

Arguments:


    

  • token: [string] -  User authentication token.
    • 

  • resourceid: [string] – ID of the Job
    • 



Return Value


    

  • status: [int] - The return code for our function, see API-Status-Codes.
    • 

  • message: [string] - A message based on the return code.
    • 



Example Request


POST /api/resource/delete

{
  "token":"dk239e09dk12lkjfge",
  "resourceid":"32lkjd0912309g30190j",
}


Example Return


{  
  "status": 200,
  "message": "OK",
}  


              


          



  
          

            


            
Clone this wiki locally