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.

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

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

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

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.

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.

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

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.

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

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 are the findings from scans. For example, a vulnerable javascript dependency or an open port.

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.

Generate PDF and HTML reports.

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.

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

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": {
    ...
  }
}

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.

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.

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.

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.

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

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