Skip to content

API

Jump to bottom
Lucas Morris edited this page Jul 9, 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.
  • Resource Manager - A plugin running on the queue server that manages a set of resources. For example, there is a physical manager that handles connections to all manually defined resources. Resource managers only handle adding and removing resources. Once added, the resource is added to the queue to be used for jobs.
  • 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 environment.
  • 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 for authentication, 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 API-Status-Codes on the specific codes returned.

Object Status

The various types of objects (jobs, queues, and resources) have a set of states that are used to track their status. The following lists provide a reference for the options and what they mean.

Queue

  • Empty - The queue is running, but there is nothing in it currently.
  • Running - The queue is running and working on jobs.
  • Paused - The entire queue has been paused.
  • Exhausted - The queue finished all of the jobs in the stack.

Job

  • Created - The job is now within the queue and will be processed as soon as possible.
  • Running - The job has been assigned to a resource and is being processed right now.
  • Paused - The job was paused, however the relevant state has been saved in memory on the resource.
  • Done - The job was successfully completed.
  • Failed - There was an error and the job could not be completed.
  • Quit - The job was stopped prematurely by a user and cannot be restarted.

Resource

  • Running - The resource is accepting jobs and processing them.
  • Paused - The resource is not accepting jobs.
  • Quit - The resource is disconnected and is listed for informational purposes.

Authentication

For all API calls (except login), an authentication token must be submitted with the call. This token will be provided as a response upon successful login. The server will then expect the token to be provided within an HTTP header named AuthorizationToken.

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.

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.
  • role: [string] - The role the user is operating as. Will be one of "read-only", "standard user", or "administrator"

Example Request

POST /api/login

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

Example Return

{  
  "status": 200,
  "message": "Login successful",
  "token": "fa2074ff31c20348bd6da41cd75fe3f4cd120fff6362386fb5b5dd367e08ca2f",
  "role": "Administrator"
}

Logout

Resource Name: /logout

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

Arguments:

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

Example Return

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

Tools

List

Resource Name: GET /tools/

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

Arguments:

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/tools

Example Return

{
  "status": 200,
  "message": "OK",
  "tools": [
    {
      "id":"63ee8045-966f-449e-9839-58e7e0586f3c",
      "name":"Hashcat",
      "version":"1.3.3"
    },
    {
      "id":"8d660ce9-f15d-40a3-a997-a4e8867cb802",
      "name":"John the Ripper",
      "version":"1.7.9"
    },
    {
      "id":"1cee8439-7f22-457c-84b8-5a8b04414090",
      "name":"John the Ripper",
      "version":"1.8.0"
    }
  ]
}

Read

Resource Name: GET /tools/:id

This will read the information about an individual tool, primarily the form that will be used to create a job using the tool.

Arguments:

  • id: [string] - UUID of the tool

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] - Array of strings containing the IDs of resources where this tool is configured.
  • form [array] - An associative array of data used to create the form for the tool. See http://textalk.github.io/angular-schema-form/ for additional information on schema.
  • schema [array] - An associative array of the schema information that will be used to validate the form. Validation also occurs on the server side, but should be included on the user side. See http://textalk.github.io/angular-schema-form/ for additional information.

Example Request

GET /api/tools/63ee8045-966f-449e-9839-58e7e0586f3c

Example Return

{
  "tool": {
    "id":"8d660ce9-f15d-40a3-a997-a4e8867cb802",
    "name":"John the Ripper",
    "version":"1.7.9",
    "form": [
      "algorithm",
      "dictionary",
      "rules",
      {
        "key":"hashes",
        "type":"textarea",
        "placeholder":"Hashes go here!"
      }
    ],
    "schema": {
      "type":"object",
      "properties":{
        "algorithm":{
          "title":"Algorithm",
          "type":"string",
          "enum":[
            "NTLM",
            "NTLMv2",
            "ms-cache",
            "ms-cache v2",
            "SQL 2005",
            "SQL 2008",
            "MD5"
          ]
        },
        "dictionary":{
          "title":"Dictionary",
          "type":"string",
          "enum":[
            "crackstation",
            "crackstation-human-only",
            "m3g9tr0n",
            "words-english"
          ]
        },
        "rules":{
          "title":"Rule File",
          "type":"string",
          "enum":[
            "d3ad0ne",
            "t0xic"
          ]
        },
        "hashes":{
          "title":"Hashes",
          "type":"string",
          "description":"Note: Use the file format as required by hashcat"
        }
      }
    },
    "status":200,
    "message":"OK"
  }
}

