HostedScan API (V1)

Download OpenAPI specification:Download

Getting Started

Welcome to the HostedScan API documentation.

The best way to get acquainted with HostedScan is to head over to our website and start running some scans! Try it out here!

This documentation covers the API and webhook integrations. Use the API to run scans, get results, and manage risks. Use webhook integrations to receive real-time event notifications in your application.

Support

Any questions? Please email us at hello@hostedscan.com

API Overview

HostedScan offers a comprehensive REST API at https://api.hostedscan.com/v1.

Authentication

Authenticate by setting the X-HOSTEDSCAN-API-KEY request header as your API key.

Testing with Sample Data

To try out the APIs with sample data, use the api key `test-data-key``. Requests made with this api key will return sample responses. For example:

curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/scans

There are Try it! request samples throughout this documentation.

HTTP Responses

Status Code Details
200 OK - Successful request.
400 Bad Request - Invalid request parameters or missing required parameters.
401 Unauthorized - Invalid API key.
404 Not Found - No resource at the requested path.
500 Internal Server Error - Something went wrong on our server.

SDKs and Tools

The API is defined using the OpenAPI (Swagger) standard. To download the HostedScan OpenAPI definition file, use the download link at the top of the documentation.

There are tools to generate clients in most programming languages from OpenAPI definitions. The easiest way to get started is with the online swagger.io editor, which has many built-in client generators or check out this comprehensive list of client generators.

Many API tools, such as Postman, also support importing OpenAPI definitions.

Scans

Run scanners such as OpenVas, Nmap, and ZAP against your Targets.

Start a new Scan

Run a new vulnerability scan. Scan is created in the QUEUED state and will transition to RUNNING while it is in progress and then to SUCCEEDED once it is finished.

Choose the Targets to scan by sending either the target values (e.g. https://example.com or 123.123.123.123), the id of a Target already created in your HostedScan account, or using the tags feature and the Scan will automatically include all Targets with matching tags.

Request Body schema: application/json
type
string (RunnableScanType)
Enum: "NMAP" "NMAP_UDP" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SSLYZE"
targets
Array of strings

Targets to scan. e.g. ["example.com", "123.123.123.123"] Either tags, targets, or target_ids must be specified.

target_ids
Array of strings

Ids of the targets to scan. Either tags, targets, or target_ids must be specified.

tags
Array of strings

Tags to scan. e.g. ["prod", "web-server"] Either tags, targets, or target_ids must be specified.

use_authentication
boolean

Use authentication, if configured for the target(s). See https://hostedscan.com/authenticated-web-app-vulnerability-scan for more details.

Responses

Response Schema: application/json
required
object (Scan)

The created Scan object

Request samples

Content type
application/json
{
  • "type": "NMAP",
  • "targets": [
    • "string"
    ],
  • "target_ids": [
    • "string"
    ],
  • "tags": [
    • "string"
    ],
  • "use_authentication": true
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "string",
    • "type": "DEPENDABOT",
    • "state": "FAILED",
    • "progress": 0,
    • "risks": {
      • "new_open": [
        • {
          • "risk_id": "string"
          }
        ],
      • "still_open": [
        • {
          • "risk_id": "string"
          }
        ],
      • "closed": [
        • {
          • "risk_id": "string"
          }
        ]
      },
    • "results": [
      • {
        • "result_id": "string",
        • "content_type": "text/html"
        }
      ],
    • "requested_targets": [
      • {
        • "target_id": "string",
        • "target": "string"
        }
      ],
    • "resolved_targets": [
      • {
        • "target_id": "string",
        • "resolved_target": "string"
        }
      ],
    • "skipped_targets": [
      • {
        • "target_id": "string",
        • "skipped_reason": "string"
        }
      ]
    }
}

List Scans

Returns all Scans

query Parameters
page_token
string

If there are more than 500 objects to return, the results will be truncated. Use page_token to request additional pages of results.

filters
object

Key value pairs of filters, where each value is an array to filter on. E.g. {"state": ["RUNNING"], "type": ["OPENVAS"]}

Allowed keys: type, state, scheduled_by

Responses

Response Schema: application/json
required
Array of objects (Scan)
next_page_token
string

Token that is present when there are more results than can fit in the response. Use the token to get the page of results.

Request samples

curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/scans

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "string",
      • "type": "DEPENDABOT",
      • "state": "FAILED",
      • "progress": 0,
      • "risks": {
        • "new_open": [
          • {
            • "risk_id": "string"
            }
          ],
        • "still_open": [
          • {
            • "risk_id": "string"
            }
          ],
        • "closed": [
          • {
            • "risk_id": "string"
            }
          ]
        },
      • "results": [
        • {
          • "result_id": "string",
          • "content_type": "text/html"
          }
        ],
      • "requested_targets": [
        • {
          • "target_id": "string",
          • "target": "string"
          }
        ],
      • "resolved_targets": [
        • {
          • "target_id": "string",
          • "resolved_target": "string"
          }
        ],
      • "skipped_targets": [
        • {
          • "target_id": "string",
          • "skipped_reason": "string"
          }
        ]
      }
    ],
  • "next_page_token": "string"
}

Get a Scan by id

Returns a single Scan

path Parameters
id
required
string

Id of the Scan to get

Responses

Response Schema: application/json
required
object (Scan)

The Scan object

Request samples

curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/scans/12345

Response samples

Content type
application/json
{
  • "data": {
    • "id": "string",
    • "type": "DEPENDABOT",
    • "state": "FAILED",
    • "progress": 0,
    • "risks": {
      • "new_open": [
        • {
          • "risk_id": "string"
          }
        ],
      • "still_open": [
        • {
          • "risk_id": "string"
          }
        ],
      • "closed": [
        • {
          • "risk_id": "string"
          }
        ]
      },
    • "results": [
      • {
        • "result_id": "string",
        • "content_type": "text/html"
        }
      ],
    • "requested_targets": [
      • {
        • "target_id": "string",
        • "target": "string"
        }
      ],
    • "resolved_targets": [
      • {
        • "target_id": "string",
        • "resolved_target": "string"
        }
      ],
    • "skipped_targets": [
      • {
        • "target_id": "string",
        • "skipped_reason": "string"
        }
      ]
    }
}

Get a Scan Result File by id

Get a Scan Result File

path Parameters
id
required
string

Id of the Result to get

Responses

Request samples

curl -o result.pdf -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET "https://api.hostedscan.com/v1/results/12345"

Authenticated Scanning

This section explains how to run an authenticated scan with the API. For general info on HostedScan's authenticated scanning features see https://hostedscan.com/authenticated-web-app-vulnerability-scan.

Steps to run an authenticated scan

  1. Create a target using the create Target API
  2. Upload the recorded Selenium script to the Target (see details below)
  3. Start a scan with the create scan API while sending use_authentication: true in the request

Uploading the recorded Selenium script

Make a POST request with content-type: multipart/form-data and one file to the endpoint https://api.hostedscan.com/v1/targets/:target_id/auth/selenium.

Example using curl

curl -H "X-HOSTEDSCAN-API-KEY: <<your api key>>" -F file=@YourSeleniumRecording.side https://api.hostedscan.com/v1/targets/your-target-id/auth/selenium

Risks

Risks are the findings from scans. For example, a vulnerable javascript dependency or an open port.

List Risks

Returns all Risks

query Parameters
page_token
string

If there are more than 500 objects to return, the results will be truncated. Use page_token to request additional pages of results.

filters
object

Key value pairs of filters, where each value is an array to filter on. E.g. {"risk_definition.scan_type": ["NMAP", "NMAP_UDP"]}

Allowed keys: target_id, status, tags, risk_definition.scan_type, risk_definition.threat_level, risk_definition.title

Responses

Response Schema: application/json
required
Array of objects (Risk)
next_page_token
string

Token that is present when there are more results than can fit in the response. Use the token to get the page of results.

Request samples

curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/risks

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "string",
      • "target_id": "string",
      • "target_label": "string",
      • "tags": [
        • "string"
        ],
      • "status": "OPEN",
      • "is_accepted": true,
      • "accepted_by": [
        • {
          • "note": "string",
          • "created_at": "2019-08-24T14:15:22Z",
          • "last_updated_at": "2019-08-24T14:15:22Z"
          }
        ],
      • "risk_definition": {
        • "scan_type": "DEPENDABOT",
        • "title": "string",
        • "threat_level": "LOW",
        • "description": "string",
        • "solution": "string",
        • "references": [
          • "string"
          ],
        • "cvss": "string",
        • "additional_info": { },
        • "first_detected_at": "2019-08-24T14:15:22Z",
        • "last_detected_at": "2019-08-24T14:15:22Z"
        }
      }
    ],
  • "next_page_token": "string"
}

Get a Risk by id

Returns a single Risk

path Parameters
id
required
string

Id of the Risk to get

Responses

Response Schema: application/json
required
object (Risk)

The Risk object

Request samples

curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/risks/12345

Response samples

Content type
application/json
{
  • "data": {
    • "id": "string",
    • "target_id": "string",
    • "target_label": "string",
    • "tags": [
      • "string"
      ],
    • "status": "OPEN",
    • "is_accepted": true,
    • "accepted_by": [
      • {
        • "note": "string",
        • "created_at": "2019-08-24T14:15:22Z",
        • "last_updated_at": "2019-08-24T14:15:22Z"
        }
      ],
    • "risk_definition": {
      • "scan_type": "DEPENDABOT",
      • "title": "string",
      • "threat_level": "LOW",
      • "description": "string",
      • "solution": "string",
      • "references": [
        • "string"
        ],
      • "cvss": "string",
      • "additional_info": { },
      • "first_detected_at": "2019-08-24T14:15:22Z",
      • "last_detected_at": "2019-08-24T14:15:22Z"
      }
    }
}

Targets

Targets are the servers and websites to be scanned for vulnerabilities. A target is defined by an IP address, URL, or Fully Qualified Domain Name.

Create a new Target

Create a new Target

query Parameters
upsert
boolean

Update target if it already exists. Defaults to false.

Request Body schema: application/json
target
required
string

IPv4, URL, or Fully Qualified Domain Name, eg. 123.456.789.1, google.com, or https://google.com/path

label
string

Label for the Target

tags
Array of strings

Up to 10 tags for filtering, selecting, and sorting

Responses

Response Schema: application/json
required
object (Target)

The created Target object

Request samples

Content type
application/json
{
  • "target": "string",
  • "label": "string",
  • "tags": [
    • "string"
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "string",
    • "target": "string",
    • "label": "string",
    • "tags": [
      • "string"
      ]
    }
}

List Targets

Returns all Targets

query Parameters
page_token
string

If there are more than 500 objects to return, the results will be truncated. Use page_token to request additional pages of results.

Responses

Response Schema: application/json
required
Array of objects (Target)
next_page_token
string

Token that is present when there are more results than can fit in the response. Use the token to get the page of results.

Request samples

curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/targets

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "string",
      • "target": "string",
      • "label": "string",
      • "tags": [
        • "string"
        ]
      }
    ],
  • "next_page_token": "string"
}

Get a Target by id

Returns a single Target

path Parameters
id
required
string

Id of the Target to get

Responses

Response Schema: application/json
required
object (Target)

The Target object

Request samples

curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/targets/12345

Response samples

Content type
application/json
{
  • "data": {
    • "id": "string",
    • "target": "string",
    • "label": "string",
    • "tags": [
      • "string"
      ]
    }
}

Update a Target

Update a Target

path Parameters
id
required
string

Id of the Target to update

Request Body schema: application/json
label
string

Label for the Target

tags
Array of strings

Up to 10 tags for filtering, selecting, and sorting

Responses

Response Schema: application/json
required
object (Target)

The updated Target object

Request samples

Content type
application/json
{
  • "label": "string",
  • "tags": [
    • "string"
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "string",
    • "target": "string",
    • "label": "string",
    • "tags": [
      • "string"
      ]
    }
}

Delete a Target

Delete a Target by id

Note: Deleting a target will also delete any risks associated with that target.

path Parameters
id
required
string

Id of the Target to delete

Responses

Request samples

curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request DELETE https://api.hostedscan.com/v1/targets/12345

Reports

Generate PDF and HTML reports.

Create a new Report

Create a new Report

Request Body schema: application/json
report_format
required
string
Enum: "PDF" "HTML"

PDF or HTML

targets_filter
object

Array of target ids or tags. { "target_ids": ["target-123"] } or { "tag": ["example-tag"] }

risks_filter
object

Key value pairs of filters, where each value is an array to filter on. E.g.

{"risk_definition.scan_type": ["NMAP", "NMAP_UDP"]}

Allowed keys: status, risk_definition.scan_type, risk_definition.threat_level, risk_definition.title

Request samples

Content type
application/json
{
  • "report_format": "PDF",
  • "targets_filter": { },
  • "risks_filter": { }
}

Download a Report

Download a Report

path Parameters
id
required
string

Id of the Report to get

Responses

Response Schema: application/octet-stream
string <binary>

Request samples

curl --header "X-HOSTEDSCAN-API-KEY: your-api-key-here" \
--request GET \
--output report.pdf \
https://api.hostedscan.com/v1/reports/id-of-created-report-here

Upload Results From Your Own Scanners

HostedScan supports uploading results from your own installations of Nmap, OpenVAS, and ZAP. To do so, first create a Source, which is a group of related targets and scans. Then, upload the result files from your scans to the new Source. For more detailed instructions and examples see https://hostedscan.com/internal-vulnerability-scanning.

Create a new Source

Create a new Source

Request Body schema: application/json
source_type
required
string
Value: "IMPORTED"
name
required
string

A name for the Source

Responses

Response Schema: application/json
required
object

Request samples

Content type
application/json
{
  • "source_type": "IMPORTED",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "string",
    • "source_type": "IMPORTED",
    • "name": "string"
    }
}

Upload a Scan Result

Upload a Scan Result

Request Body schema: multipart/form-data
source_id
required
string

Id of the Source that this result will be grouped with

scan_type
required
string (ScanType)
Enum: "DEPENDABOT" "NMAP" "NMAP_UDP" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SSLYZE"
target
string

The target that was scanned. e.g. https://example.com. Required only for the OWASP_ZAP and OWASP_ZAP_ACTIVE scan_types. For other scanners, such as NMAP and OPENVAS the targets will be automatically inferred.

Responses

Webhooks Overview

HostedScan uses webhooks to send event notifications to your application. Receive events when scans finish or when new risks are discovered.

Base Event Object

The webhook notifications sent by HostedScan are Event objects. An Event is a JSON structure with the following properties: the event id, the event_created_at time, the event type, and the data. The data is specific for each event. E.g. for a risk.created event the data is the Risk object and for a scan.created event the data is the Scan object.

{
  "id": "12345",
  "event_created_at": "2023-08-11T05:52:56.104Z",
  "type": "risk.created",
  "data": {
    ...
  }
}

Registering an Endpoint

Your webhook endpoint must use HTTPS with a signed certificate, such as one from https://letsencrypt.org/. HostedScan will not send to endpoints using self-signed certificates.

You can register new webhook endpoints and view your existing webhook endpoints in your account settings at https://hostedscan.com/settings.

Registering a Webhook Endpoint with HostedScan

Message Delivery and Retries

Any 2xx response code from your endpoint is treated as a successful delivery. Any non-2xx status code (or a timeout) is treated as a failure and will be retried. HostedScan will attempt to deliver messages to your endpoint for up to 12 hours, with exponential backoff.

Securing Your Webhooks

When you register an endpoint, HostedScan creates a signing secret for that endpoint. HostedScan uses this secret to send a signature in the header of each Event message. The signature can be validated using the signing secret to verify that an event was sent by HostedScan.

Validating the Webhook Signature

Each webhook message request includes an http header X-HOSTEDSCAN-SIGNATURE. The X-HOSTEDSCAN-SIGNATURE is a hash-based message authentication code (HMAC) generated with SHA-256. To validate this signature an application will first recreate the signature using the signing secret for that endpoint and then check that the signature sent in the X-HOSTEDSCAN-SIGNATURE header matches the recreated signature. To do this, follow the steps below:

  1. Prepare the data to be signed. The data is: the message timestamp (sent in the X-HOSTEDSCAN-TIMESTAMP header), the character . , and the JSON payload sent in the request body.
  2. Compute the expected signature. HMAC with SHA256.
  3. Compare the signature your application computed to ensure it matches the value sent in the X-HOSTEDSCAN-SIGNATURE header.

Sample Code

The hostedscan-api-examples Github repository has sample code for receiving webhooks with an AWS Lambda function.

Scan Events

Scan Created Webhook

A new Scan has been created

Request Body schema: application/json
id
required
string
event_created_at
string <date-time>
type
required
string
Value: "scan.created"
required
object

Request samples

Content type
application/json
{
  • "id": "string",
  • "event_created_at": "2019-08-24T14:15:22Z",
  • "type": "scan.created",
  • "data": {
    • "id": "string",
    • "type": "DEPENDABOT",
    • "state": "FAILED",
    • "progress": 0,
    • "risks": {
      • "new_open": [
        • {
          • "risk_id": "string"
          }
        ],
      • "still_open": [
        • {
          • "risk_id": "string"
          }
        ],
      • "closed": [
        • {
          • "risk_id": "string"
          }
        ]
      },
    • "results": [
      • {
        • "result_id": "string",
        • "content_type": "text/html"
        }
      ],
    • "requested_targets": [
      • {
        • "target_id": "string",
        • "target": "string"
        }
      ],
    • "resolved_targets": [
      • {
        • "target_id": "string",
        • "resolved_target": "string"
        }
      ],
    • "skipped_targets": [
      • {
        • "target_id": "string",
        • "skipped_reason": "string"
        }
      ]
    }
}

Scan Updated Webhook

A Scan has been updated

Request Body schema: application/json
id
required
string
event_created_at
string <date-time>
type
required
string
Value: "scan.updated"
required
object

Request samples

Content type
application/json
{
  • "id": "string",
  • "event_created_at": "2019-08-24T14:15:22Z",
  • "type": "scan.updated",
  • "data": {
    • "id": "string",
    • "type": "DEPENDABOT",
    • "state": "FAILED",
    • "progress": 0,
    • "risks": {
      • "new_open": [
        • {
          • "risk_id": "string"
          }
        ],
      • "still_open": [
        • {
          • "risk_id": "string"
          }
        ],
      • "closed": [
        • {
          • "risk_id": "string"
          }
        ]
      },
    • "results": [
      • {
        • "result_id": "string",
        • "content_type": "text/html"
        }
      ],
    • "requested_targets": [
      • {
        • "target_id": "string",
        • "target": "string"
        }
      ],
    • "resolved_targets": [
      • {
        • "target_id": "string",
        • "resolved_target": "string"
        }
      ],
    • "skipped_targets": [
      • {
        • "target_id": "string",
        • "skipped_reason": "string"
        }
      ]
    }
}

Risk Events

Risk Created Webhook

A new Risk has been created

Request Body schema: application/json
id
required
string
event_created_at
string <date-time>
type
required
string
Value: "risk.created"
required
object

Request samples

Content type
application/json
{
  • "id": "string",
  • "event_created_at": "2019-08-24T14:15:22Z",
  • "type": "risk.created",
  • "data": {
    • "id": "string",
    • "target_id": "string",
    • "target_label": "string",
    • "tags": [
      • "string"
      ],
    • "status": "OPEN",
    • "is_accepted": true,
    • "accepted_by": [
      • {
        • "note": "string",
        • "created_at": "2019-08-24T14:15:22Z",
        • "last_updated_at": "2019-08-24T14:15:22Z"
        }
      ],
    • "risk_definition": {
      • "scan_type": "DEPENDABOT",
      • "title": "string",
      • "threat_level": "LOW",
      • "description": "string",
      • "solution": "string",
      • "references": [
        • "string"
        ],
      • "cvss": "string",
      • "additional_info": { },
      • "first_detected_at": "2019-08-24T14:15:22Z",
      • "last_detected_at": "2019-08-24T14:15:22Z"
      }
    }
}

Risk Updated Webhook

A Risk has been updated

Request Body schema: application/json
id
required
string
event_created_at
string <date-time>
type
required
string
Value: "risk.updated"
required
object

Request samples

Content type
application/json
{
  • "id": "string",
  • "event_created_at": "2019-08-24T14:15:22Z",
  • "type": "risk.updated",
  • "data": {
    • "id": "string",
    • "target_id": "string",
    • "target_label": "string",
    • "tags": [
      • "string"
      ],
    • "status": "OPEN",
    • "is_accepted": true,
    • "accepted_by": [
      • {
        • "note": "string",
        • "created_at": "2019-08-24T14:15:22Z",
        • "last_updated_at": "2019-08-24T14:15:22Z"
        }
      ],
    • "risk_definition": {
      • "scan_type": "DEPENDABOT",
      • "title": "string",
      • "threat_level": "LOW",
      • "description": "string",
      • "solution": "string",
      • "references": [
        • "string"
        ],
      • "cvss": "string",
      • "additional_info": { },
      • "first_detected_at": "2019-08-24T14:15:22Z",
      • "last_detected_at": "2019-08-24T14:15:22Z"
      }
    }
}

Sample Code

Sample code can be found on Github at https://github.com/hostedscan/hostedscan-api-examples