Launch a Scan

Required User Role: SCAN OPERATOR [24]
Required Scan Permissions: CAN EXECUTE [32]

You may want to launch a scan if:

• You configured the scan to run on demand only.
• You want to run a scan immediately, in addition to the configured schedule.

📘

Note

For information about running scans automatically on a schedule, see Example Assessment Scan: Recurring.

You can launch a scan if the following conditions are present:

• The scan is not imported (that is, if the info.control attribute for the scan is true).
• Your user account has CAN CONTROL (32) permissions for the scan you want to launch.

To launch a scan:

1. Determine the ID of the scan you want to launch.
2. Use the POST /scans/{scan_id}/launch endpoint to launch the scan:
   • To use the targets specified in the scan configuration, you can omit the request body.
   • To use alternate targets, specify a comma-separated list of targets in the alt_targets parameter in the request body. This parameter overrides the targets specified in the scan configuration.

What to do next:

• (Optional) Use the GET /scans/{scan_id}/latest-status endpoint to monitor the status of the scan as it runs.
• Once scan processing is complete, do any of the following:
  • View results from the latest run of the scan.
  • View results from a historical run of the scan.
  • View results from aggregated runs of the scan.

👍

Example

Scans (pyTenable)

Example Assessment Scan: Launch the Scan with Alternate Targets

Related endpoint: POST /scans/{scan_id}/launch

The example request body launches a run of the specified scan configuration.

{
  "alt_targets": ["192.0.2.57,192.0.2.177,192.0.2.8,192.0.2.176,192.0.2.225"]
}