WAS: Pagination Update
The Tenable.io Web Application Scanning v2 API page request and response format has been updated to match the Tenable.io Vulnerability Management format. This change brings consistent pagination across the various Tenable.io APIs. The old page request and response format has been deprecated in favor of the new page request and response format.
Warning
The old page request and response format has been deprecated. Backwards compatibility and support for both formats will remain until June 11, 2021. Please update any existing integrations that your organization has before this date.
This update affects the following endpoints:
| API Endpoint | Name |
|---|---|
| GET /was/v2/configs | List configurations |
| GET /was/v2/scans | List scans |
| GET /was/v2/scans/{scan_id}/notes | Get scan notes |
| GET /was/v2/scans/{scan_id}/vulnerabilities | List vulnerabilities for scan |
| GET /was/v2/vulnerabilities | List vulnerabilities |
| GET /was/v2/templates | List Tenable-provided templates |
| GET /was/v2/user-templates | List user-defined templates |
| GET /was/v2/plugins | List plugins |
New page request and response format
Request
You can specify pagination preferences for responses using the following query parameters:
| Parameter | Type | Description |
|---|---|---|
| limit | int32 | The number of records to retrieve. If this parameter is omitted, Tenable.io uses the default value of 10. The minimum value is 0 and the maximum value is 200. If you need to retrieve more than 200 records, use the offset value to iterate through page responses. |
| offset | int32 | The starting record to retrieve. If this parameter is omitted, Tenable.io uses the default value of 0. |
| sort | string | The field you want to use to sort the results by along with the sort order. The field is specified first, followed by a colon, and the order is specified second (asc or desc). For example, name:desc would sort results by the name field in descending order.If you specify multiple fields, the fields must be separated by commas. For example, name:desc,created_at:asc would first sort results by the name field in descending order and then by the created_at field in ascending order. |
Response
The new response format returns the result set within an items object and the pagination information within a pagination object.
{
"pagination": { },
"items": [...]
}
Example
For example, to request a list of scan configurations from the GET /was/v2/configs endpoint (using the new request format), limit the result set to two records, and sort the result set by the creation date (ascending) and name (descending), you would use the following request format:
https://cloud.tenable.com/was/v2/configs?limit=2&sort=created_at:asc,name:desc
The response format from this request would be:
{
"pagination": {
"total": 1690,
"offset": 0,
"limit": 2,
"sort": [
{
"name": "created_at",
"order": "asc"
},
{
"name": "name",
"order": "desc"
}
]
},
"items": [
{
"config_id": "24da4d67-bc7b-369d-bc73-826671a575cc",
"owner_id": "4dc95b60-8821-4280-be08-265ae01882a7",
"is_shared": false,
"user_permissions": "configure",
"name": "Example 1",
"target": "http://example.com/",
"description": "Example 1",
"created_at": "1970-01-19T10:02:34.808Z",
"updated_at": "2020-06-05T11:00:08Z",
"schedule": null,
"template_id": "b223f18e-5a94-4e02-b560-77a4a8246cd3",
"last_scan": {
"scan_id": "4f9e9182-b1f3-4b7c-a931-c3e502f5c155",
"user_id": "5ff4ad03-f168-4632-90fb-babf376579e9",
"config_id": "24da4d67-bc7b-369d-bc73-826671a575cc",
"asset_id": "6febe7b0-5dc0-43ec-afc1-aa8a7a6a7ae5",
"target": "http://example.com/",
"application_uri": "http://example.com/",
"created_at": "2020-10-07T22:35:20.533Z",
"updated_at": "2020-10-07T22:37:57.449Z",
"started_at": "2020-10-07T22:35:34.353Z",
"finalized_at": "2020-10-07T22:37:57.436Z",
"requested_action": "start",
"status": "completed",
"metadata": {
"found_urls": 11,
"queued_urls": 0,
"scan_status": "running",
"audited_urls": 1,
"queued_pages": 0,
"audited_pages": 1,
"request_count": 2634,
"response_time": 0
},
"scanner": {
"group_name": "US Cloud Scanner"
},
"template_name": "scan"
},
"user_template": null
},
{
"config_id": "a3775500-38f4-4cb1-b032-5386b445e554",
"owner_id": "4a0d43eb-77e2-4a52-b24a-93d29bcb0aba",
"is_shared": false,
"user_permissions": "configure",
"name": "Example 2",
"target": "http://192.0.2.119",
"description": null,
"created_at": "2020-02-05T23:16:11.883Z",
"updated_at": "2020-02-05T23:16:11.883Z",
"schedule": null,
"template_id": "112f3e7f-d83a-4bba-b2c8-df2d22e2fa4c",
"last_scan": {
"scan_id": "934848fa-2e28-4f1e-a438-dcbeef89b5b5",
"user_id": "4a0d43eb-77e2-4a52-b24a-93d29bcb0aba",
"config_id": "a3775500-38f4-4cb1-b032-5386b445e554",
"asset_id": "22807f4e-d678-4c60-bcb9-6af2a0623f9b",
"target": "http://192.0.2.119",
"application_uri": "http://192.0.2.119",
"created_at": "2020-02-19T16:52:17.264Z",
"updated_at": "2020-02-19T16:55:59.154Z",
"started_at": null,
"finalized_at": null,
"requested_action": "start",
"status": "aborted",
"metadata": {
"estimate_crawl_percent_complete": 100,
"queued_urls": 0,
"scan_status": "running",
"crawled_urls": 11,
"queued_pages": 0,
"audited_pages": 18,
"request_count": 678,
"response_time": 0
},
"scanner": null,
"template_name": "overview"
},
"user_template": null
}
]
}
Old page request and response format (deprecated)
For reference, information about the deprecated page request and response format is included below.
Request
Pagination preferences for responses using the old format (deprecated) were specified using the following query parameters:
| Parameter | Type | Description |
|---|---|---|
| order_by | string | The field used to order the query results. |
| ordering | string | The sort order applied when sorting by the order_by parameter. Values include asc and desc. If your request omits the ordering query parameter, this value defaults to asc. |
| page | int32 | The starting record to retrieve. Use in combination with the size parameter to paginate results. The default value is 0. |
| size | int32 | The page size of the query results. Use in combination with the page parameter to paginate results. The default value is 10. |
Response
The old response format returned the result set within the data object. The pagination preferences were also returned.
{
"page_number": 0,
"page_size": 2,
"order_by": "created_at",
"ordering": "asc",
"total_size": 1690,
"data": [...]
}
Example
For example, to request a list of scan configurations from the GET /was/v2/configs endpoint (using the deprecated request format), limit the result set to two records, and sort the result set by the creation date in ascending order you would use the following request:
https://cloud.tenable.com/was/v2/configs?size=2&order_by=created_at&ordering=asc
The response format from this request would be:
{
"page_number": 0,
"page_size": 2,
"order_by": "created_at",
"ordering": "asc",
"total_size": 1690,
"data": [
{
"config_id": "24da4d67-bc7b-369d-bc73-826671a575cc",
"owner_id": "4dc95b60-8821-4280-be08-265ae01882a7",
"is_shared": false,
"user_permissions": "configure",
"name": "Example 1",
"target": "http://example.com/",
"description": "Example 1",
"created_at": "1970-01-19T10:02:34.808Z",
"updated_at": "2020-06-05T11:00:08Z",
"schedule": null,
"template_id": "b223f18e-5a94-4e02-b560-77a4a8246cd3",
"last_scan": {
"scan_id": "4f9e9182-b1f3-4b7c-a931-c3e502f5c155",
"user_id": "5ff4ad03-f168-4632-90fb-babf376579e9",
"config_id": "24da4d67-bc7b-369d-bc73-826671a575cc",
"asset_id": "6febe7b0-5dc0-43ec-afc1-aa8a7a6a7ae5",
"target": "http://example.com/",
"application_uri": "http://example.com/",
"created_at": "2020-10-07T22:35:20.533Z",
"updated_at": "2020-10-07T22:37:57.449Z",
"started_at": "2020-10-07T22:35:34.353Z",
"finalized_at": "2020-10-07T22:37:57.436Z",
"requested_action": "start",
"status": "completed",
"metadata": {
"found_urls": 11,
"queued_urls": 0,
"scan_status": "running",
"audited_urls": 1,
"queued_pages": 0,
"audited_pages": 1,
"request_count": 2634,
"response_time": 0
},
"scanner": {
"group_name": "US Cloud Scanner"
},
"template_name": "scan"
},
"user_template": null
},
{
"config_id": "a3775500-38f4-4cb1-b032-5386b445e554",
"owner_id": "4a0d43eb-77e2-4a52-b24a-93d29bcb0aba",
"is_shared": false,
"user_permissions": "configure",
"name": "Example 2",
"target": "http://192.0.2.119",
"description": null,
"created_at": "2020-02-05T23:16:11.883Z",
"updated_at": "2020-02-05T23:16:11.883Z",
"schedule": null,
"template_id": "112f3e7f-d83a-4bba-b2c8-df2d22e2fa4c",
"last_scan": {
"scan_id": "934848fa-2e28-4f1e-a438-dcbeef89b5b5",
"user_id": "4a0d43eb-77e2-4a52-b24a-93d29bcb0aba",
"config_id": "a3775500-38f4-4cb1-b032-5386b445e554",
"asset_id": "22807f4e-d678-4c60-bcb9-6af2a0623f9b",
"target": "http://192.0.2.119",
"application_uri": "http://192.0.2.119",
"created_at": "2020-02-19T16:52:17.264Z",
"updated_at": "2020-02-19T16:55:59.154Z",
"started_at": null,
"finalized_at": null,
"requested_action": "start",
"status": "aborted",
"metadata": {
"estimate_crawl_percent_complete": 100,
"queued_urls": 0,
"scan_status": "running",
"crawled_urls": 11,
"queued_pages": 0,
"audited_pages": 18,
"request_count": 678,
"response_time": 0
},
"scanner": null,
"template_name": "overview"
},
"user_template": null
}
]
}