Skip to content
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: Website Scan, Find Subdomains, Find Virtual Hosts, TCP Port Scan, UDP Port Scan, Network Scan OpenVAS, URL Fuzzer, SQLi Scan, XSS Scan, WordPress Scan, Drupal Scan.

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.10 17 June 2020 Allow parameter customization for Find Subdomains
0.9 5 February 2020 Added API support for TCP Port Scan and UDP Port Scan
0.8 25 January 2020 Added follow_redirects parameter and workspace functionality
0.7 26 March 2019 Added API support for SQLi Scan and XSS Scan
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.
workspace_id Integer (optional) The id of the workspace you want your scan to be placed into. To find the ids of your workspaces, use the get_workspaces method.
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
target_id Integer The target of the scan
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"
}

Get targets

This operation returns the list of targets belonging to the current user, including their names.

Request parameters:
Name Type Description Value
op String Get the list of targets get_targets
limit Integer Limit the number of returned targets
workspace_id Integer (optional) Only show the targets in this workspace. To find the ids of your workspaces, use the get_workspaces method.
Request example:
{
    "op":       "get_targets",
    "limit":    3
}

Response parameters:
Name Type Description Value
op_status String The status of the operation
  • success
  • fail
targets Array The list of targets 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":    [
        {
            "target_id":    8785534,
            "name":         "176.28.50.165",
            "workspace_id": 36489826
        },
        {
            "target_id":    9796332,
            "name":         "testphp.vulnweb.com",
            "workspace_id": 42809779
        },
        {
            "target_id":    65442312,
            "name":         "http:\/\/testphp.vulnweb.com\/",
            "workspace_id": 42809779
        }
    ]
}

Get workspaces

This operation returns the list of workspaces belonging to the current user, including their names.

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

Response parameters:
Name Type Description Value
op_status String The status of the operation
  • success
  • fail
workspaces Array The list of workspaces 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",
    "workspaces": [
        {
            "id": 42809779,
            "name": "My Workspace"
        },
        {
            "id": 73878548,
            "name": "VPN"
        },
        {
            "id": 36489826,
            "name": "Pentest firstexample.org"
        },
        {
            "id": 19939241,
            "name": "Pentest otherexample.org"
        }
    ]
}

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

Delete scan

This operation deletes a scan which is not running.

Request parameters:
Name Type Description Value
op String Delete a scan delete_scan
scan_id Integer The id of the scan that will be deleted
Request example:
{
    "op":       "delete_scan",
    "scan_id":  194764
}

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

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 workspace The requested workspace does not exist.
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.

Website 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_new
follow_redirects Boolean Follow HTTP redirects and scan the final redirect location. This will create a new target if it does not already exist. The default value of this parameter is false.
Start scan example:
{
    "op":                   "start_scan",
    "tool_id":              170,
    "tool_params": {
        "target":               "http://demo.pentest-tools.com/webapp/",
        "scan_type":            "quick",
        "follow_redirects":     false
    }
}

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
web_details String Extract also web server details for each subdomain (Server Type, Operating System, Technlogy, Web Platform, Page Title). Turn this option off for faster results
  • on (default)
  • off
subdom_details String Show IP information (netname, country)
  • on
  • off (default)
Search methods
do_zone_transfer String DNS records (NS, MX, TXT, AXFR)
  • on (default)
  • off
do_dns_enumeration String DNS enumeration
  • on (default)
  • off
do_ctr_search String Certificate Transparency Logs
  • on (default)
  • off
do_ext_search String Subdomains from external APIs
  • on (default)
  • off
do_bing_search String Bing search
  • on (default)
  • off
do_google_search String Google search
  • on (default)
  • off
do_website_search String Extract from HTML links
  • on (default)
  • off
do_ssl_search String Extract from SSL certificates
  • on (default)
  • off
do_revdns_search String Reverse DNS on target IP ranges
  • on (default)
  • off
do_smart_search String Smart DNS search - Disabling this option will speed up the scan if the target has a large number of subdomains, but might reduce the number of results
  • on (default)
  • off
Start scan example:
    {
        "op":               "start_scan",
        "tool_id":          20,
        "tool_params": {
            "target":       "bbc.com",
            "web_details":  "off"
        }
    }

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

TCP Port Scan

Name Type Description Value
tool_id Integer The id of this tool 70
target String The IP address or hostname that will be scanned
do_service_detect String Detect service version (optional)
  • on (default)
  • off
do_os_detect String Detect operating system (optional)
  • on
  • off (default)
