Create a Scan
Required User Role: SCAN OPERATOR [24]
You can use the POST /scans endpoint to create scan configurations.
Note
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.
Before You Begin
Use the following steps to gather information needed for scan configuration and perform any preparatory tasks.
Any Scan
| Required | Task |
|---|---|
| yes | Identify the targets you want to scan. |
| no | Upload a targets file for the scan. |
| no | Create or identify a target group to use in the scan. |
| yes | Determine the UUID of the Tenable-provided template you want to use for the scan. |
| yes | Determine the parameters supported for the Tenable-provided template. |
| yes | Determine the ID of the scanner you want to use for the scan. |
| no | Determine the UUID of the scan policy you want to use for the scan. |
| no | Determine the ID of the folder where you want to store the scan. |
| no | Determine 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 Vulnerability Management; otherwise, the results of the scans may not be included in Vulnerability Management dashboards and reports. |
Scheduled Scan
Note that scheduled scans do not run if they are in the scan owner's trash folder.
| Required | Task |
|---|---|
| yes | Determine when you want the scan to run (what day and time). |
| yes | Determine the timezone value. |
| yes | Determine how often you want the scan to run (once, daily, weekly, monthly, or yearly). |
Credentialed Scan
| Required | Credential Type | Task |
|---|---|---|
| yes | any | Determine what type of credentials you want to use in the scan. |
| yes | scan-specific | Determine the settings for the specific credential type. |
| no | scan-specific | If a specific setting requires a file (for example, a private key file for SSH credentials), upload the required files to Vulnerability Management. |
| yes | managed | Create a managed credential, or determine the UUID of the existing managed credential you want to use. |
Agent Scan
| Required | Task |
|---|---|
| yes | Configure and deploy agents on local hosts as described in the Nessus Agent and Deployment User Guide. |
| yes | Determine the agent group ID. |
| no | Determine 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 Vulnerability Management; otherwise, the results of the agent scans may not be included in Vulnerability Management dashboards and reports. |
Shared Scan
| Required | Task |
|---|---|
| no | To 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:
| Parameter | Type | Description | Example |
|---|---|---|---|
| text_targets | string | A list of targets to scan. For supported target formats, see the Tenable 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: Vulnerability Management does not perform validation on values you submit for this parameter. If you submit invalid values, Vulnerability Management 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_groups | array of integers | An array of target group IDs to scan. Use the GET /target-groups endpoint to determine a target group ID. | [2, 8, 12] |
| file_targets | string | The 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 Vulnerability Management; 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_targets | array of strings | The 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
- Example Discovery Scan: Launch on Demand
- Example Agent Scan: Recurring
- Example Assessment Scan: Launch on Demand
- Example Assessment Scan: Shared
- Example Assessment Scan: Policy-based
- Example Assessment Scan: Recurring
- Example Assessment Scan: Scan-Specific Credentials (Windows)
- Example Assessment Scan: Scan-specific Credentials (SSH)
- Example Assessment Scan: Managed Credentials (Windows)
- Remediation Scan: Multiple Assets and Plugins
Updated 3 days ago