Tenable Scans API
The Scans API from Tenable — 11 operation(s) for scans.
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Scans API
description: 'The Downloads API enables customers to access and download installation and update files for available Tenable products. You can use the API endpoints to list product pages, list downloads available for a specific product, and to download a file. The endpoints can also be used to determine and download the latest version of a file to facilitate the automation of an installation.
**Note:** The Tenable Downloads API uses a different server URL than the Tenable Vulnerability Management API:
`https://www.tenable.com/downloads/api/v2/pages`.
### Authentication
Like the Downloads website, certain files require authentication to download. When files have a `"requires_auth": true` attribute on the product list page, the Downloads API uses bearer token authentication and requires a valid token in the Authorization header to download the file:
```
Authorization: Bearer AbCdEf123456
```
To access or reset your authentication token, navigate to the [Authentication Token](https://www.tenable.com/downloads/api-docs) page.
Examples of product downloads that **do not** require authentication include Nessus and Nessus Agents.'
servers:
- url: https://www.tenable.com/downloads/api/v2
security:
- Bearer: []
tags:
- name: Scans
paths:
/pci-asv/scans/list:
get:
tags:
- Scans
summary: List PCI scans
description: 'Returns a list of PCI scans in PCI ASV.
**Note:** You need to request access to this endpoint through Tenable support even if you have a valid PCI ASV license.. <div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>'
operationId: pci-scans-list
parameters:
- description: '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,started_at:asc` would first sort results by the `name` field in descending order and then by the `started_at` field in ascending order.'
name: sort
in: query
schema:
type: string
- description: The number of records to retrieve.
name: limit
in: query
schema:
type: integer
format: int32
- description: The starting record to retrieve. If this parameter is omitted, Tenable PCI ASV uses the default value of `0`.
name: offset
in: query
schema:
type: integer
format: int32
responses:
'200':
description: Returned if the list of PCI scans was retrieved successfully.
content:
application/json:
schema:
type: object
required:
- pagination
- items
properties:
pagination:
$ref: '#/components/schemas/Response-Pagination'
scans:
type: array
description: An array of PCI ASV scan objects.
items:
$ref: '#/components/schemas/Response-ScansList'
examples:
response:
value:
pagination:
total: 2
offset: 0
limit: 200
sort:
- name: name
order: asc
scans:
- asset_count: 4
updated_at: '2023-01-13T08:30:03.219Z'
name: PCI Scan Example 1
cde.uuid: 2a26c398-d61f-4f0f-8aea-bce410a64818
started_at: '2023-01-13T05:30:12Z'
scan_type: nessus
failure_count: 68
import_status: complete
vulnerability_count: 229
uuid: 1ud20a81-5dbf-4749-9173-62ba398c0646
ended_at: '2023-01-13T05:50:03Z'
status: 100
- asset_count: 4
updated_at: '2023-01-13T08:30:03.219Z'
name: PCI Scan Example 2
cde.uuid: 1a26c398-d61f-4f0f-8aea-bce410a64818
started_at: '2023-01-13T05:30:12Z'
scan_type: nessus
failure_count: 68
import_status: complete
vulnerability_count: 229
uuid: bu7e71d6-25db-44a1-8869-f7b234480c11
ended_at: '2023-01-13T05:50:03Z'
status: 100
'400':
description: Returned if you do not have a license to use Tenable PCI ASV.
content:
application/json:
examples:
response:
value:
errors:
- rule: user.does_not_have_access_for_api
message: Please contact Tenable support to enable API access for this endpoint in your container.
error: Please contact Tenable support to enable API access for this endpoint in your container.
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have the required permissions to view the list of PCI scans. For example, if you're an analyst user instead of an administrator.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
/scans:
post:
summary: Create scan
description: "Creates a scan configuration. For more information and request body examples, see [Create a Scan](doc:create-scan-tio). \n\n**Note:** Tenable Vulnerability Management limits the active number of scans to 10,000 scans. Tenable recommends you re-use scheduled scans instead of creating new scans. Alternatively, you can delete unused scans. An HTTP 403 error is returned if you attempt to create a scan after you have already reached the scan limit of 10,000. <div class=\"perms-callout\">Requires the Scan Operator [24] user role or the `VM.VM_SCAN.VM_SCAN.CREATE` custom role privilege. See [Roles](doc:roles).</div>"
operationId: scans-create
tags:
- Scans
requestBody:
required: true
content:
application/json:
schema:
required:
- uuid
- settings
type: object
properties:
uuid:
type: string
description: 'The UUID for the Tenable-provided scan template to use. Use the [List templates](ref:editor-list-templates) endpoint to find the template UUID.
**Caution:** The defaults listed for a template via the [Get template details](ref:editor-template-details) endpoint apply to the user interface only. When you create a scan via the API you must include the settings in the request even if the setting is listed as a default in the editor. For example, even if `host_tagging` is set to `yes` by default in the editor, you still need to include `"host_tagging": "yes"` in the `settings` object for the scan.'
example: 9afd5e49-b4a8-4ab3-8c44-4ed329a505c44e51e1f403febe40
settings:
$ref: '#/components/schemas/scans_Request-ScanSettings'
credentials:
$ref: '#/components/schemas/scans_request-create-scan-credentials-object'
plugins:
$ref: '#/components/schemas/scans_request-create-and-update-plugins-object'
audits:
$ref: '#/components/schemas/scans_Request-ScanAudits'
responses:
'200':
description: Returned the scan configuration was created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/scans_scan-object-create-update-response'
examples:
response:
value:
scan:
container_id: 3584b24b-7f26-4684-b644-a2a92103d6c2
owner_uuid: 595e5aa0-e631-4e99-80e2-e1be8cc7bdc1
uuid: template-8b64a4a8-50b4-4077-bcc4-31f451fa3549f4f660ba792e0b0f
name: Full Network Scan
description: Scan all hosts daily
policy_id: 16
scanner_id: null
scanner_uuid: 00000000-0000-0000-0000-00000000000000000000000000001
emails: person_1@example.com,person_2@example.com
sms: +15555555555,+14444444444
enabled: true
dashboard_file: null
include_aggregate: true
scan_time_window: null
custom_targets: null
starttime: null
rrules: null
timezone: US/Central
notification_filter_type: and
notification_filters:
- value: CVE-2023-2234
quality: eq
filter: cve
tag_targets:
- 1cf4f3a3-9878-44ce-9fa7-3a969c602e28
- 9808942a-2053-43a7-8580-7caebdfb959f
shared: 0
user_permissions: 128
default_permissions: 0
owner: user2@example.com
owner_id: 2
last_modification_date: 1544145190
creation_date: 1544145190
type: public
id: 26
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/scans_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you attempt to create a scan after you have already reached the scan limit of 10,000. Tenable recommends you re-use scheduled scans instead of creating new scans.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/scans_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- scans_cloud: []
get:
summary: List scans
description: "Returns a list of scans where you have at least CAN VIEW [16] scan permissions. \n\n**Note:** Keep in mind potential [rate limits](doc:rate-limiting) when using this endpoint. To check the status of your scans, use the [Get latest scan status](ref:scans-get-latest-status) endpoint. Tenable recommends the [Get latest scan status](ref:scans-get-latest-status) endpoint especially if you are programmatically checking the status of large numbers of scans.<div class=\"perms-callout\">Requires the Basic [16] user role and the Can View [16] scan permission. Alternatively, requires the `VM.VM_SCAN.VM_SCAN.READ` custom role privilege . See [Roles](doc:roles) and [Permissions](doc:permissions).</div>"
operationId: scans-list
tags:
- Scans
parameters:
- description: The unique identifier of the folder to filter by. When provided, only scans within this folder are returned.
required: false
name: folder_id
in: query
schema:
type: integer
- description: "Filters results to scans that are either currently active or were executed on or after the specified Unix timestamp (in seconds). \n\n**Note:** Despite the parameter name, this refers to the scan execution time, not the date the scan configuration was last modified."
required: false
name: last_modification_date
in: query
schema:
type: integer
format: int64
example: 1770881803
- description: Filters results to scans started on or after the specified Unix timestamp (in seconds).
required: false
name: started_from
in: query
schema:
type: integer
format: int64
example: 1770881803
- description: Filters results to scans started on or before the specified Unix timestamp (in seconds).
required: false
name: started_to
in: query
schema:
type: integer
format: int64
example: 1770881803
responses:
'200':
description: Returned if the list of scans was retrieved successfully.
content:
application/json:
schema:
type: object
properties:
scans:
type: array
items:
$ref: '#/components/schemas/scans_scan-object-list'
folders:
type: array
items: {}
timestamp:
type: integer
description: The Unix timestamp when Tenable Vulnerability Management received the list request.
format: int64
examples:
response:
value:
scans:
- control: true
creation_date: 1667846780
enabled: false
id: 32
last_modification_date: 1667955712
legacy: false
name: Example Scan 1
owner: example@example.com
policy_id: 30
read: false
schedule_uuid: 26cf08d3-3f94-79f4-8038-996376eabd4f186741fe15533e70
shared: true
status: completed
template_uuid: 131a8e52-3ea6-a291-ec0a-d2ff0619c19d7bd788d6be818b65
has_triggers: false
type: remote
permissions: 16
user_permissions: 128
uuid: c1d84965-c4c6-47ea-99c6-2111b803bcae
wizard_uuid: 931a8e52-3ea6-a291-ec0a-d2ff0619c19d7bd788d6be818b65
progress: 100
total_targets: 3072
- control: true
creation_date: 1667846760
enabled: false
id: 29
last_modification_date: 1667951900
legacy: false
name: Example Scan 2
owner: example@example.com
policy_id: 27
read: false
schedule_uuid: 461e4ebc-b309-face-6fa1-afa4ba163cb6d84b9dc0a0dc5020
shared: true
status: completed
template_uuid: 231a8e52-3ea6-a291-ec0a-d2ff0619c19d7bd788d6be818b65
has_triggers: false
type: remote
permissions: 16
user_permissions: 128
uuid: a2ae343e-308b-4540-90b9-ceae09641d84
wizard_uuid: 831a8e52-3ea6-a291-ec0a-d2ff0619c19d7bd788d6be818b65
progress: 100
total_targets: 3072
- control: true
creation_date: 1656499184
enabled: false
id: 14
last_modification_date: 1656499323
legacy: false
name: Example Scan 3
owner: system
read: true
schedule_uuid: bca83022-b67a-5f73-c0ca-db4542057d40fa937bee56c5655b
shared: false
status: completed
has_triggers: false
type: pvs
permissions: 0
user_permissions: 128
uuid: d83acc14-2f92-44d3-a843-80c2c4f35ebf
progress: 100
total_targets: 1
folders:
- id: 43
name: My Scans
type: main
custom: 0
unread_count: 3
default_tag: 1
- id: 44
name: Trash
type: trash
custom: 0
unread_count: 2
default_tag: 0
timestamp: 1671477512
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/scans_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/scans_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- scans_cloud: []
/scans/{scan_id}:
get:
summary: Get scan details
description: "Returns scan results for a specific scan. If you submit a request without query parameters, Tenable Vulnerability Management returns results from the latest run of the specified scan. If you submit a request using the query parameters to specify a historical run of the scan, Tenable Vulnerability Management returns the scan results for the specified run. \n\n**Note:** Keep in mind potential [rate limits](doc:rate-limiting) and [concurrency limits](doc:concurrency-limiting) when using this endpoint. To check the status of a scan, use the [Get latest scan status](ref:scans-get-latest-status) endpoint. Tenable recommends the [Get latest scan status](ref:scans-get-latest-status) endpoint especially if you are programmatically checking the status of large numbers of scans. \n\n**Note:** This endpoint returns limited data if scan results are older than 35 days. Scans that are older than 35 days are effectively \"archived\". The `info.is_archived` attribute in the response message for this endpoint serves as the indication of archival status. For complete data from archived scan results, use the [Export scan](ref:scans-export-request) endpoint instead. <div class=\"perms-callout\">Requires the Scan Operator [24] user role and the Can View [16] scan permission. Alternatively, requires the `VM.VM_SCAN.VM_SCAN.READ` custom role privilege . See [Roles](doc:roles) and [Permissions](doc:permissions).</div>"
operationId: scans-details
tags:
- Scans
parameters:
- description: 'The unique identifier for the scan. You can use either the `schedule_uuid` (string) or the `id` (integer) retrieved from the [List Scans](ref:scans-list) endpoint.
**Note:** Tenable recommends using the `schedule_uuid` for consistency across scan instances.'
required: true
name: scan_id
in: path
schema:
oneOf:
- title: String Value for UUID
type: string
- title: Integer Value for ID
type: integer
- description: The unique identifier of the specific scan historical instance you want to retrieve. This value enables you to access data from a previous execution of the scan and corresponds to the `id` attribute from the [Get scan history](ref:scans-history) endpoint.
name: history_id
in: query
schema:
type: integer
responses:
'200':
description: Returned if the details for the specified scan were retrieved successfully.
content:
application/json:
schema:
type: object
properties:
info:
$ref: '#/components/schemas/scans_scan-info-response-object'
comphosts:
type: array
description: A list of the hosts that had compliance checks run against them. If the scan results are older than 35 days (that is, if the `info.archived` attribute for the scan is `true`), this array does not appear in the response message.
items:
$ref: '#/components/schemas/scans_host'
hosts:
type: array
description: A list of the hosts targeted by the scan for the specified run. This lists includes both hosts assessed for vulnerabilities and compliance checks. If the scan results are older than 35 days (that is, if the `info.archived` attribute for the scan is `true`), this array does not appear in the response message.
items:
$ref: '#/components/schemas/scans_host'
notes:
type: array
items:
$ref: '#/components/schemas/scans_note'
remediations:
type: object
vulnerabilities:
type: array
description: A list of vulnerabilities that the scan identified on the target hosts. If the scan results are older than 35 days (that is, if the `info.archived` attribute for the scan is `true`), this array does not appear in the response message.
items:
$ref: '#/components/schemas/scans_vulnerability'
filters:
type: array
description: A list of filters. If the scan results are older than 35 days (that is, if the `info.archived` attribute for the scan is `true`), this array does not appear in the response message.
items:
$ref: '#/components/schemas/scans_filter'
history:
type: array
description: A list of details about each time the scan has run.
items:
$ref: '#/components/schemas/scans_history-in-scan-details-response'
compliance:
type: array
description: A list of compliance checks performed during the run of the scan. If the scan results are older than 35 days (that is, if the `info.archived` attribute for the scan is `true`), this array does not appear in the response message.
items:
$ref: '#/components/schemas/scans_vulnerability'
progress:
type: integer
description: The progress of the scan ranging from 0 to 100.
examples:
response:
value:
info:
owner: user2@example.com
name: KitchenSinkScan
no_target: false
folder_id: 9
control: false
user_permissions: 128
schedule_uuid: b0eeabbe-a612-429a-a60e-0f68eafb8c36f60557ee0e264228
edit_allowed: false
scanner_name: null
policy: null
shared: false
object_id: 11
tag_targets:
- 1cf4f3a3-9878-44ce-9fa7-3a969c602e28
- 9808942a-2053-43a7-8580-7caebdfb959f
acls:
- permissions: 0
owner: null
display_name: null
name: null
id: null
type: default
- permissions: 128
owner: 1
display_name: user2@example.com
name: user2@example.com
id: 2
type: user
hostcount: 10
uuid: fd7d0d8e-c0e1-4439-97a5-d5c3a5c2d369ab8f7ecb158c480e
status: imported
scan_type: null
targets: null
alt_targets_used: null
pci-can-upload: null
scan_start: 1430933086
timestamp: 1430934526
is_archived: false
scan_end: 1430934526
haskb: true
hasaudittrail: true
scanner_start: null
scanner_end: null
history:
- history_id: 10328682
owner_id: 2
creation_date: 1430933086
last_modification_date: 1430934526
uuid: fd7d0d8e-c0e1-4439-97a5-d5c3a5c2d369ab8f7ecb158c480e
type: null
status: imported
scheduler: 0
alt_targets_used: false
is_archived: false
hosts:
- asset_id: 5
host_id: 5
hostname: 192.0.2.57
progress: 100-100/200-200
scanprogresscurrent: 100
scanprogresstotal: 100
numchecksconsidered: 100
totalchecksconsidered: 100
severitycount:
item:
- count: 156
severitylevel: 0
- count: 1
severitylevel: 1
- count: 6
severitylevel: 2
- count: 3
severitylevel: 3
- count: 0
severitylevel: 4
severity: 166
score: 3766
info: 156
low: 1
medium: 6
high: 3
critical: 0
host_index: 0
- asset_id: 3
host_id: 3
hostname: 192.0.2.57
progress: 100-100/200-200
scanprogresscurrent: 100
scanprogresstotal: 100
numchecksconsidered: 100
totalchecksconsidered: 100
severitycount:
item:
- count: 52
severitylevel: 0
- count: 11
severitylevel: 1
- count: 100
severitylevel: 2
- count: 58
severitylevel: 3
- count: 32
severitylevel: 4
severity: 253
score: 388162
info: 52
low: 11
medium: 100
high: 58
critical: 32
host_index: 1
- asset_id: 9
host_id: 9
hostname: 192.0.2.57
progress: 100-100/200-200
scanprogresscurrent: 100
scanprogresstotal: 100
numchecksconsidered: 100
totalchecksconsidered: 100
severitycount:
item:
- count: 115
severitylevel: 0
- count: 5
severitylevel: 1
- count: 21
severitylevel: 2
- count: 45
severitylevel: 3
- count: 16
severitylevel: 4
severity: 202
score: 207265
info: 115
low: 5
medium: 21
high: 45
critical: 16
host_index: 2
vulnerabilities:
- count: 68
plugin_id: 34220
plugin_name: Netstat Portscanner (WMI)
severity: 0
plugin_family: Port scanners
vuln_index: 1
- count: 65
plugin_id: 34252
plugin_name: Microsoft Windows Remote Listeners Enumeration (WMI)
severity: 0
plugin_family: Windows
# --- truncated at 32 KB (291 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-scans-api-openapi.yml