Skip to content

API

Jump to bottom
Lucas Morris edited this page Mar 15, 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 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.

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": "29edk1930d0129d910d91029d81",
  "role": "administrator"
}

Logout

Resource Name: /logout

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

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

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

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/tools?token=2lkj1325098ek12lg98231

Example Return

{
  "status": 200,
  "message": "OK",
  "tools": {
    "63ee8045-966f-449e-9839-58e7e0586f3c": {
      "name": "Hashcat",
      "version": "1.3.3", 
    }
    "8d660ce9-f15d-40a3-a997-a4e8867cb802": {
      "name": "John the Ripper",
      "version": "1.7.9", 
    }
    "8d660ce9-f15d-328b-a997-39dl10d012ld": {
      "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:

  • token: [string] - User authentication token.
  • toolname: [string] - Name of the relevant 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?token=2lkj1325098ek12lg98231

Example Return

{
  "status": 200,
  "message": "OK",
  "name": "John the Ripper",
  "version": "1.8.0",
  "resources": [ 
    "1116814b-7c59-4b5d-87b6-fabaa5f594d1",
    "202fa763-ab6d-4cad-b29d-5fa108766760"
  ],
  "form": [
    "name",
    "algorithm",
    "dictionary",
    "rules",
    {
      "key": "hashes",
      "type": "textarea",
      "placeholder": "Hashes go here!"
    }
  ]
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "title": "Name",
        "type": "string"
      },
      "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"
      }
    }
  }
}

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:

  • 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
    • 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?token=2lkj1325098ek12lg98231

Example Return

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

Create

Resource Name: POST /jobs/

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.

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

POST /api/jobs

{
  "token": "2ldljk120o89fgh31wlk12",
  "tooldid": "63ee8045-966f-449e-9839-58e7e0586f3c", 
  "name": "Example Bank",
  "params": {
    "rules": "d3ad0ne",
    "dictionary": "m3g9tr0n",
    "algorithm": "NTLMv2",
    "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:

  • 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.
  • jobid: [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.
  • starttime: [timestamp] - Timestamp of when this job was startedj
  • 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 timestamp 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?token=2lkj1325098ek12lg98231

Example Return

{  
  "status": 200,
  "message": "OK",
  "jobid":"72fd24ca-e529-4b38-b70d-2ad566de7e49",
  "name":"The Cheerful Shark Logistics Company",
  "status":"running",
  "resourceid":"1116814b-7c59-4b5d-87b6-fabaa5f594d1",
  "owner":"emperorcow",
  "starttime":1423978660,
  "cracked":5,
  "total":800,
  "progress":0.68,
  "performance": {
    "1424133520": "1000000000"
    "1424133520": "12092152912"
  },
  "performancetitle": "Hashes Per Second",
  "output": [
    //***TODO*** CREATE EXAMPLE
  ]
}

Update

Resource Name: PUT /jobs/:id

Update the status of a job, pausing, resuming, or shutting it down.

Arguments:

  • token: [string] - User authentication token.
  • jobid: [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

{
  "token": "2ldljk120o89fgh31wlk12",
  "action": "pause",
}

Example Return

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

Delete

Resource Name: DELETE /jobs/:id

Delete a job from the queue.

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

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

{
  "token": "2ldljk120o89fgh31wlk12",
}

Example Return

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

Resources

List

Resource Name: GET /resources

List all resources currently configured within the Queue

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 ("running" or "paused")
    • tools: [array] - An array of strings with the name of each tool on this resource

Example Request

GET /api/resources?token=ld91209ugfelk212lkj2

Example Return

{  
  "status": 200,
  "message": "OK",
  "resources": [
     {
      "resourceid": "2390309g1kdlk12109ge1209u13",
      "status": "running",
      "tools": {
          "63ee8045-966f-449e-9839-58e7e0586f3c": {
              "name": "Hashcat",
              "version": "1.3.3", 
          },
          "8d660ce9-f15d-40a3-a997-a4e8867cb802": {
              "name": "John the Ripper",
              "version": "1.7.9", 
          },
          "8d660ce9-f15d-328b-a997-39dl10d012ld": {
              "name": "John the Ripper",
              "version": "1.8.0", 
          }
      }
     },
     {
      "resourceid": "2390309g1kdlk12109ge1209u13",
      "status": "paused",
      "tools": {
          "63ee8045-966f-449e-9839-58e7e0586f3c": {
              "name": "Hashcat",
              "version": "1.3.3", 
          },
          "8d660ce9-f15d-40a3-a997-a4e8867cb802": {
              "name": "John the Ripper",
              "version": "1.7.9", 
          },
          "8d660ce9-f15d-328b-a997-39dl10d012ld": {
              "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:

  • 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/resources

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

Example Return

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

Read

Resource Name: GET /resources/:id

Get all information about a resource.

Arguments:

  • token: [string] - User authentication token.
  • resourceid: [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.
  • hardware: [array] - This is an array of the hardware values. These are arbitrary, but should be somewhat descriptive in their name.
  • tools [array] - This is a map of the tools available with the tool UUID being the key.

Example Request

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

{
  "token":"dk239e09dk12lkjfge",
}

Example Return

{  
  "status": 200,
  "message": "OK",
  "hardware": ["gpu","cpu"],
  "tools": [
    "63ee8045-966f-449e-9839-58e7e0586f3c": {
      "name": "Hashcat",
      "version": "1.3.3", 
    }
    "8d660ce9-f15d-40a3-a997-a4e8867cb802": {
      "name": "John the Ripper",
      "version": "1.7.9", 
    }
    "8d660ce9-f15d-328b-a997-39dl10d012ld": {
      "name": "John the Ripper",
      "version": "1.8.0", 
    }
  ]
  "resource_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:

  • token: [string] - User authentication token.
  • resourceid: [string] – ID of the Job
  • action [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

{
  "token":"dk239e09dk12lkjfge",
  "action": "pause"
}

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:

  • 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

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

{
  "token":"dk239e09dk12lkjfge",
}

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:

  • 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

PUT /api/queue/

{
  "token": "2ldljk120o89fgh31wlk12",
  "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