Loading...

API Reference


Introduction

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.6 22 August 2018 Added API support for URL Fuzzer
0.5 27 June 2018 Added API support for Network Scan OpenVAS
0.4 26 June 2018 Added API support for Find Virtual Hosts
0.3 14 June 2018 Added get_scan_status operation
0.2 5 April 2018 Added API support for Find Subdomains
0.1 31 August 2017 First version

Sample API client

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

API Operations

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.
callback_url URL The PDF report will be sent to this URL in a POST request after the scan is finished. (optional)
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",
        }
    ]
}

Get scan status

Returns the status of a scan by its id.

Request parameters:
Name Type Description Value
op String Get the status of a scan get_scan_status
scan_id Integer The id of a scan belonging to the current user.
Request example:
{
    "op":       "get_scan_status",
    "scan_id":  27785
}

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)
error String Error message.
(Returned in case of a failed operation)
Response example:
{
    "op_status":   "success",
    "scan_status": "running"
}

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

Additional notes

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.

Tool start parameters

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

Find Subdomains

Name Type Description Value
tool_id Integer The id of this tool 20
target String The domain name that will be searched for subdomains
Start scan example:
    {
        "op":               "start_scan",
        "tool_id":          20,
        "tool_params": {
            "target":       "bbc.com"
        }
    }

Find Virtual Hosts

Name Type Description Value
tool_id Integer The id of this tool 160
target String The IP address that will be searched for virtual hosts.
This parameter can also be a hostname. In this case, it will first be resolved to an IP address, then the normal search for virtual hosts will continue for that IP.
Start scan example:
{
    "op":               "start_scan",
    "tool_id":          160,
    "tool_params": {
        "target":       "151.101.64.81"
    }
}

Network Scan OpenVAS

Name Type Description Value
tool_id Integer The id of this tool 350
target String The IP address or hostname that will be scanned
scan_type String The type of scan that you want to be performed
  • light
  • full
check_alive String Enable host discovery to check if the target is alive before scanning it
  • on
  • off (default)
Start scan example:
{
    "op":               "start_scan",
    "tool_id":          350,
    "tool_params": {
        "target":       "demo.pentest-tools.com",
        "scan_type":    "light",
        "check_alive":  "on"
    }
}

URL Fuzzer

Name Type Description Value
tool_id Integer The id of this tool 90
target String The URL on the target server that will be fuzzed.
dirs String Search for directories located at the base URL (optional)
  • on
  • off
configs String Search for files with the following extensions: conf, cfg, txt, xml, json, ini (optional)
  • on
  • off
com_cfgs String Search for common file names such as: .htaccess, .bashrc, .mysql_history, passwd and many more (about 4500 names) (optional)
  • on
  • off
sources String Search for files with the following extensions: bat, c, java, cpp, cs, h (optional)
  • on
  • off
archives String Search for files with the following extensions: zip, tar, tar.gz, tgz, gz, 7z, bzip, rar, jar, apk (optional)
  • on
  • off
databases String Search for files with the following extensions: sql, mdb, db, nsf, csv, dbf (optional)
  • on
  • off
logs String Search for files with the following extensions: log, err, journal (optional)
  • on
  • off
backups String Search for files with the following extensions: old, back, bkp, bak, tmp, test, dev, prod (optional)
  • on
  • off
docs String Search for files with the following extensions: doc, docx, odt, xls, xlsx, rtf, pdf, ppt, pptx (optional)
  • on
  • off
web String Search for files with the following extensions: asp, aspx, php, jsp, shtml, htm, html, dll, pl, py, cgi, cfm, sh (optional)
  • on
  • off
custom_ext String Search for files with custom extensions (optional).
Requires input_ext parameter to be set.
  • on
  • off
input_ext String The custom extensions that you want to search for. You can specify multiple extensions (up to 10 per scan), including double extensions (ex. .php.old, .jsp.bak, .tgz, etc) (optional).
For this option to work custom_ext must be on.
dynamic String This is a scan option which extends the default wordlist with words from the HTML page located at the base URL (including existing links) (optional)
  • on
  • off
mutate String This is a scan option which applies various mutations to the identified files in order to find other resources (config.php, config2.php, config_old.php, config-dev.php, etc) (optional)
  • on
  • off
*Note:
If no parameter is set, the following defaults will be used: dirs, com_cfgs, dynamic, mutate.

Start scan example:
{
    "op":               "start_scan",
    "tool_id":          90,
    "tool_params": {
        "target":       "http://demo.pentest-tools.com/url_fuzzer",
        "dirs":         "on",
        "com_cfgs":     "on",
        "custom_ext":   "on",
        "input_ext":    "php, tar.gz",
        "dynamic":      "on"
    }
}