Resource Managers

List

Resource Name: GET /resourcemanager/

This will return a list of all resource managers currently configured in the queue.

Arguments:

Return Value

  • status: [int] - The return code for our function, see API-Status-Codes.
  • message: [string] - A message based on the return code.
  • resourcemanagers: [array] - The returned value is an array of the names and IDs for all managers.

Example Request

GET /api/resourcemanager

Example Return

{
  "status": 200,
  "message": "OK",
  "resourcemanagers": [
    {
      "id":"physical",
      "name":"Physical",
    },
    {
      "id":"cloud-aws",
      "name":"Amazon Web Services",
    },
  ]
}

Read

Resource Name: GET /resourcemanager/:id

This will read the information about an individual manager, primarily the form that will be used to connect a resource.

Arguments:

  • id: [string] - System name of the resource manager

Return Value

  • status: [int] - The return code for our function, see API-Status-Codes.
  • message: [string] - A message based on the return code.
  • id: [string] - The system name of the resource manager.
  • name: [string] - The display name of the resource manager.
  • description: [string] - A description of the resource manager.
  • resources: [array] - Array of strings containing the IDs of resources managed by this resource manager.
  • form [array] - An associative array of data used to create the form for connecting resources. See http://textalk.github.io/angular-schema-form/ for additional information on schema.
  • schema [array] - An associative array of the schema information that will be used to validate the form. Validation also occurs on the server side, but should be included on the user side. See http://textalk.github.io/angular-schema-form/ for additional information.

Example Request

GET /api/tools/63ee8045-966f-449e-9839-58e7e0586f3c

Example Return

{
  "id":"physical",
  "name":"Physical",
  "description":"Manages all resources that will be connected manually, does not include any automatic removal or updates.",
  "resources": [
    "ec978274-6984-4fc2-a21a-dffc6cba2930",
    "07625054-0885-45c0-a7e1-6f8b5afbddf3",
    "d12858d1-abde-4b11-b9cf-e2321f556888",
    "bced54c0-58cb-4161-9045-7e517475ac89",
    "5243c6ed-7259-4c75-8e4f-e87f425a2f33"
  ],
  "form": [
    "address"
  ],
  "schema": {
    "type": "object",
    "title": "Comment",
    "properties": {
      "address": {
        "title": "Address",
        "type": "string"
      }
    },
    "required": [
      "address"
    ]
  },
  "status":200,
  "message":"OK"
}

Job

List

Resource Name: GET /jobs

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

