Pentest-Tools.com REST API

https://pentest-tools.com/docs/api/v2
Admin
Pentest-Tools.com REST API enables security teams to programmatically manage targets, scans,...
Tokens:26,612
Snippets:102
Trust Score:7.5
Update:8 months ago
Show doc for...
Tokens:
Raw
### Scan Initiation Response Example

Source: https://pentest-tools.com/docs/api/v2/scans

This is an example of a successful response (201 Created) when initiating a scan. It returns the ID of the newly created scan and the target ID associated with it.

```json
{
  "created_id": 420323,
  "target_id": 5426912
}
```

--------------------------------

### Example VPN Profiles Response

Source: https://pentest-tools.com/docs/api/v2/vpn_profiles

This is an example of a successful (200 OK) response when retrieving VPN profiles from the Pentest-Tools.com API. The response is a JSON array, where each object represents a VPN profile with its ID, name, and type.

```json
[
  {
    "id": "990a9f5c-d0df-4903-91fb-35b9fea0077d",
    "name": "Internal Network Agent",
    "type": "VPN Agent"
  }
]
```

--------------------------------

### GET /targets

Source: https://pentest-tools.com/docs/api/v2/sample-api-client

Retrieves a list of all targets associated with the authenticated user.

```APIDOC
## GET /targets

### Description
Retrieves a list of all targets associated with the authenticated user.

### Method
GET

### Endpoint
/targets

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
null
```

### Response
#### Success Response (200)
- **data** (array) - A list of target objects.
- **status** (string) - The status of the operation (e.g., "success").

#### Response Example
```json
{
  "data": [
    {
      "id": 456,
      "name": "http://example.com",
      "description": "Example website for testing",
      "workspace_id": 123
    },
    {
      "id": 789,
      "name": "192.168.1.1",
      "description": "Internal server",
      "workspace_id": 123
    }
  ],
  "status": "success"
}
```
```

--------------------------------

### GET /reports/{id}/download

Source: https://pentest-tools.com/docs/api/v2/reports

Initiates the download of a specific report by its unique ID.

```APIDOC
## GET /reports/{id}/download

### Description
Initiates the download of a specific report by its ID.

### Method
GET

### Endpoint
/reports/{id}/download

### Path Parameters
- **id** (integer) - Required - The unique identifier of the report to download.

### Request Example
```bash
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/reports/123/download \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

### Response
#### Success Response (200)
The response will be the report file content in the specified format.
```

--------------------------------

### GET /targets/{target_id}

Source: https://pentest-tools.com/docs/api/v2/sample-api-client

Retrieves details of a specific target by its ID.

```APIDOC
## GET /targets/{target_id}

### Description
Retrieves details of a specific target by its ID. This endpoint can also be used to update the description of a target.

### Method
GET

### Endpoint
/targets/{target_id}

### Parameters
#### Path Parameters
- **target_id** (integer) - Required - The ID of the target to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
null
```

### Response
#### Success Response (200)
- **data** (object) - An object containing the details of the target.
- **status** (string) - The status of the operation (e.g., "success").

#### Response Example
```json
{
  "data": {
    "id": 456,
    "name": "http://example.com",
    "description": "Example website for testing",
    "workspace_id": 123
  },
  "status": "success"
}
```
```

--------------------------------

### Execute and Monitor a Pentest-Tools Scan

Source: https://pentest-tools.com/docs/api/v2/sample-api-client

Demonstrates starting a web server scan, polling for its completion, and retrieving the JSON report. It utilizes functions like `start_scan`, `get_scan_status`, and `get_output`. Error handling for JSON decoding and scan initiation is included.

```python
import requests
import traceback
import sys
import time
import json

# Assume Tool, start_scan, get_scan_status, get_output are defined elsewhere
# API_URL and HEADERS are also assumed to be defined globally or passed in

# Placeholder for assumed functions and constants
class Tool:
    WEBSITE_SCANNER = 1

def start_scan(target, tool_id, tool_params):
    # This is a placeholder for the actual API call
    print(f"Starting scan for {target} with tool {tool_id}")
    # Simulate a successful response
    return requests.Response()

def get_scan_status(scan_id):
    # This is a placeholder for the actual API call
    print(f"Getting status for scan {scan_id}")
    # Simulate a finished status
    mock_response = requests.Response()
    mock_response.json = lambda: {"data": {"status_name": "finished"}}
    return mock_response

