Manage Remediation Scans

Tenable.io remediation scans allow you to validate whether your vulnerability remediation actions on scan targets have been successful. If a remediation scan cannot identify a vulnerability on targets where the vulnerability was previously identified, the system changes the status of the vulnerability to Fixed.

You can create a remediation scan to run a follow-up scan against existing scan results. A remediation scan evaluates a specific plugin against a specific scan target or targets where a vulnerability was present in your earlier active scan.

Configuration Guidelines

  • Remediation scans are supported from the following sensors: Tenable.io cloud, On-premises Nessus, and Nessus scanner for Amazon Web Services (AWS).
  • Passing credentials in remediation scans is identical to standard scans.
  • Tagging is supported for specifying targets, but agent scans are not supported.
  • Remediation scans can also be performed in the Tenable.io User Interface. For more information, see Launch a Remediation Scan in the Tenable.io Vulnerability Management User Guide.

Before You Begin

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

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.
noDetermine the parameters supported for the Tenable-provided template.
noDetermine 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.

Remediation Scan Template

Requires STANDARD [32] user permissions

You must first select an appropriate template specific to remediation scans. You can find remediation scan templates using the GET /editor/{type}/templates endpoint. For the type path parameter, use the value remediation to find a list of remediation scan templates.

Configuration Limitations

Most settings are configured automatically when using a uuid associated with a remediation scan template found using the GET /editor/remediation/templates endpoint. When configuring a remediation scan, the request body settings must be as follows:

  • settings.folder_id must be null
  • settings.enabled must be false or null
  • settings.starttime must be null
  • settings.rrules must be null
  • settings.timezone must be null

A 400 Bad Request is returned if you attempt to create a remediation scan without using a remediation scan template.

Create the Remediation Scan

Requires SCAN MANAGER [40] user permissions

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

The following parameters are required:

  • uuid - A UUID associated with a remediation type scan template found using the GET /editor/remediation/templates endpoint.
  • settings.name - A name for the remediation scan.
  • A target specified using one of the available target parameters, text_targets, target_groups, file_targets, or tag_targets. The target should be a valid target from a previous scan you wish to remediate.
  • enabled_plugins - An array of plugin IDs to include for the remediation scan.

Example: Remediation Scan with One Asset and One Plugin

The request body below creates a remediation scan for one asset with one plugin via the POST /scans/remediation endpoint.

{
    "uuid": "ad629e16-03b6-8c1d-cef6-ef8c9dd3c658d24bd260ef5f9e66",
    "settings": {
        "name": "remediationSingle",
        "description": "string",
        "policy_id": 602,
        "enabled": false,
        "launch": "string",
        "scan_time_window": 0,
        "text_targets": "192.0.2.1",
        "tag_targets": [],
        "agent_group_id": [],
        "acls": "[{\"type\": \"default\", \"permissions\": 16}, {\"type\": \"user\", \"permissions\": 64, \"name\": \"admin\", \"id\": 1, \"owner\": 1}]"
    },
    "credentials": {
      "add": {
          "Host": {
            "Windows": [
              {
                  "domain": "",
                  "username": "[email protected]ple.com",
                  "auth_method": "Password",
                  "password": "aJ^deq34Rc"
                }
            ]
          }
      }
    },
    "enabled_plugins": [
          "11213"
    ]
}

The 200 OK response for the remediation scan creation request is below:

{
   "scan": {
      "tag_type": null,
      "container_id": "7a818eb1-8351-4795-99b0-9610c8954cb4",
      "owner_uuid": "18f1b7a3-caf0-4ef6-87a5-2d31338ead34",
      "uuid": "template-e8c7ce1b-9781-78ac-dfcb-d2071bc0f12259c99a858ea94007",
      "name": "remediationSingle",
      "description": null,
      "policy_id": 602,
      "scanner_id": null,
      "scanner_uuid": "00000000-0000-0000-0000-00000000000000000000000000001",
      "emails": null,
      "sms": "",
      "enabled": false,
      "include_aggregate": true,
      "scan_time_window": null,
      "custom_targets": "192.0.2.1",
      "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": "[email protected]",
      "owner_id": 28,
      "last_modification_date": 1612199394,
      "creation_date": 1612199394,
      "type": "public",
      "id": 603
   }
}

For a remediation scan example including multiple assets and plugins, see Example Remediation Scan: Multiple Assets and Plugins.

Update a Remediation Scan

You can use the PUT /scans/{scan_id} endpoint to update a remediation scan.

Configuration Limitations

Updating a remediation scan utilizes the same parameters used when creating a remediation scan. You can update a remediation scan using the PUT /scans/{scan_id} endpoint.

When updating a remediation scan, the request body settings must be as follows:

  • settings.folder_id must be null
  • settings.enabled must be false or null
  • settings.starttime must be null
  • settings.rrules must be null
  • settings.timezone must be null

List Remediation Scans

You can use the GET /scans/remediation endpoint to list remediation scans. The following query parameters are available:

ParameterTypeSettings
offsetintegerdefault: 0
min: 0
limitintegerdefault: 50
min: 1
max: 200
sortstringdefault: scan_creation_date:desc
valid fields: scan_creation_date
valid order directions: desc, asc

The attribute scan_creation_date is included in the response. This attribute is the Unix timestamp when the scan run was created. Note the functional difference with the creation_date attribute which is the date on which the scan configuration was originally created. The scan_creation_date attribute is the only field that can be used to order the data in the response.