Create a Scan

Required User Role: SCAN OPERATOR [24]

You can use the POST /scans endpoint to create scan configurations.

📘

Note

Tenable.io 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.

Before You Begin

Use the following steps to gather information needed for scan configuration and perform any preparatory tasks.

Any Scan

RequiredTask
yesIdentify the targets you want to scan.
noUpload a targets file for the scan.
noCreate or identify a target group to use in the scan.
yesDetermine the UUID of the Tenable-provided template you want to use for the scan.
yesDetermine the parameters supported for the Tenable-provided template.
yesDetermine the ID of the scanner you want to use for the scan.
noDetermine the UUID of the scan policy you want to use for the scan.
noDetermine the ID of the folder where you want to store the scan.
noDetermine the time frame you want the scan to run, in minutes, with the scan_time_window parameter. Set a large enough window to allow the scan results to transmit to Tenable.io; otherwise, the results of the scans may not be included in Tenable.io dashboards and reports.

Scheduled Scan

Note that scheduled scans do not run if they are in the scan owner's trash folder.

RequiredTask
yesDetermine when you want the scan to run (what day and time).
yesDetermine the timezone value.
yesDetermine how often you want the scan to run (once, daily, weekly, monthly, or yearly).

Credentialed Scan

RequiredCredential TypeTask
yesanyDetermine what type of credentials you want to use in the scan.
yesscan-specificDetermine the settings for the specific credential type.
noscan-specificIf a specific setting requires a file (for example, a private key file for SSH credentials), upload the required files to Tenable.io.
yesmanagedCreate a managed credential, or determine the UUID of the existing managed credential you want to use.

Agent Scan

RequiredTask
yesConfigure and deploy agents on local hosts as described in the Nessus Agent and Deployment User Guide.
yesDetermine the agent group ID.
noDetermine the time frame you want the agent scan to run, in minutes, with the scan_time_window parameter. Set a large enough window to allow agents to transmit scan results to Tenable.io; otherwise, the results of the agent scans may not be included in Tenable.io dashboards and reports.

Shared Scan

RequiredTask
noTo share the scan with other users, determine the IDs of appropriate users or user groups.

Required Scan Target Parameters

A valid request message for the POST /scans endpoint must include at least one of the following parameters:

ParameterTypeDescriptionExample
text_targetsstringA list of targets to scan. For supported target formats, see the Tenable.io Vulnerability Management User Guide. You can specify multiple targets (of differing formats) as a comma-delimited list. You can submit this parameter empty if you want to add targets to the scan via a later update.

Note: Tenable.io does not perform validation on values you submit for this parameter. If you submit invalid values, Tenable.io stores the invalid values in the scan configuration, and when the scan runs, scanning fails on the invalid targets."
192.0.2.1-192.0.2.255
target_groupsarray of integersAn array of target group IDs to scan. Use the GET /target-groups endpoint to determine a target group ID.[2, 8, 12]
file_targetsstringThe name of a file containing the list of targets to scan. Before you use this parameter, use the POST /files/upload endpoint to upload the file to Tenable.io; then, use the 'fileuploaded' attribute of the response message as the file_targets parameter value.

Note: Unicode/UTF-8 encoding is not supported in the targets file.
scan_targets.txt
tag_targetsarray of stringsThe list of asset tag identifiers that the scan uses to determine which assets it evaluates. For more information about tag-based scans, see Manage Tag-Based Scans.[
"a7ff9cd4-4fa1-41e2-981b-4e4df38ea68b",
"7acbf717-302b-4437-acd7-7744530926c1"
]

Request Body Examples