def get_output(scan_id):
    # This is a placeholder for the actual API call
    print(f"Getting output for scan {scan_id}")
    # Simulate a JSON report
    mock_response = requests.Response()
    mock_response.json = lambda: {"report": "sample_report_data"}
    return mock_response

API_URL = "YOUR_API_URL"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

if __name__ == "__main__":
    # `tool_params` is specific to the tool
    # Here we do a light scan with the Web Server Scanner
    tool_id = Tool.WEBSITE_SCANNER
    tool_params = {"scan_type": "light"}
    target = "http://demo.pentest-tools.com/webapp/"

    # Start the scan
    res = start_scan(target, tool_id, tool_params)
    try:
        res_json = res.json()
    except requests.exceptions.JSONDecodeError:
        print(traceback.format_exc())
        print(res.text)
        sys.exit(1)

    # Get the new `scan_id`
    if "data" in res_json and "created_id" in res_json["data"]:
        scan_id = res_json["data"]["created_id"]
        print(f"Started scan {scan_id}")
    else:
        print("Scan could not start")
        print(f"Status: {res_json['status']}, message: {res_json['message']}")
        sys.exit(1)

    # Poll periodically to check if the scan is finished
    while True:
        time.sleep(2)

        # Get the status of our scan
        status = get_scan_status(scan_id)
        status_json = status.json()
        status_name = status_json["data"]["status_name"]

        if status_name == "finished":
            print(f"Scan status: {status_json['data']}")
            # Get the HTML report and write it to a file
            print("Getting JSON report")
            res = get_output(scan_id)
            output_json = res.json()

            with open("report.json", "w") as file:
                json.dump(output_json, file)

            print("JSON report written to file")
            break

```

--------------------------------

### Get All Workspaces (cURL)

Source: https://pentest-tools.com/docs/api/v2/workspaces

Retrieves a list of all workspaces associated with the authenticated user. Requires an API key for authorization. Returns a JSON array of workspace objects.

```shell
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/workspaces \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Retrieve Targets from Pentest-Tools API

Source: https://pentest-tools.com/docs/api/v2/sample-api-client

Fetches a list of all targets associated with the authenticated API key. It sends a GET request to the /targets endpoint of the Pentest-Tools API.

```python
import requests

API_URL = "YOUR_API_URL"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

def get_targets(api_url=API_URL, headers=HEADERS):
    """Get a list of targets"""
    return requests.get(api_url + "/targets", headers=headers)
```

--------------------------------

### POST /scans

Source: https://pentest-tools.com/docs/api/v2/scans

Initiates a new scan. This endpoint allows users to start a scan for a given target using a specific tool.

```APIDOC
## POST /scans

### Description
Starts a new scan. You need to provide the `tool_id` and `target_id` to initiate the scan.

### Method
POST

### Endpoint
/scans

### Request Body
- **tool_id** (integer) - Required - The ID of the tool to use for the scan.
- **target_id** (integer) - Required - The ID of the target to scan.

### Request Example
```json
{
  "tool_id": 1,
  "target_id": 1
}
```

### Response
#### Success Response (200 or 201)
- **id** (integer) - The ID of the newly created scan.
- **tool_id** (integer) - The ID of the tool used for the scan.
- **target_id** (integer) - The ID of the target for the scan.
- **status_name** (string) - The initial status of the scan (e.g., "waiting").

#### Response Example
```json
{
  "id": 123,
  "tool_id": 1,
  "target_id": 1,
  "status_name": "waiting"
}
```

#### Error Responses
- **400** Invalid parameters (e.g., missing `tool_id` or `target_id`)
- **401** API key is missing or invalid
- **404** The specified tool or target was not found
- **500** Internal server error
```

--------------------------------

### Vulnerability Response Example (JSON)

Source: https://pentest-tools.com/docs/api/v2/finding_templates

This JSON object details a specific vulnerability, 'OS Command Injection', found in a 'Web Server' product. It includes vendor, product, discovery date, a detailed description of the vulnerability (CVE-2020-5902), how to reproduce it, its public description, risk assessment, and recommendations for mitigation. It also lists related CVEs, exploit capabilities, and publication/update dates.

