ssh_scan Web API

ssh_scan Web API

API Version: 1.0
Status: not ready

This document explains the ssh_scan Web API, intended to be used in the web interface for ssh_scan.

Protocol Calls

scan

API Call: scan
API Method: POST

Scans a target, with an optional port (default 22). Equivalent to ssh_scan -t host -p port.

Parameters:

• target (required), which can be a hostname or an IP address

POST Parameters:

• port on which to scan (optional)

Returns:

• A JSON document including the uuid for a given scan or an error

{"uuid" : "uuid_string"}

Examples:

• /api/v1/scan?target=www.mozilla.org
• /api/v1/scan?target=115.223.33.44
  • port=9999 (POST data)

scan/results

API Call: scan/results
API Method: GET

Retrieves the results or status of a given ssh_scan_api request

Parameters:

• uuid (required), which is the uuid for a given scan

GET Parameters:

• uuid on which to scan (optional)

Returns:

• A JSON array of ssh_scan results [{...}]
• A JSON document indicating the scan is not complete

{"completed": false}

Examples:

• /api/v1/scan/results?uuid=uuid_string

work

API Call: work
API Method: GET

Retrieves the next unit of work

Parameters:

• worker_id (required), which is the unique id for a given worker instance

Returns:

• A job for worker to perform

{"job": false} 

• A JSON document indicating the scan is not complete {"job": true job_contents }

Examples:

• /api/v1/work/results?worker_id=worker_id_string

stats

API Call: stats
API Method: GET

Returns the current statistics.

Parameters: None

Returns:

{
  "SCAN_STATES":{
    "QUEUED":0,
    "RUNNING":23,
    "ERRORED":2426,
    "COMPLETED":2546
  },
  "QUEUED_MAX_AGE":0,
  "GRADE_REPORT":{
    "A":326,
    "B":74,
    "C":382,
    "D":977,
    "F":996
   }
}

Additional Notes:

• SCAN_STATES describe the quantity of scans in any one state (QUEUED, RUNNING, ERRORED, COMPLETED)
• QUEUE_MAX_AGE describes the age in seconds of the oldest item in QUEUED state. This is a good item to monitor to ensure that the queues don't get backed up or to identify an abuse scenario.
• GRADE_REPORT describes the histogram of the grade distribution for all scans in which we have enough information to determine a grade.

Examples:

• /api/v1/stats

__version__

API Call: __version__
API Method: GET

Returns version details for ssh_scan being used and API.

Example:

• /__version__
  • Returns { "ssh_scan_version": "0.0.1", "api_version": "1" }

__lbheartbeat__

API Call: __lbheartbeat__
API Method: GET

Indicates whether the API is up and working(200) or not.

Example:

• /api/v1/__lbheartbeat__
  • Returns { "status": "OK", "message": "Keep sending requests. I am still alive." }