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." }