```json
[
  {
    "name": "OS Command Injection",
    "software_type": "Web Server",
    "vendor": "Microsoft",
    "product": "Laravel",
    "date": "2020-12-25T00:00:00.000Z",
    "codename": "OMIGOD",
    "vuln_description": "We found that the target F5 BIG-IP server is vulnerable to CVE-2020-5902, a Remote Code Execution vulnerability, affecting the Traffic Management User Interface (TMUI) component, which is publicly accessible.\nThe root cause of this vulnerability consists in a broken parser logic in the Tomcat endpoint. This allows an unauthenticated malicious attacker to access any file stored on the server.\nWe have detected this by sending a HTTP GET request to the tmui endpoint, containing the /etc/passwd file, and looking for the output of the file in the response.",
    "how_to_reproduce": "…",
    "public_vuln_description": "F5 BIG-IP server is affected by a Remote Code Execution vulnerability, located in the Traffic Management User Interface (TMUI) component, which is publicly accessible.\nThe root cause of this vulnerability consists in a broken parser logic in the Tomcat endpoint.\nThis allows an unauthenticated malicious attacker to access any file stored on the server or to execute arbitrary commands on the server.",
    "risk_description": "The risk exists that a remote unauthenticated attacker can fully compromise the F5 BIG-IP server in order to steal confidential information, install ransomware or pivot to the internal network.",
    "recommendation": "We recommend upgrading your F5 BIG-IP server to the latest version.",
    "public_recommendation": "Upgrade F5 BIG-IP server to the latest version or to a non-vulnerable version listed in K52145254.",
    "references": "<a href=\"https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-5902\" target=\"_blank\">https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-5902</a><br><a href=\"https://pentest-tools.com/blog/big-ip-tmui-rce/\" target=\"_blank\">https://pentest-tools.com/blog/big-ip-tmui-rce/</a><br><a href=\"https://www.ptsecurity.com/ww-en/about/news/f5-fixes-critical-vulnerability-discovered-by-positive-technologies-in-big-ip-application-delivery-controller/\" target=\"_blank\">https://www.ptsecurity.com/ww-en/about/news/f5-fixes-critical-vulnerability-discovered-by-positive-technologies-in-big-ip-application-delivery-controller/</a><br><a href=\"https://research.nccgroup.com/2020/07/12/understanding-the-root-cause-of-f5-networks-k52145254-tmui-rce-vulnerability-cve-2020-5902/\" target=\"_blank\">https://research.nccgroup.com/2020/07/12/understanding-the-root-cause-of-f5-networks-k52145254-tmui-rce-vulnerability-cve-2020-5902/</a>",
    "cve": [
      "CVE-2021-26855",
      "CVE-2021-27065"
    ],
    "ptt_exploit_capabilities": [
      "RCE",
      "File Read"
    ],
    "vuln_id": "NETSCAN-SNIPER-CVE-2021-42013-RCE",
    "in_cisa_catalog": true,
    "published": "2021-08-04T00:00:00.000Z",
    "updated": "2022-05-25T00:00:00.000Z"
  }
]
```

--------------------------------

### GET /targets

Source: https://pentest-tools.com/docs/api/v2/targets

Retrieves a list of all targets. Supports filtering by workspace, target type, and pagination.

```APIDOC
## GET /targets

### Description
Retrieves a list of all targets. Supports filtering by workspace, target type, and pagination.

### Method
GET

### Endpoint
/targets

### Query Parameters
- **workspace_id** (integer) - Optional - ID of the workspace to show targets from.
- **type** (string) - Optional - The type of target. Possible values: "hostname", "ip_address", "url".
- **limit** (integer) - Optional - The maximum number of targets to return. Default: 1000. Min: 1. Max: 1000.
- **page** (integer) - Optional - The page number to return. Default: 1. Min: 1.

### Responses
#### Success Response (200)
- **id** (integer) - Description of the target.
- **name** (string) - Name of the target.
- **type** (string) - Type of the target.
- **description** (string) - Description of the target.
- **workspace_id** (integer) - The ID of the workspace the target belongs to.

#### Error Responses
- **400** - Invalid parameters.
- **401** - API key is missing or invalid.
- **404** - The object with the given ID was not found.
- **500** - Internal server error.

### Request Example
```bash
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/targets \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

### Response Example (200 OK)
```json
[
  {
    "id": 1,
    "name": "example.org",
    "type": "hostname",
    "description": "…",
    "workspace_id": 1
  }
]
```
```

--------------------------------

### GET /reports

Source: https://pentest-tools.com/docs/api/v2/reports

Retrieves a list of all reports associated with the authenticated user. Supports filtering and pagination.

```APIDOC
## GET /reports

### Description
Retrieves a list of all reports.

### Method
GET

### Endpoint
/reports

### Query Parameters
- **limit** (integer) - Optional - Maximum number of reports to return.
- **offset** (integer) - Optional - Number of reports to skip before starting to collect the result set.

