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

scan/results/delete

API Call: scan/results/delete/uuid
API Method: POST

Deletes the scan with their specific uuid.

Parameters:

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

Returns:

• A JSON document indicating if the uuid is not found

{"deleted": false}

Examples:

• /api/v1/scan/results/delete/uuid

scan/results/delete

API Call: scan/results/delete/all
API Method: GET

Deletes all of the scans from the database.

Parameters: None

Examples:

• /api/v1/scan/results/delete/all

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:

{ "items_queued" : "Number of items queued",
  "avg_requests_per_min" : "Average of the requests per minute", 
  "requests_per_min" : "Requests per minute" } 

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