Download OpenAPI specification:Download
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.
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.
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. |
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 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.
type | string (RunnableScanType) Enum: "NMAP" "NMAP_UDP" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SSLYZE" |
targets | Array of strings Targets to scan. e.g. |
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. |
use_authentication | boolean Use authentication, if configured for the target(s). See https://hostedscan.com/authenticated-web-app-vulnerability-scan for more details. |
required | object (Scan) The created Scan object |
{- "type": "NMAP",
- "targets": [
- "string"
], - "target_ids": [
- "string"
], - "tags": [
- "string"
], - "use_authentication": true
}
{- "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"
}
]
}
}
Returns all Scans
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. |
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. |
curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/scans
{- "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"
}
Returns a single Scan
id required | string Id of the Scan to get |
required | object (Scan) The Scan object |
curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/scans/12345
{- "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"
}
]
}
}
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.
use_authentication: true
in the requestMake 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
.
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.
Returns all Risks
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. |
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. |
curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/risks
{- "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"
}
Returns a single Risk
id required | string Id of the Risk to get |
required | object (Risk) The Risk object |
curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/risks/12345
{- "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 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
upsert | boolean Update target if it already exists. Defaults to false. |
target required | string IPv4, URL, or Fully Qualified Domain Name, eg. |
label | string Label for the Target |
tags | Array of strings Up to 10 tags for filtering, selecting, and sorting |
required | object (Target) The created Target object |
{- "target": "string",
- "label": "string",
- "tags": [
- "string"
]
}
{- "data": {
- "id": "string",
- "target": "string",
- "label": "string",
- "tags": [
- "string"
]
}
}
Returns all Targets
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. |
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. |
curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/targets
{- "data": [
- {
- "id": "string",
- "target": "string",
- "label": "string",
- "tags": [
- "string"
]
}
], - "next_page_token": "string"
}
Returns a single Target
id required | string Id of the Target to get |
required | object (Target) The Target object |
curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request GET https://api.hostedscan.com/v1/targets/12345
{- "data": {
- "id": "string",
- "target": "string",
- "label": "string",
- "tags": [
- "string"
]
}
}
Update a Target
id required | string Id of the Target to update |
label | string Label for the Target |
tags | Array of strings Up to 10 tags for filtering, selecting, and sorting |
required | object (Target) The updated Target object |
{- "label": "string",
- "tags": [
- "string"
]
}
{- "data": {
- "id": "string",
- "target": "string",
- "label": "string",
- "tags": [
- "string"
]
}
}
Delete a Target by id
Note: Deleting a target will also delete any risks associated with that target.
id required | string Id of the Target to delete |
curl -H "X-HOSTEDSCAN-API-KEY: test-data-key" --request DELETE https://api.hostedscan.com/v1/targets/12345
Create a new Report
report_format required | string Enum: "PDF" "HTML"
|
targets_filter | object Array of target ids or tags. |
risks_filter | object Key value pairs of filters, where each value is an array to filter on. E.g.
|
{- "report_format": "PDF",
- "targets_filter": { },
- "risks_filter": { }
}
Download a Report
id required | string Id of the Report to get |
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
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
source_type required | string Value: "IMPORTED" |
name required | string A name for the Source |
required | object |
{- "source_type": "IMPORTED",
- "name": "string"
}
{- "data": {
- "id": "string",
- "source_type": "IMPORTED",
- "name": "string"
}
}
Upload a Scan Result
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 |
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:
X-HOSTEDSCAN-TIMESTAMP
header), the character . , and the JSON payload sent in the request body.X-HOSTEDSCAN-SIGNATURE
header.The hostedscan-api-examples Github repository has sample code for receiving webhooks with an AWS Lambda function.
A new Scan has been created
id required | string |
event_created_at | string <date-time> |
type required | string Value: "scan.created" |
required | object |
{- "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"
}
]
}
}
A Scan has been updated
id required | string |
event_created_at | string <date-time> |
type required | string Value: "scan.updated" |
required | object |
{- "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"
}
]
}
}
A new Risk has been created
id required | string |
event_created_at | string <date-time> |
type required | string Value: "risk.created" |
required | object |
{- "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"
}
}
}
A Risk has been updated
id required | string |
event_created_at | string <date-time> |
type required | string Value: "risk.updated" |
required | object |
{- "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 can be found on Github at https://github.com/hostedscan/hostedscan-api-examples