### Request Example
```bash
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/reports \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the report.
- **download_name** (string) - The filename for the downloaded report.
- **status** (string) - The current status of the report generation (e.g., 'waiting', 'completed', 'failed').
- **format** (string) - The format of the report (e.g., 'pdf', 'html', 'json').
- **generation_date** (string) - The date and time when the report was generated.
- **expiration_date** (string) - The date and time when the report will expire.

#### Response Example
```json
[
  {
    "id": 1,
    "download_name": "report.pdf",
    "status": "waiting",
    "format": "pdf",
    "generation_date": "2023-10-27T10:00:00Z",
    "expiration_date": "2023-11-26T10:00:00Z"
  }
]
```
```

--------------------------------

### Get All Reports (cURL)

Source: https://pentest-tools.com/docs/api/v2/reports

This snippet demonstrates how to retrieve a list of all reports using a cURL command. It requires an API key for authorization and specifies the 'application/json' accept header.

```shell
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/reports \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Python API Client for Pentest-Tools v2

Source: https://pentest-tools.com/docs/api/v2/sample-api-client

This Python script acts as a client for the Pentest-Tools.com v2 API. It includes functions for starting scans (by target URL or target ID), retrieving scan information (list, status, output), stopping and deleting scans, and managing targets. A valid API key is mandatory for authentication.

```python
#!/usr/bin/python

"""
Sample client for the v2 API of Pentest-Tools.com.
This client starts a Web Server Scan, queries the output and writes the report in a HTML and a PDF file.?
A valid API key is necessary for this program to work.

This client contains sample requests for most API methods

API Reference: https://pentest-tools.com/docs/api/v2

Python 3.9+ is assumed here
"""

import json
import sys
import time
import traceback
import urllib

import requests

API_KEY = "xxxxxxxxxxxxxxxxxxxxxx"  #    <-- Place your API key here
API_URL = "https://app.pentest-tools.com/api/v2"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


class Tool:
    """Map the tool_id that the API knows to the tool name"""

    SUBDOMAIN_FINDER = 20
    PORT_SCANNER = 70
    URL_FUZZER = 90
    FIND_VHOSTS = 160
    WEBSITE_SCANNER = 170
    SHARE_POINT_SCANNER = 260
    WORDPRESS_SCANNER = 270
    DRUPAL_SCANNER = 280
    JOOMLA_SCANNER = 290
    WEBSITE_RECON = 310
    NETWORK_SCANNER = 350
    DOMAIN_FINDER = 390
    PASSWORD_AUDITOR = 400
    SSL_SCANNER = 450
    SNIPER = 490
    WAF_DETECTOR = 500
    API_SCANNER = 510
    CLOUD_SCANNER = 520
    KUBERNETES_SCANNER = 540


"""Scans

Two common ways to start a scan is by using either `target` or `target_id`.

`target` needs to be a simple URL, like "https://example.org". `target_id` is an
integer you can get from the `get_targets` method.

For both, you need:
- tool_id: ID of the tool you want to use
- tool_params: Options for the tool
- target or target_id: The target you want to scan, depending on the chosen method
"""


def start_scan(target, tool_id, tool_params, api_url=API_URL, headers=HEADERS):
    """Start a scan using the given target name"""
    data = {"tool_id": tool_id, "target_name": target, "tool_params": tool_params}
    return requests.post(api_url + "/scans", headers=headers, json=data)


def start_scan_by_targetid(target_id, tool_id, tool_params, api_url=API_URL, headers=HEADERS):
    """Start a scan using the given target_id"""
    data = {"tool_id": tool_id, "target_id": target_id, "tool_params": tool_params}
    return requests.post(api_url + "/scans", headers=headers, json=data)


"""Interacting with scans

After you started a scan, through either method, you may want to interact with it. These are the most commonly
used methods for interacting with scans after they have been started.

A scan is identified by a `scan_id`, which can be obtained from running `GET $API/scans`,
or `get_scans` from this client.

You can check the status of a scan using the `get_scan_status` function.

You can get the JSON output of a scan by calling `get_output` with a suitable `scan_id`.
The previous feature of getting output in a chosen format has moved to the `start_scan` function, through an URL callback. TODO: example

You may want to stop a running scan, which you can do with `stop_scan`.
Should you want to delete a scan entirely, tou can use the `delete_scan` function.

"""