do_traceroute String Do traceroute (optional)
  • on
  • off (default)
check_alive String Use host discovery to check if target is alive (optional)
  • on (default)
  • off
port_type String Port type
  • common_ports (default)
  • port_range
  • port_list
commonms String Type of common ports
Used when port_type is set to common_ports
  • Top 10 ports
  • Top 100 ports (default)
  • Top 1000 ports
  • Top 5000 ports
start_port Integer Start port used when port_type is set to port_range
end_port Integer End port used when port_type is set to port_range
list_of_ports String Comma separated list of ports
Used when port_type is set to port_list
Example: 22,80,443
Start scan example:
{
    "op":               "start_scan",
    "tool_id":          70,
    "tool_params": {
        "target":               "demo.pentest-tools.com",
        "do_service_detect":    "off",
        "do_os_detect":         "on",
        "do_traceroute":        "on",
        "check_alive":          "on",
        "port_type":            "port_list",
        "list_of_ports":        "22,80,443"
    }
}

UDP Port Scan

Name Type Description Value
tool_id Integer The id of this tool 80
target String The IP address or hostname that will be scanned
do_service_detect String Detect service version (optional)
  • on
  • off (default)
do_os_detect String Detect operating system (optional)
  • on
  • off (default)
check_alive String Use host discovery to check if target is alive (optional)
  • on (default)
  • off
port_type String Port type
  • common_ports (default)
  • port_range
  • port_list
commonms String Type of common ports
Used when port_type is set to common_ports
  • Top 10 ports
  • Top 100 ports (default)
  • Top 1000 ports
  • Top 5000 ports
start_port Integer Start port used when port_type is set to port_range
end_port Integer End port used when port_type is set to port_range
list_of_ports String Comma separated list of ports
Used when port_type is set to port_list
Example: 53,67,68
Start scan example:
{
    "op":               "start_scan",
    "tool_id":          80,
    "tool_params": {
        "target":               "demo.pentest-tools.com",
        "do_service_detect":    "off",
        "do_os_detect":         "on",
        "do_traceroute":        "on",
        "check_alive":          "on",
        "port_type":            "common_ports",
        "commonms":             "Top 10 ports"
    }
}

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
follow_redirects Boolean Follow HTTP redirects and scan the final redirect location. This will create a new target if it does not already exist. The default value of this parameter is false.
*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"
    }
}

SQLi Scan

Name Type Description Value
tool_id Integer The id of this tool 370
target String The target URL that will be scanned
scan_type String The type of scan that you want to be performed
  • light
  • full
follow_redirects Boolean Follow HTTP redirects and scan the final redirect location. This will create a new target if it does not already exist. The default value of this parameter is false.
Start scan example:
{
    "op":               "start_scan",
    "tool_id":          370,
    "tool_params": {
        "target":       "http://demo.pentest-tools.com",
        "scan_type":    "light"
    }
}

XSS Scan

Name Type Description Value
tool_id Integer The id of this tool 360
target String The target URL that will be scanned
scan_type String The type of scan that you want to be performed
  • light
  • full
follow_redirects Boolean Follow HTTP redirects and scan the final redirect location. This will create a new target if it does not already exist. The default value of this parameter is false.
Start scan example:
{
    "op":               "start_scan",
    "tool_id":          360,
    "tool_params": {
        "target":       "http://demo.pentest-tools.com",
        "scan_type":    "light"
    }
}

WordPress Scan

Name Type Description Value
tool_id Integer The id of this tool 270
target String The target URL that will be scanned
detection_mode String What detection mode to use in order to find WordPress version, plugins and enumerate users
  • passive
  • aggressive
follow_redirects Boolean Follow HTTP redirects and scan the final redirect location. This will create a new target if it does not already exist. The default value of this parameter is false.
Start scan example:
{
    "op":               "start_scan",
    "tool_id":          270,
    "tool_params": {
        "target":               "http://demo.pentest-tools.com/wordpress/",
        "detection_mode":       "aggressive",
        "follow_redirects":     true
    }
}

Drupal Scan

Name Type Description Value
tool_id Integer The id of this tool 280
target String The target URL that will be scanned
follow_redirects Boolean Follow HTTP redirects and scan the final redirect location. This will create a new target if it does not already exist. The default value of this parameter is false.
Start scan example:
{
    "op":               "start_scan",
    "tool_id":          280,
    "tool_params": {
        "target":       "http://demo.pentest-tools.com/drupal/"
    }
}