Tenable Remediation Scans API
The Remediation Scans API from Tenable — 1 operation(s) for remediation scans.
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Remediation 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: Remediation Scans
x-displayName: Remediation Scans
paths:
/scans/remediation:
post:
summary: Create remediation scan
description: "Creates a remediation scan configuration. For more information and request body examples, see [Manage Remediation Scans](doc:io-manage-remediation-scans). \n\n**Note:** Tenable Vulnerability Management limits the number of scans you can create to 10,000 scans. Tenable recommends you re-use scheduled scans instead of creating new 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_REMEDIATION.VM_REMEDIATION.CREATE` custom role privilege. See [Roles](doc:roles).</div>"
operationId: io-scans-remediation-create
tags:
- Remediation Scans
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
uuid:
type: string
description: Specifies the UUID for the Tenable-provided remediation scan template to use. Use the [List templates](ref:editor-list-templates) endpoint with a type of `remediation` to find remediation scan template UUIDs.
example: 9afd5e49-b4a8-4ab3-8c44-4ed329a505c44e51e1f403febe40
settings:
description: 'Specifies the scan settings for the remediation scan. Remediation scans support the same settings as standard scans, with the following exceptions:
* Schedule settings (`enabled`, `starttime`, `rrules`, `timezone`, `launch_now`) are not applicable. Remediation scans are launched on demand only.
* The `folder_id` setting is not applicable. Remediation scans are stored in a dedicated remediation folder.
For a complete description of available settings, see the `settings` object in the [Create scan](ref:scans-create) endpoint.'
allOf:
- $ref: '#/components/schemas/Remediation_Scans_Request-ScanSettings'
credentials:
$ref: '#/components/schemas/Remediation_Scans_request-create-scan-credentials-object'
plugins:
$ref: '#/components/schemas/Remediation_Scans_request-create-and-update-plugins-object'
enabled_plugins:
$ref: '#/components/schemas/Remediation_Scans_enabled_plugins'
required:
- uuid
- settings
responses:
'200':
description: Returned if the remediation scan configuration was created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Remediation_Scans_scan-object-create-update-response'
examples:
response:
value:
scan:
tag_type: null
container_id: 7a818eb1-8351-4795-99b0-9610c8954cb4
owner_uuid: 68f1b7a3-caf0-4ef6-87a5-2d31338ead34
uuid: template-54910541-1016-191c-f92d-fe58f5455d40bbac8a568ec40c26
name: remediationMultiple
description: string
policy_id: 602
scanner_id: null
scanner_uuid: 00000000-0000-0000-0000-00000000000000000000000000001
emails: null
sms: ''
enabled: false
include_aggregate: true
scan_time_window: 0
custom_targets: 192.0.2.1/24
target_network_uuid: null
auto_routed: 0
remediation: 1
starttime: null
rrules: null
timezone: null
notification_filters: null
shared: 0
user_permissions: 128
default_permissions: 0
owner: user@example.com
owner_id: 28
last_modification_date: 1613751173
creation_date: 1613751173
type: public
id: 618
'400':
description: "Returned under the following conditions:\n - If your request message is missing a required parameter.\n - If your request was for a remediation scan and it included a user-defined template. User-defined templates are invalid for remediation scans."
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Remediation_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/Remediation_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:
- Remediation_Scans_cloud: []
get:
summary: List remediation scans
description: "Returns a list of remediation 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_REMEDIATION.VM_REMEDIATION.READ` custom role privilege. See [Roles](doc:roles) and [Permissions](doc:permissions).</div>"
operationId: io-scans-remediation-list
tags:
- Remediation Scans
parameters:
- description: Specifies the number of records to retrieve. Minimum value is `1`. Maximum value is `200`. If omitted, the system uses the default value of `50`.
required: false
name: limit
in: query
schema:
type: integer
- description: Specifies the starting record to retrieve. Minimum value is `0`. If omitted, the system uses the default value of `0`.
required: false
name: offset
in: query
schema:
type: integer
- description: 'Specifies the field and order to sort results by. Valid format: `scan_creation_date:desc` or `scan_creation_date:asc`. If omitted, the system uses the default value of `scan_creation_date:desc`.'
required: false
name: sort
in: query
schema:
type: string
enum:
- scan_creation_date:desc
- scan_creation_date:asc
responses:
'200':
description: Returned if the remediation scan list is retrieved successfully.
content:
application/json:
schema:
type: object
properties:
pagination:
$ref: '#/components/schemas/Remediation_Scans_PaginationResponse'
scans:
type: array
items:
$ref: '#/components/schemas/Remediation_Scans_remediation-scan-object-list'
examples:
response:
value:
pagination:
offset: 0
total: 10
sort: scan_creation_date:desc
limit: 1
scans:
- type: ps
uuid: 19270891-9d39-4087-ab1c-887fdf4f31d6
permissions: 128
enabled: false
control: true
read: false
last_modification_date: 1591039287
creation_date: 1591038929
status: completed
shared: false
user_permissions: 128
schedule_uuid: template-0aaf949f-dd1c-a1b6-8de9-7cb934568618f7d3e3bb22b45950
wizard_uuid: 731a8e52-3ea6-a291-ec0a-d2ff0619c19d7bd788d6be818b65
scan_creation_date: 1591032316
owner: user1@example.com
policy_id: 1751
id: 1752
name: Remediation Scan
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Remediation_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/Remediation_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:
- Remediation_Scans_cloud: []
components:
schemas:
Remediation_Scans_PaginationResponse:
description: An object containing pagination information for the current result set.
type: object
properties:
total:
type: integer
format: int32
description: The total number of records matching your search criteria.
limit:
type: integer
format: int32
description: The number of records requested (or the default value if omitted from the request).
offset:
type: integer
format: int32
description: The starting record you requested (or zero if omitted).
sort:
description: An array of objects specifying how the current result set is sorted.
type: array
items:
$ref: '#/components/schemas/Remediation_Scans_PaginationResponseSortObject'
Remediation_Scans_request-create-scan-credentials-object:
type: object
description: An object that specifies credential parameters that enable a scanner to authenticate a connection to a target host. For more information about using managed credentials with the Tenable Vulnerability Management API, see [Manage Credentials](doc:manage-credentials).
properties:
add:
type: object
description: 'A credentials object you want to add to the scan. For scan-specific credentials, the parameters of the object vary based on credentials category, credentials type, and type-specific settings. For more information, see [Determine Settings for a Credential Type](doc:determine-settings-for-credential-type). For managed credentials, the object contains a single parameter `id`, which specifies the UUID of the managed credentials you want to add.
**Note:** This form displays limited parameters that support a Windows type of credentials that uses password authentication.'
properties:
Host:
type: object
description: "The name of this parameter corresponds to the display name that uniquely identifies the credentials category (in this case, `Host` for credentials from the Host category). This value corresponds to the following response message attributes:\n - `credentials[].data[].name` in the [Get template details](ref:editor-template-details) response message\n - `credentials[].id` in the [List credential types](ref:credentials-list-credential-types) response message"
properties:
Windows:
type: array
description: "The name of this parameter corresponds to the display name that uniquely identifies the credentials type (in this case, `Windows` for a Windows credential). This value corresponds to the following response message attributes:\n - `credentials[].data[].types[].name` in the [Get template details](ref:editor-template-details) response message\n - `credentials[].types[].id` in the [List credential types](ref:credentials-list-credential-types) response message`"
items:
type: object
properties:
domain:
type: string
description: The Windows domain to which the username belongs.
username:
type: string
description: The username on the target system.
auth_method:
type: string
description: The name for the authentication method. This value corresponds to the credentials[].types[].configuration[].options[].id attribute in the response message for the [List credential types](ref:credentials-list-credential-types) endpoint.
enum:
- Password
password:
type: string
description: The user password on the target system.
Remediation_Scans_settings-rrules:
type: string
description: 'The interval at which the scan repeats. The interval is formatted as a string of three values delimited by semi-colons. These values are: the frequency (FREQ=ONETIME or DAILY or WEEKLY or MONTHLY or YEARLY), the interval (INTERVAL=1 or 2 or 3 ... x), and the days of the week (BYDAY=SU,MO,TU,WE,TH,FR,SA). For a scan that runs every three weeks on Monday Wednesday and Friday, the string would be `FREQ=WEEKLY;INTERVAL=3;BYDAY=MO,WE,FR`. If the scan is not scheduled to recur, this attribute is `null`. For more information, see [rrules Format](doc:example-assessment-scan-recurring#rrules-format).
**Note:** To set the `rrules` parameter for an agent scan, the request must also include the following body parameters:<ul><li>The `uuid` parameter must specify an agent scan template. For more information, see [Tenable-Provided Agent Templates](https://docs.tenable.com/vulnerability-management/Content/Scans/AgentTemplates.htm) and the [List templates](ref:editor-list-templates) endpoint.</li><li>The `agent_group_id` parameter must specify an agent group. For more information, see [Agent Groups](ref:agent-groups).</li></ul>For an example request body for an agent scan, see [Example Agent Scan: Recurring](doc:example-agent-scan-recurring).'
Remediation_Scans_settings-scan-triggers:
type: array
description: For Nessus Agent scans, describes the scan triggers used when `agent_scan_launch_type` is set to `triggered`.
items:
type: object
properties:
type:
type: string
description: The type of scan launch trigger (periodic or file-exists).
enum:
- periodic
- file-exists
options:
type: object
properties:
periodic_hourly_interval:
type: integer
description: The number of hours between successive scan launches. This option is only applicable for scan trigger type `periodic`.
minimum: 12
filename:
type: string
description: The name of the file which, when created, will trigger a scan launch. This option is only applicable for scan trigger type `file-exists`.
Remediation_Scans_Request-ScanSettings-Basic:
title: Basic Settings
description: Basic scan configuration settings including name, description, targets, scanner assignment, and notifications.
type: object
required:
- name
properties:
name:
type: string
description: '**[Basic]** Specifies the name of the scan.'
description:
type: string
description: '**[Basic]** Specifies the description of the scan.'
include_aggregate:
type: boolean
description: '**[Basic]** Specifies whether the scan results are shown in the workbenches, dashboards, and reports.'
scanner_type:
type: string
description: '**[Basic]** Specifies the type of scanner to use for the scan.'
example: internal
folder_id:
type: integer
description: '**[Basic]** Specifies the unique ID of the folder where you want to store the scan. Use the [List folders](ref:folders-list) endpoint to find the folder ID. If you omit this parameter from the request, the system assigns the ID of the default `main` folder.'
scanner_id:
type: string
description: '**[Basic]** Specifies the unique identifier (UUID) of the scanner to use for the scan. Use the [List scanners](ref:scanners-list) endpoint to retrieve available scanners. You can use the special value `AUTO-ROUTED` to assign scan targets automatically to scanner groups based on their configured scan routes. For more information, see [Manage Scan Routing](doc:manage-scan-routing-tio).
**Note:** If you omit this parameter from the request, the system assigns the default cloud scanner for your region.'
example: 00000000-0000-0000-0000-00000000000000000000000000001
target_network_uuid:
type: string
description: '**[Basic]** This field is required if the `scanner_id` parameter is `AUTO-ROUTED`. Specify a value as follows:<ul><li>If your scans involve separate environments with overlapping IP ranges, specify the UUID of the [network](doc:manage-networks-tio) you want to associate with the results of the auto-routed scan. This value must match the network where you have assigned the scanner groups that you configured for scan routing.</li><li>Otherwise, specify the default network (`00000000-0000-0000-0000-000000000000`).</li></ul>
**Note:** This parameter does not override network associations for scans that are not auto-routed. Tenable Vulnerability Management automatically associates a non-routed scan with the network to which you have assigned the scanner that performs the scan.'
example: 00000000-0000-0000-0000-000000000000
policy_id:
type: string
description: '**[Basic]** Specifies the unique ID of a user-defined policy to use for the scan. When creating a scan, if your user role is Scan Operator [24], this parameter is required. Use the [List policies](ref:policies-list) endpoint to find the policy ID.'
text_targets:
type: string
description: '**[Basic]** Specifies the list of targets to scan as a comma-separated string. For a full list of supported target formats, see the [Tenable Vulnerability Management User Guide](https://docs.tenable.com/vulnerability-management/Content/Scans/AboutScanTargets.htm). You can specify multiple targets of differing formats.
This parameter is required if your request omits other target parameters. For more information, see "Required Scan Target Parameters" in [Create a Scan](doc:create-scan-tio).
**Note:** The system does not perform validation on values you submit for this parameter. If you submit invalid values, they are stored in the scan configuration and scanning fails on the invalid targets when the scan runs.'
example: localhost
file_targets:
type: string
description: '**[Basic]** Specifies the name of a file containing the list of targets to scan. Use the [Upload file](ref:file-upload) endpoint to upload the file first, then use the `fileuploaded` attribute of the response as the `file_targets` parameter value.
This parameter is required if your request omits other target parameters. For more information, see "Required Scan Target Parameters" in [Create a Scan](doc:create-scan-tio).
**Note:** Unicode/UTF-8 encoding is not supported in the targets file.'
example: scan_targets.txt
target_groups:
type: array
items:
type: integer
description: '**[Basic]** Specifies an array of target group IDs to scan. Use the [List target groups](ref:target-groups-list) endpoint to determine target group IDs.
This parameter is required if your request omits other target parameters. For more information, see "Required Scan Target Parameters" in [Create a Scan](doc:create-scan-tio).'
example: '[2, 8, 12]'
asset_lists:
type: array
items:
type: integer
description: '**[Basic]** Specifies an array of asset list IDs to include as scan targets.'
tag_targets:
type: array
items:
type: string
description: '**[Basic]** Scan all assets that have any of the specified asset tag identifiers (UUIDs) applied. For more information about tag-based scans, see [Manage Tag-Based Scans](doc:manage-tag-based-scans-tio). For more information about asset tags, see [Manage Asset Tags](doc:manage-asset-tags-tio).
This parameter is required if your request omits other target parameters. For more information, see "Required Scan Target Parameters" in [Create a Scan](doc:create-scan-tio).'
tag_targets_ip_selection:
type: integer
description: '**[Basic]** Specifies the IP selection for tag-based scans.<ul><li>External — Runs a tag-based scan on non-RFC-1918 (public) IP addresses. Use integer `2` to select this option.</li><li>Internal — Runs a tag-based scan on RFC-1918 (private) IP addresses. Use integer `3` to select this option.</li></ul>**Note:** Cloud scanners can only scan external targets. If you need to scan both external and internal targets with the same tags, create two separate scan configurations.'
enum:
- 2
- 3
use_tag_rules_as_targets:
type: integer
description: '**[Basic]** Specifies whether the scan targets only existing tagged assets or any assets matching the tag rules.<ul><li>Existing tagged assets only — Scans all existing assets that have any of the specified tags applied. Use integer `0` to select this option.</li><li>Targets defined by tags — Scans all assets whose IP address or DNS matches the rules of the specified tags. This option only works for IPv4, IPv6, and DNS tag rules. Use integer `1` to select this option.</li></ul>For more information, see [Tags](https://docs.tenable.com/vulnerability-management/Content/Settings/Tagging/Tags.htm) and [Tag Rules](https://docs.tenable.com/vulnerability-management/Content/Settings/Tagging/TagRules.htm) in the Tenable Vulnerability Management User Guide.'
enum:
- 0
- 1
emails:
type: string
description: '**[Basic]** Email addresses used for notifications when a scan completes and results are available. Specify multiple email addresses in a comma-separated list.'
example: test1@test.com, test2@test.com
sms:
type: string
description: '**[Basic]** Mobile phone numbers used for notifications when a scan completes and results are available. Specify multiple phone numbers in a comma-separated list.'
example: 555-555-5555, 444-444-4444
filter_type:
type: string
description: '**[Basic]** Specifies the logical operator for notification filters. Use `and` to require all filters to match, or `or` to require any filter to match.'
enum:
- and
- or
example: and
filters:
type: array
description: '**[Basic]** Filters applied to the email and SMS notifications. When applied, for notifications to be sent, scans must match one or all conditions. If using multiple filters, choose a logical operator with the `filter_type` parameter.'
items:
type: object
properties:
filter:
type: string
description: The name of the filter, for example `plugin_id`.
quality:
type: string
description: The operator for the filter, for example `eq`.
value:
description: The value of the filter. For example, for `plugin_id`, *211637*.
oneOf:
- title: String Value
type: string
- title: Boolean Value
type: boolean
- title: Integer Value
type: integer
- title: Float Value
type: number
format: float
acls:
items:
$ref: '#/components/schemas/Remediation_Scans_settings-acls'
description: '**[Basic]** Specifies an array of access control entries (permissions) to apply to the scan.'
type: array
example: '[{"type": "default", "permissions": 16}, {"type": "user", "permissions": 64, "name": "admin", "id": 1, "owner": 1}]'
owner_id:
type: integer
description: '**[Basic]** Specifies the unique ID of the user to assign as the scan owner. You can only change ownership for scans where you have Owner [128] scan permissions. Only applicable when updating a scan. For more information, see [Change Scan Ownership](doc:change-scan-ownership-tio).'
host_tagging:
type: string
description: '**[Basic]** Specifies whether to create a unique identifier on hosts scanned using credentials.'
enum:
- 'yes'
- 'no'
default: 'yes'
example: 'yes'
scan_time_window:
type: integer
description: '**[Basic]** This parameter depends on the type of scan: <ul><li>For Nessus Agent scans, `scan_time_window` is the time frame, in minutes, during which agents must transmit scan results to Tenable Vulnerability Management in order to be included in dashboards and reports. If your request omits this parameter, the default value is 180 minutes.</li><li>For Nessus scanner scans, `scan_time_window` is the time frame, in minutes, after which the scan will automatically stop. If your request omits this parameter, the default value is 0 and the scan will not stop after a certain time frame.</li></ul>'
agent_group_id:
items:
type: string
description: '**[Basic]** Specifies an array of agent group UUIDs to scan. Required if the scan is an agent scan.'
type: array
agent_scan_launch_type:
$ref: '#/components/schemas/Remediation_Scans_settings-agent-scan-launch-type'
triggers:
$ref: '#/components/schemas/Remediation_Scans_settings-scan-triggers'
refresh_reporting_type:
type: string
description: '**[Basic]** Specifies how often the Nessus Agent reports unchanged info-level vulnerability findings. This setting corresponds to **Info-level Reporting** in **Basic Settings** in the user interface. For more information, see [Info-level Reporting](https://docs.tenable.com/vulnerability-management/Content/Scans/InfoLevelReporting.htm) in the Tenable Vulnerability Management User Guide.
You can configure agent scans to launch a new baseline scan after a certain interval, either number of scans or number of days. By default, the system uses the `scans` interval. Scheduled Nessus Agent scans can use either the `scans` or `days` type, but triggered Nessus Agent scans can only use the `scans` type.<ul><li>scans — The agent scan reports all findings every x number of scans. You can choose any integer from 4 to 20. Default value is `10`.</li><li>days — The agent scan reports all findings after a set number of days. You can choose any integer from 7 to 90. Default value is `10`.</li></ul><p>**Note:** This setting can only be used by agents version 10.5.0 and later. Agents on earlier versions always perform baseline scans.</p>'
default: scans
enum:
- scans
- days
refresh_reporting_frequency_scans:
type: integer
description: '**[Basic]** Specifies the number of scans after which the Nessus Agent reports all findings. Applies when `refresh_reporting_type` is set to `scans`. You can choose any integer from 4 to 20. Default value is `10`.'
default: 10
refresh_reporting_frequency_days:
type: integer
description: '**[Basic]** Specifies the number of days after which the Nessus Agent reports all findings. Applies when `refresh_reporting_type` is set to `days`. You can choose any integer from 7 to 90. Default value is `10`.'
default: 10
disable_refresh_reporting:
type: string
default: 'no'
description: '**[Basic]** Specifies whether to force a refresh of all info-level findings on the next scan. After the next scan completes and reports all findings, the `refresh_reporting_type` setting determines subsequent reporting frequen
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-remediation-scans-api-openapi.yml