def get_scans(workspace_id=None, target_id=None, api_url=API_URL, headers=HEADERS):
    """Get a list of scans

    Specific parameters:
    - workspace_id  -- when set, only the scans from this workspace will be returned
                        (you can get a list of workspaces by using the `get_workspaces` operation)
    - target_id     -- when set, only the scans run on this target will be returned
                        (use `get_targets` for the target list)
    """
    data = {}
    if workspace_id is not None:
        data["workspace_id"] = workspace_id
    if target_id is not None:
        data["target_id"] = target_id
    params = "?" + urllib.parse.urlencode(data)
    return requests.get(api_url + f"/scans{params}", headers=headers)

def get_scan_status(scan_id, api_url=API_URL, headers=HEADERS):
    """Get the status of a scan"""
    return requests.get(api_url + f"/scans/{scan_id}", headers=headers)

def get_output(scan_id, api_url=API_URL, headers=HEADERS):
    """Get the output of a scan"""
    return requests.get(api_url + f"/scans/{scan_id}/output", headers=headers)

def stop_scan(scan_id, api_url=API_URL, headers=HEADERS):
    """Stop a running scan"""
    return requests.post(api_url + f"/scans/{scan_id}/stop", headers=headers)

def delete_scan(scan_id, api_url=API_URL, headers=HEADERS):
    """Delete a scan"""
    return requests.delete(api_url + f"/scans/{scan_id}", headers=headers)


"""Targets

Although you can interact with targets manually, by inputting the URL everytime, Pentest-Tools offers facilities of working with targets.

The simples workflow involves three functions: Add a target with `add_target`, get all targets with `get_targets` and get a single target with
`get_target_by_id`.

Deleting and updating targets remain, for now, an operation you can only do throught the site.
"""

```

--------------------------------

### GET /wordlists

Source: https://pentest-tools.com/docs/api/v2/wordlists

Retrieves a list of all available wordlists. This endpoint allows you to fetch basic information about predefined and user-created wordlists.

```APIDOC
## GET /wordlists

### Description
Retrieves a list of all available wordlists. This endpoint allows you to fetch basic information about predefined and user-created wordlists.

### Method
GET

### Endpoint
/wordlists

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Example
```bash
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/wordlists \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the wordlist.
- **name** (string) - The name of the wordlist.
- **description** (string) - A brief description of the wordlist.
- **num_words** (integer) - The number of words contained in the wordlist.
- **predefined** (boolean) - Indicates if the wordlist is a predefined system wordlist.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "URL Fuzzer (default)",
    "description": "This is the standard wordlist used by URL Fuzzer",
    "num_words": 254,
    "predefined": true
  }
]
```
```

--------------------------------

### Get All Finding Templates (cURL)

Source: https://pentest-tools.com/docs/api/v2/finding_templates

This snippet demonstrates how to retrieve all finding templates using a cURL request. It requires an 'accept' header for JSON and an 'authorization' header with a Bearer token. The endpoint is /public/finding_templates.

```curl
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/public/finding_templates \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### GET /reports/{id}/download

Source: https://pentest-tools.com/docs/api/v2/reports

Downloads a specific report by its ID. The report will be provided in the format specified during its generation.

```APIDOC
## GET /reports/{id}/download

### Description
Downloads a specific report by its ID. The report will be provided in the format specified during its generation.

### Method
GET

### Endpoint
/reports/{id}/download

#### Path Parameters
- **id** (integer) - Required - The ID of the report to download.

### Request Example
```bash
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/reports/{id}/download \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

### Response
#### Success Response (200)
- The report file content.

#### Other Responses
- **202**: The report is still being generated.
- **204**: There is no data for the report. This may be due to a failure in report generation.
- **401**: API key is missing or invalid.
- **403**: You can't perform this action.
- **404**: The object with the given ID was not found.
- **500**: Internal server error.
```

--------------------------------

### GET /scans

Source: https://pentest-tools.com/docs/api/v2/scans

Retrieves a list of scans. Supports filtering by tool, workspace, target, status, and pagination.

```APIDOC
## GET /scans

### Description
Retrieves a list of scans. You can filter scans by `tool_id`, `workspace_id`, `target_id`, and `status`. Pagination is supported using `limit` and `page` parameters. You can also filter by a time interval using `start_time`.

### Method
GET

### Endpoint
/scans

