API Reference

Some of our tools can be accessed programatically using this API. The tools can be started, stopped and queried for output in a machine-friendly format (JSON). The following tools have support for API:

All the API calls must be done using HTTP POST against the following url:

https://pentest-tools.com/api?key={your key}
API version information:
API Version Release Date Notes
0.1 31 August 2017 Current version

This is a sample API client written in Python, which can be used as a starting point for using the API.

Start scan

This operation starts a new scan.

Request parameters:
Name Type Description Value
op String Start a new scan start_scan
tool_id Integer The id of the tool that will be started. See details of each tool.
tool_params Dictionary The parameters for the tool. See details of each tool.
Request example:
Since tool_id and tool_params are specific for each tool, please see the specific start example for the tool that you need.

Response parameters:
Name Type Description Value
op_status String The status of the operation
  • success
  • fail
scan_id Integer The id of the new scan that was started.
(Returned in case of a successful operation)
scan_status String The status of the new scan.
(Returned in case of a successful operation)
  • waiting
error String Error message.
(Returned in case of a failed operation)
Response example:
{
    "op_status":        "success",
    "scan_id":          456234,
    "scan_status":      "waiting"
}

Get output

This operation returns the output of a scan, including scan information and status.

Request parameters:
Name Type Description Value
op String Get the output of the scan get_output
scan_id Integer The id of the scan that is queried for output. This value is usually taken from
the response of start_scan or get_scans.
output_format String The format of the output. (optional)
  • json (default)
  • html
  • pdf
Request example:
{
    "op":            "get_output",
    "scan_id":       456234,
    "output_format": "html",
}

Response parameters:
Name Type Description Value
op_status String The status of the operation
  • success
  • fail
scan_output Dictionary The output according to the requested output_format. Can be:
  • scan_tests - a list of JSON objects containing information about each test performed and its results
  • output_html - raw HTML report
  • output_pdf - raw PDF report
(Returned in case of a successful operation)
scan_info Dictionary Contains the following information about the scan:
  • crt_test - The description of the test that is currently running
  • num_tests - The total number of security tests performed by this scanner
  • num_finished_tests - The number of finished tests from this scan
  • start_time - The time when the scan started
  • end_time - The time when the scan finished
  • scan_type - The type of test performed. This influences the output format.
    • vulnerability
    • discovery
  • duration - The number of seconds the scan took to finish.

(Returned in case of a successful operation)
error String Error message.
(Returned in case of a failed operation)
Response example for a "running" scan:
{
    "op_status": "success", 
    "scan_output": {
        "output_html":        "<html> ... <\/html>"
    }, 
    "scan_info": {
        "crt_test":           "Searching for sensitive files...",
        "num_tests":          26,
        "num_finished_tests": 9,
        "start_time":         "2017-08-31 13:01:52",
        "end_time":           "2017-08-31 13:01:53",
        "scan_type":          "vulnerability",
        "duration":           "1.0 seconds"
    }, 
    "scan_status": "running"
}

Response example for a "finished" scan:
{
    "op_status": "success", 
    "scan_output": {
        "output_html":        "<html> ... <\/html>"
    }, 
    "scan_info": {
        "crt_test":           "",
        "num_tests":          26,
        "num_finished_tests": 26,
        "start_time":         "2017-08-31 13:08:02",
        "end_time":           "2017-08-31 13:08:17",
        "scan_type":          "vulnerability",
        "duration":           "15.0 seconds"
    }, 
    "scan_status": "finished"
}

Get scans

This operation returns the list of the scans performed by the current user, together with their status.

Request parameters:
Name Type Description Value
op String Get the list of scans get_scans
limit Integer Limit the number of returned scans
Request example:
{
    "op":       "get_scans",
    "limit":    4
}

Response parameters:
Name Type Description Value
op_status String The status of the operation
  • success
  • fail
scans Array The list of scans for the current user.
(Returned in case of a successful operation)
error String Error message.
(Returned in case of a failed operation)
Response example:
{
    "op_status":    "success",
    "scans":    [
        {
            "scan_id":      456234,
            "scan_status":  "running",
        },
        {
            "scan_id":      456235,
            "scan_status":  "finished",
        },
        {
            "scan_id":      456236,
            "scan_status":  "waiting",
        },
        {
            "scan_id":      456237,
            "scan_status":  "stopped",
        }
    ]
}

Stop scan

This operation stops a running scan.

Request parameters:
Name Type Description Value
op String Stop a scan stop_scan
scan_id Integer The id of the scan that will be stopped
Request example:
{
    "op":       "stop_scan",
    "scan_id":  456234
}

Response parameters:
Name Type Description Value
op_status String The status of the operation
  • success
  • fail
scan_status String The status of the scan.
(Returned in case of a successful operation)
  • stopped
error String Error message.
(Returned in case of a failed operation)
Response example:
{
    "op_status":    "success",
    "scan_status":  "stopped"
}

Error messages

The following error messages can be returned into the response of an operation request.

Message Description
invalid request The request could not be processed on the server side, maybe because it had an invalid format.
invalid key The provided API key was incorrect.
unauthorized The user was not authorized to perform the requested operation.
insufficient credits The user does not have enough credits to start the requeste scan.
invalid operation The requested operation was invalid.
invalid tool_id The specified tool_id was invalid.
invalid tool_params The specified parameters were invalid for the tool.
invalid target This target cannot be scanned due to lack of authorization.
invalid scan_id The specified scan_id was invalid.
invalid format The requested output format is invalid.
internal error An internal error has occured.

Scan status codes

A scan can have one of the following statuses:

Scan status Description
waiting The scan was queued and it is waiting to start.
running The scan was successfully started and it is running.
failed to start The has failed to start.
finished The scan has successfully finished its execution.
stopped The scan was stopped by the user.
timed out The allocated time for the scan has expired and the tool was stopped.
aborted An internal error has happened and the tool was stopped.
These are the specific parameters needed to start each tool. The complete reference to start_scan operation is here.

Web Server Scan

Name Type Description Value
tool_id Integer The id of this tool 170
target String The URL that will be scanned
scan_type String The type of scan that you want to be performed
  • quick
  • full
Start scan example:
{
    "op":               "start_scan",
    "tool_id":          170,
    "tool_params": {
        "target":       "http://demo.pentest-tools.com/webapp/",
        "scan_type":    "quick"
    }
}