Arguments:

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:
    • id: [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
    • etc: [string] – estimated time remaining
    • cracked: [int] – Number of hashes that have been cracked.
    • total: [int] - Number of hashes that were submitted
    • progress: [int] – Percentage of job completion

Example Request

GET /api/jobs

Example Return

{
  "status": 200,
  "message": "OK",
  "jobs": [ 
    {
      "id":"72fd24ca-e529-4b38-b70d-2ad566de7e49",
      "name":"The Cheerful Shark Logistics Company",
      "status":"running",
      "resourceid":"1116814b-7c59-4b5d-87b6-fabaa5f594d1",
      "owner":"emperorcow",
      "etc":"3 hours, 15 minutes",
      "crackedhashes":5,
      "totalhashes":800,
      "progress":0.68,
      "toolid":"1116814b-7c59-4b5d-87b6-fabaa5f594d1"
    },
    {
      "id":"786c4f68-1b7f-46e0-b5bd-75090d78b25c",
      "name":"The Deep Lime Builders Company",
      "status":"paused",
      "resourceid":"1116814b-7c59-4b5d-87b6-fabaa5f594d1",
      "owner":"emperorcow",
      "etc":"16 minutes",
      "crackedhashes":102,
      "totalhashes":539,
      "progress":0.17,
      "toolid":"1116814b-7c59-4b5d-87b6-fabaa5f594d1"
    }
  ]
}

Create

Resource Name: POST /jobs/

Create a Job to be added to the Queue.

Arguments:

  • 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

POST /api/jobs

{
  "toolid":"8d660ce9-f15d-40a3-a997-a4e8867cb802",
  "name":"Crack for ABC",
  "params":{
    "algorithm":"ms-cache",
    "dictionary":"m3g9tr0n",
    "rules":"t0xic",
    "hashes":"Administrator:500:6A98EB0FB88A449CBE6FABFD825BCA61:D144986C6122B1B1654BA39932465528:::\nGuest:501:A0E150C75A17008EAAD3B435B51404EE:3D2B4DFAC512B7EF6188248B8E113CB9:::\nfakeuser:1000:24500AFA4E78B1C1944E2DF489A880E4:F47E4045A58ECEBD1F544168E050B1A9:::"
  }
}

Example Return

{  
  "status": 200,
  "message": "OK",
  "jobid": "628c1286-05b5-4643-b9d2-07d53fc0f36e"
}

Read

Resource Name: GET /jobs/:id

Get a detailed status on a specific job

Arguments:

  • id: [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.
    • id: [string] - The UUID of the job.
    • name: [string] - Name of the selected job.
    • status: [string] - Status of the job. Will be one of completed, running, paused, stopped, or queued
    • resourceid: [string] - The UUID of the resource the job is running on.
    • owner: [string] - Username of the person who started this job.
    • etc: [string] - String representing the time the job has left to run
    • cracked: [int] - How many tasks or hashes have we completed/cracked
    • total: [int] - Total number of tasks or hashes that were originally submitted.
    • progress: [int] - A number from 0 to 1 representing how far the job has completed.
    • performance: [array] - An array of key value pairs, with the key as the time of the data and the value being a piece of data showing over time performance of the tool
    • performancetitle: [string] - The title to show above the graph of performance.
    • output: [array] - An array of key/value pairs for output from the tool. Will be different for each tool.

Example Request

GET /api/jobs/eeeb309a-00db-40a2-966e-504c39f853eb

Example Return

{
  "status":200,
  "message":"OK",
  "job":{
    "id":"786c4f68-1b7f-46e0-b5bd-75090d78b25c",
    "name":"The Deep Lime Builders Company",
    "status":"paused",
    "resourceid":"1116814b-7c59-4b5d-87b6-fabaa5f594d1",
    "owner":"emperorcow",
    "etc":"3 hours and 15 minutes",
    "crackedhashes":102,
    "totalhashes":539,
    "progress":0.17,
    "params":{
      "rules":"d3ad0ne",
      "dictionary":"m3g9tr0n",
      "algorithm":"NTLMv2"
    },
    "toolid":"1116814b-7c59-4b5d-87b6-fabaa5f594d1",
    "performancetitle":"Hashes Per Second",
    "performancedata":{
      "2015-03-20T08:41:40-06:00":170408695042,
      "2015-03-20T08:46:40-06:00":887381030944,
      "2015-03-20T08:51:40-06:00":281011148854,
      "2015-03-20T08:56:40-06:00":829705171956,
      "2015-03-20T09:01:40-06:00":387598519958,
      "2015-03-20T09:06:40-06:00":875715683354,
      "2015-03-20T09:11:40-06:00":504016472857,
      "2015-03-20T09:16:40-06:00":191412988977,
      "2015-03-20T09:21:40-06:00":910057657506,
      "2015-03-20T09:26:40-06:00":292800919333,
      "2015-03-20T09:31:40-06:00":60899135794,
      "2015-03-20T09:36:40-06:00":133411525899,
      "2015-03-20T09:41:40-06:00":690580034950,
      "2015-03-20T09:46:40-06:00":547304740030,
      "2015-03-20T09:51:40-06:00":742755575255,
      "2015-03-20T09:56:40-06:00":364057020833,
      "2015-03-20T10:01:40-06:00":675835662873,
      "2015-03-20T10:06:40-06:00":70984913208,
      "2015-03-20T10:11:40-06:00":692616662126,
      "2015-03-20T10:16:40-06:00":359597199587,
      "2015-03-20T10:21:40-06:00":556924477062,
      "2015-03-20T10:26:40-06:00":434569672536,
      "2015-03-20T10:31:40-06:00":764635553536,
      "2015-03-20T10:36:40-06:00":183403765827,
      "2015-03-20T10:41:40-06:00":781993316002,
      "2015-03-20T10:46:40-06:00":229866146520,
      "2015-03-20T10:51:40-06:00":399912130723,
      "2015-03-20T10:56:40-06:00":413416842757,
      "2015-03-20T11:01:40-06:00":400435206762,
      "2015-03-20T11:06:40-06:00":766845239145,
      "2015-03-20T11:11:40-06:00":243617788193,
      "2015-03-20T11:16:40-06:00":597963029446
    },
    "outputtitles": [
      "Hash",
      "Plaintext"
    ],
    "outputdata": [
      ["hash0","password0"],
      ["hash1","password1"],
      ["hash2","password2"],
      ["hash3","password3"],
      ["hash4","password4"],
      ["hash5","password5"],
      ["hash6","password6"]
    ]
  }
}

Update

Resource Name: PUT /jobs/:id

Update the status of a job, pausing, resuming, or shutting it down. Note that only the status of the job object can be updated, although by default the entire job object will be sent, all other properties are read only.

Arguments:

  • id: [string] – ID of the Job
  • action: [string] - What should we change this job to? Should be pause, stop, or resume

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

PUT /api/jobs/72fd24ca-e529-4b38-b70d-2ad566de7e49

{
  "id":"b762b17a-c324-4385-8629-a829e1bc4395",
  "name":"Beta Gecko Films",
  "status":"paused",
  "resourceid":"1116814b-7c59-4b5d-87b6-fabaa5f594d1",
  "owner":"emperorcow",
  "etc":"3 hours and 15 minutes",
  "crackedhashes":0,
  "totalhashes":352,
  "progress":0,
  "toolid":"1116814b-7c59-4b5d-87b6-fabaa5f594d1",
}

Example Return

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

Delete

Resource Name: DELETE /jobs/:id

Delete a job from the queue.

Arguments:

  • id: [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

DELETE /api/jobs/72fd24ca-e529-4b38-b70d-2ad566de7e49

Example Return

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

Resources

List

Resource Name: GET /resources

List all resources currently configured within the Queue

Arguments:

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:
    • id: [string] - String ID of the resource
    • name: [string] - Friendly name of the resource
    • address: [string] - IP address or hostname of the resource
    • params: [object] - A dictionary of all parameters as set by the resource manager
    • manager: [string] - The ID of the resource manager that runs this resource
    • status: [string] - Current status of the resource ("running" or "paused")
    • tools: [array] - An array of strings with the name of each tool on this resource

Example Request

GET /api/resources

Example Return

{  
  "status": 200,
  "message": "OK",
  "resources": [
    {
      "id": "2390309g1kdlk12109ge1209u13",
      "status": "running",
      "name": "McAtee's Massive Magical Manipulator",
      "params": {},      
      "address": "192.168.1.1",
      "manager": "physical",
      "tools": [
        {
          "id":"63ee8045-966f-449e-9839-58e7e0586f3c",
          "name":"Hashcat",
          "version":"1.3.3"
        },
        {
          "id":"8d660ce9-f15d-40a3-a997-a4e8867cb802",
          "name":"John the Ripper",
          "version":"1.7.9"
        },
        {
          "id":"1cee8439-7f22-457c-84b8-5a8b04414090",
          "name":"John the Ripper",
          "version":"1.8.0"
        }
      ]
    },
    {
      "id": "2390309g1kdlk12109ge1209u13",
      "status": "paused",
      "name": "Lucas' Lovely Logistical Loader",
      "params": {},
      "address": "10.0.0.1",
      "manager": "physical",
      "tools": [
        {
          "id":"63ee8045-966f-449e-9839-58e7e0586f3c",
          "name":"Hashcat",
          "version":"1.3.3"
        },
        {
          "id":"8d660ce9-f15d-40a3-a997-a4e8867cb802",
          "name":"John the Ripper",
          "version":"1.7.9"
        },
        {
          "id":"1cee8439-7f22-457c-84b8-5a8b04414090",
          "name":"John the Ripper",
          "version":"1.8.0"
        }
      ]
    }
  ]
}

Create

Resource Name: POST /resources

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.

Arguments:

  • key: [string] - Connection key configured on the resource. Note: This is only used during initial connection, not to secure the ongoing connection.
  • name: [string] - A friendly name for the resource.
  • address: [string] - The IP address or hostname to connect to.
  • 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.

Example Request

POST /api/resources

{
  "key":"supers3cretk3y",
  "address": "192.168.1.2",
  "name": "GPU Cracker 1",
  "manager": "physical",
  "params":{}
}

Example Return

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

Read

Resource Name: GET /resources/:id

Get all information about a resource.

Arguments:

  • id: [string] – ID of the resource.

Return Value

  • status: [int] - The return code for our function, see API-Status-Codes.
  • message: [string] - A message based on the return code.
  • resource: [object] - An object representing the data from the resource:
    • id: [string] - String ID of the resource
    • name: [string] - Friendly name of the resource
    • address: [string] - IP address or hostname of the resource
    • params: [object] - A dictionary of all parameters as set by the resource manager
    • manager: [string] - The ID of the resource manager that runs this resource
    • status: [string] - Current status of the resource ("running" or "paused")
    • tools: [array] - An array of strings with the name of each tool on this resource

Example Request

GET /api/resources/1116814b-7c59-4b5d-87b6-fabaa5f594d1

Example Return

{  
  "status": 200,
  "message": "OK",
  "resource": {
    "name": "GPU Cracker 1",
    "address": "10.0.0.1",
    "params": {},      
    "manager": "physical",    
    "tools": [
      {
        "id":"63ee8045-966f-449e-9839-58e7e0586f3c",
        "name":"Hashcat",
        "version":"1.3.3"
      },
      {
        "id":"8d660ce9-f15d-40a3-a997-a4e8867cb802",
        "name":"John the Ripper",
        "version":"1.7.9"
      },
      {
        "id":"1cee8439-7f22-457c-84b8-5a8b04414090",
        "name":"John the Ripper",
        "version":"1.8.0"
      }
    ],
    "status": "running",
  }
}

Update

Resource Name: PUT /resources/:id

Update the status of the resource to either shut it down or pause all jobs on it.

Arguments:

  • id: [string] – ID of the resource
  • status [string] - A string representing the status that is either resume, pause or shutdown.

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

PUT /api/resources/1116814b-7c59-4b5d-87b6-fabaa5f594d1

{
  "status": "paused"
}

Example Return

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

Delete

Resource Name: DELETE /resources/:id

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

Arguments:

  • id: [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

DELETE /api/resources/1116814b-7c59-4b5d-87b6-fabaa5f594d1

Example Return

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

Queue

Update

Resource Name: PUT /queue/

Take the listing of jobs within the queue and reorder the stack or pause an individual job.

Arguments:

  • 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

PUT /api/queue/

{
  "joborder": [
    "72fd24ca-e529-4b38-b70d-2ad566de7e49",
    "786c4f68-1b7f-46e0-b5bd-75090d78b25c",
    "bedf31d2-25d6-4023-a2b1-9400926c6c92",
    "baba3905-a53b-4b37-bde1-027f1fa89766",
  ]
}

Example Return

{  
  "status": 200,
  "message": "OK",
}
Clone this wiki locally