### Query Parameters
- **tool_id** (integer) - Optional - ID of the tool to show scans from.
- **workspace_id** (integer) - Optional - ID of the workspace to show scans from. If not set, the scans from the active workspace will be returned.
- **target_id** (integer) - Optional - ID of the target to show scans from.
- **status** (string) - Optional - Status of the scans to be shown. Possible values: `"running"`, `"finished"`, `"failed to start"`, `"stopped"`, `"timed out"`, `"waiting"`, `"aborted"`, `"VPN connection error"`, `"auth failed"`, `"connection error"`.
- **limit** (integer) - Optional - The maximum number of scans to return. Default: 1000. Min: 1. Max: 1000.
- **page** (integer) - Optional - The page number to return. Default: 1. Min: 1.
- **start_time** (object) - Optional - Start time interval of the scans to be shown.
  - **start** (date-time) - The start of the time interval.
  - **end** (date-time) - The end of the time interval.

### Request Example
```curl
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/scans \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the scan.
- **tool_id** (integer) - Identifier for the tool used in the scan.
- **target_id** (integer) - Identifier for the target of the scan.
- **status_name** (string) - The current status of the scan (e.g., "running", "finished").
- **vpn_scan** (boolean) - Indicates if the scan was performed via VPN.
- **progress** (number) - The progress of the scan, typically a value between 0 and 1.
- **result_summary** (object) - A summary of the scan results.
  - **text** (string) - A textual summary of the results.
  - **critical** (integer) - Number of critical findings.
  - **high** (integer) - Number of high severity findings.
  - **medium** (integer) - Number of medium severity findings.
  - **low** (integer) - Number of low severity findings.
  - **info** (integer) - Number of informational findings.
- **start_time** (string) - The timestamp when the scan started.
- **end_time** (string) - The timestamp when the scan ended.
- **duration** (integer) - The duration of the scan in seconds.
- **num_tests** (integer) - The total number of tests performed during the scan.
- **num_finished_tests** (integer) - The number of tests that have finished.
- **status_message** (string) - A message providing more details about the scan's status.

#### Response Example
```json
[
  {
    "id": 1,
    "tool_id": 1,
    "target_id": 1,
    "status_name": "running",
    "vpn_scan": true,
    "progress": 1,
    "result_summary": {
      "text": "…",
      "critical": 1,
      "high": 1,
      "medium": 1,
      "low": 1,
      "info": 1
    },
    "start_time": "…",
    "end_time": "…",
    "duration": 1,
    "num_tests": 1,
    "num_finished_tests": 1,
    "status_message": "…"
  }
]
```

#### Error Responses
- **400** Invalid parameters
- **401** API key is missing or invalid
- **404** The object with the given ID was not found
- **500** Internal server error
```

--------------------------------

### GET /public/finding_templates

Source: https://pentest-tools.com/docs/api/v2/finding_templates

Retrieves a list of all finding templates available in the Pentest-Tools platform. This endpoint allows filtering by vulnerability ID type, exploit capabilities, and pagination.

```APIDOC
## GET /public/finding_templates

### Description
Retrieves a list of all finding templates. You can filter results by vulnerability ID type, whether they have exploit capabilities, and control pagination with limit and offset.

### Method
GET

### Endpoint
/public/finding_templates

### Query Parameters
- **vuln_id_type** (string) - Optional - The vuln ID type of the vulnerability (e.g., "NETSCAN", "WEBSCAN").
- **has_ptt_exploit** (boolean) - Optional - Only show vulnerabilities which have/don't have exploit capabilities. Setting this to `false` will only show vulnerabilities without any capabilities.
- **limit** (integer) - Optional - The maximum number of templates to return.
- **offset** (integer) - Optional - The offset to start returning templates from. This does not work without the `limit` parameter.

### Responses
#### Success Response (200 OK)
- **(Array of Objects)** - A list of finding template objects.

#### Error Response (400 Bad Request)
- **(Object)** - Indicates invalid parameters were provided.

#### Error Response (500 Internal Server Error)
- **(Object)** - Indicates an internal server error.

### Request Example
```curl
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/public/finding_templates \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

### Response Example (Success)
```json
[
  {
    "id": "example_id_1",
    "name": "Example Finding Template 1",
    "description": "This is a sample finding template.",
    "vuln_id_type": "WEBSCAN",
    "has_ptt_exploit": true
  },
  {
    "id": "example_id_2",
    "name": "Example Finding Template 2",
    "description": "Another sample finding template.",
    "vuln_id_type": "NETSCAN",
    "has_ptt_exploit": false
  }
]
```
```

--------------------------------

### Get All Wordlists (curl)

Source: https://pentest-tools.com/docs/api/v2/wordlists

Retrieves a list of all available wordlists. Requires an 'authorization' header with a Bearer token. Returns a JSON array of wordlist objects.

```curl
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/wordlists \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Scans API

Source: https://pentest-tools.com/docs/api/v2/sample-api-client

Endpoints for managing and interacting with security scans. This includes starting new scans, retrieving scan status, fetching scan output, stopping running scans, and deleting scans.

```APIDOC
## POST /scans

### Description
Starts a new security scan. You can specify the target using either a URL (`target_name`) or a `target_id`. Requires `tool_id` and `tool_params`.

### Method
POST

### Endpoint
/scans

### Parameters
#### Request Body
- **tool_id** (integer) - Required - The ID of the tool to use for the scan.
- **target_name** (string) - Optional - The URL of the target to scan (e.g., "https://example.org").
- **target_id** (integer) - Optional - The ID of a pre-registered target.
- **tool_params** (object) - Required - Parameters specific to the chosen tool.

### Request Example
```json
{
  "tool_id": 170, 
  "target_name": "https://example.com",
  "tool_params": {
    "subdomain": "www.example.com"
  }
}
```

### Response
#### Success Response (200)
- **scan_id** (integer) - The ID of the newly created scan.
- **status** (string) - The initial status of the scan.

#### Response Example
```json
{
  "scan_id": 12345,
  "status": "running"
}
```

## GET /scans

### Description
Retrieves a list of scans. You can filter scans by `workspace_id` or `target_id`.

### Method
GET

### Endpoint
/scans

### Parameters
#### Query Parameters
- **workspace_id** (integer) - Optional - Filters scans belonging to a specific workspace.
- **target_id** (integer) - Optional - Filters scans associated with a specific target.

### Response
#### Success Response (200)
- An array of scan objects, each containing details like `scan_id`, `tool_id`, `target_id`, `status`, etc.

#### Response Example
```json
[
  {
    "scan_id": 12345,
    "tool_id": 170,
    "target_id": 678,
    "status": "completed",
    "start_time": "2023-10-27T10:00:00Z"
  }
]
```

## GET /scans/{scan_id}

### Description
Retrieves the status and details of a specific scan using its `scan_id`.

### Method
GET

### Endpoint
/scans/{scan_id}

### Parameters
#### Path Parameters
- **scan_id** (integer) - Required - The ID of the scan to retrieve status for.

### Response
#### Success Response (200)
- A scan object containing details like `scan_id`, `tool_id`, `target_id`, `status`, `progress`, etc.

#### Response Example
```json
{
  "scan_id": 12345,
  "tool_id": 170,
  "target_id": 678,
  "status": "completed",
  "progress": 100,
  "end_time": "2023-10-27T10:30:00Z"
}
```

## GET /scans/{scan_id}/output

### Description
Retrieves the output data of a completed scan using its `scan_id`.

### Method
GET

### Endpoint
/scans/{scan_id}/output

### Parameters
#### Path Parameters
- **scan_id** (integer) - Required - The ID of the scan whose output is to be retrieved.

### Response
#### Success Response (200)
- The scan output in JSON format.

#### Response Example
```json
{
  "scan_results": {
    "vulnerabilities": [],
    "findings": []
  }
}
```

## POST /scans/{scan_id}/stop

### Description
Stops a scan that is currently in progress.

### Method
POST

### Endpoint
/scans/{scan_id}/stop

### Parameters
#### Path Parameters
- **scan_id** (integer) - Required - The ID of the scan to stop.

### Response
#### Success Response (200)
- A confirmation message indicating the scan has been stopped.

#### Response Example
```json
{
  "message": "Scan 12345 has been stopped."
}
```

## DELETE /scans/{scan_id}

### Description
Deletes a scan and its associated data.

### Method
DELETE

### Endpoint
/scans/{scan_id}

### Parameters
#### Path Parameters
- **scan_id** (integer) - Required - The ID of the scan to delete.

### Response
#### Success Response (200)
- A confirmation message indicating the scan has been deleted.

#### Response Example
```json
{
  "message": "Scan 12345 has been deleted."
}
```
```

--------------------------------

### Get Workspace by ID (cURL)

Source: https://pentest-tools.com/docs/api/v2/workspaces

Retrieves a specific workspace by its unique identifier. Requires the workspace ID as a path parameter and an API key for authentication. Returns the details of the requested workspace.

```shell
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/workspaces/{id} \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Retrieve Specific Target by ID from Pentest-Tools API

Source: https://pentest-tools.com/docs/api/v2/sample-api-client

Retrieves details for a specific target using its unique ID. This function sends a GET request to the /targets/{target_id} endpoint.

```python
import requests

API_URL = "YOUR_API_URL"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

def get_target_by_id(target_id, api_url=API_URL, headers=HEADERS):
    """Update the description of a target

    Specific parameters:
    - target_id     -- the ID of the updated target
    """
    return requests.get(api_url + f"/targets/{target_id}", headers=headers)
```

--------------------------------

### Get All Findings (cURL)

Source: https://pentest-tools.com/docs/api/v2/findings

Retrieves a list of all findings from the Pentest-Tools.com API v2. Requires an API key for authorization. Supports filtering by workspace, target, and task ID, and can group duplicate findings.

```bash
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/findings \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Get All Targets (cURL)

Source: https://pentest-tools.com/docs/api/v2/targets

Retrieves a list of all targets associated with the authenticated user. It supports filtering by workspace ID and target type, and allows for pagination and limiting the number of results. Requires an API key for authorization.

```shell
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/targets \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Get All VPN Profiles using cURL

Source: https://pentest-tools.com/docs/api/v2/vpn_profiles

This snippet demonstrates how to retrieve all VPN profiles from the Pentest-Tools.com API using a cURL command. It requires an 'accept' header for JSON and an 'authorization' header with a Bearer token. The response is a JSON array of VPN profile objects.

```shell
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/vpn_profiles \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Get All HTTP Loggers (cURL)

Source: https://pentest-tools.com/docs/api/v2/http_loggers

Retrieves a list of all HTTP loggers. Requires an API key for authorization. The response includes logger details such as ID, label, handler URL, active days, number of requests, and remaining requests.

```bash
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/http_loggers \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Get Scan Output by ID (cURL)

Source: https://pentest-tools.com/docs/api/v2/scans

Fetches the output of a specific scan, identified by its ID. The output can be requested in JSON or PDF format via the 'Accept' header. Authentication is mandatory.

```shell
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/scans/{id}/output \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Get Report by ID (cURL)

Source: https://pentest-tools.com/docs/api/v2/reports

This snippet illustrates how to fetch information for a specific report using its ID via a cURL command. It requires the report's ID in the path and valid authorization.

```shell
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/reports/{id} \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Get Finding by ID (cURL)

Source: https://pentest-tools.com/docs/api/v2/findings

Retrieves detailed information for a specific finding using its unique ID from the Pentest-Tools.com API v2. Requires an API key for authorization. Returns a 404 error if the finding is not found.

```bash
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/findings/{id} \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### Get All Scans using cURL

Source: https://pentest-tools.com/docs/api/v2/scans

Retrieves a list of all scans. This endpoint supports filtering by tool ID, workspace ID, target ID, status, and time range. It also allows for pagination and limiting the number of results. The response includes detailed information about each scan.

```curl
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/scans \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### GET /wordlists/{id}

Source: https://pentest-tools.com/docs/api/v2/wordlists

Retrieves detailed information about a specific wordlist using its ID. Use the `/wordlists/{id}/contents` endpoint to get the actual wordlist content.

```APIDOC
## GET /wordlists/{id}

### Description
Retrieves detailed information about a specific wordlist using its ID. Use the `/wordlists/{id}/contents` endpoint to get the actual wordlist content.

### Method
GET

### Endpoint
/wordlists/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the wordlist to retrieve.

#### Query Parameters
None

### Request Example
```bash
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/wordlists/{id} \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the wordlist.
- **name** (string) - The name of the wordlist.
- **description** (string) - A brief description of the wordlist.
- **num_words** (integer) - The number of words contained in the wordlist.
- **predefined** (boolean) - Indicates if the wordlist is a predefined system wordlist.

#### Response Example
```json
{
  "id": 1,
  "name": "URL Fuzzer (default)",
  "description": "This is the standard wordlist used by URL Fuzzer",
  "num_words": 254,
  "predefined": true
}
```
```

--------------------------------

### Get Wordlist Contents by ID (curl)

Source: https://pentest-tools.com/docs/api/v2/wordlists

Retrieves the contents of a specific wordlist, identified by its ID. Requires an 'authorization' header with a Bearer token. This endpoint is used to get the actual words within a wordlist.

```curl
curl --request GET \
  --url https://app.pentest-tools.com/api/v2/wordlists/{id}/contents \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {token}'
```

--------------------------------

### GET /scans/{id}

Source: https://pentest-tools.com/docs/api/v2/scans

Retrieves the details of a specific scan using its ID.

```APIDOC
## GET /scans/{id}

### Description
Retrieves the details of a specific scan using its ID.

### Method
GET

### Endpoint
/scans/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the scan to retrieve.
```
Tokens:
Raw