Launch a Remediation Scan on Tenable Security Center

A remediation scan evaluates a specific plugin against a specific target or targets where the related vulnerability was present in an earlier scan. A remediation scan is a type of active scan.

Remediation scans allow you to validate whether your vulnerability remediation actions on specific targets have been successful. If a remediation scan can no longer identify the vulnerability on targets where it was previously identified, the system changes the status of the vulnerability instances to mitigated. For more information about the methodology the system uses in remediation scans, see "Mitigation Logic" in the Tenable Security Center User Guide.

To launch a remediation scan on Tenable Security Center, Tenable recommends the following approach:

Authenticate, if you have not already done so. Be sure to include the authentication token in your request headers. For more information on authentication, see the description of the /token endpoint in the Tenable Security Center API reference guide.
Identify the plugin ID and plugin family ID for the vulnerability you want to remediate.

You can determine the plugin ID and plugin family ID from the vulnerability results of a standard scan. For more information on retrieving these results, see Retrieve Vulnerability Data for a Specific Time Range.

Alternatively, if you know the plugin ID but not the plugin family ID, use the /pluginFamily/{id} endpoint to retrieve the plugin family ID. For more information about this endpoint, see the description of the /pluginFamily endpoint in the Tenable Security Center API reference guide.

HTTP Request Syntax:

GET /rest/pluginFamily/pluginID

HTTP Request Example:

GET /rest/pluginFamily/97833

HTTP Response Example:

{ "type" : "regular", "response" : { "id" : "1000030", "name" : "Malware", "type" : "passive", "plugins" : [], "count" : 0 }, "error_code" : 0, "error_msg" : "", "warnings" : [], "timestamp" : 1408728549 }

The id field in this response is the plugin family ID. Retain this value for use in the next HTTP request (specifically, in the families parameter of the /policy request).

Create a scan policy for one-time use.

The policy you create in this step cannot be retrieved in a GET request to the /policy endpoint. This policy can be used only for this particular remediation scan.

Note: If you launch a remediation scan from the Tenable Security Center user interface, the system automatically creates a default policy, so there is no action in the Tenable Security Center user interface that is equivalent to this step.

HTTP Request Syntax:

POST /rest/policy{parameters}

Parameters must include:

Parameter	Value
`context`	`scan`
`families`	Both of the following: the plugin for the vulnerability you want to remediate (specifically, the plugin ID and plugin family ID you identified in Step 2) the Nessus Scan Information plugin (plugin ID 19506; plugin family ID 41) Note: If you omit plugin 19506, the remediation scan returns incomplete scan information, if any.
`policyTemplate{id}`	The code for the Advanced Template (`1`).
`preferences{parameter,...)`	Specifies parameters corresponding to custom scan policy options. The HTTP request example below includes the following parameters with their default settings: `portscan_range`—equivalent to Port Scanning > Ports > Port scan range `tcp_scanner`—equivalent to Port Scanning > Network Port Scanners > TCP `syn_scanner`—equivalent to Port Scanning > Network Port Scanners > SYN `udp_scanner`—equivalent to Port Scanning > Network Port Scanners > UDP `syn_firewall_detection`—equivalent to Port Scanning > Network Port Scanners > Override automatic firewall detection For more information on these parameters, see the Tenable Security Center User Guide.

HTTP Request Example:

{
  "name": "",
  "description": "",
  "context": "scan",
  "createdTime": 0,
  "modifiedTime": 0,
  "groups": [],
  "policyTemplate": {
    "id": 1
  },
  "auditFiles": [],
  "preferences": {
    "portscan_range": "default",
    "tcp_scanner": "no",
    "syn_scanner": "yes",
    "udp_scanner": "no",
    "syn_firewall_detection": "Automatic (normal)"
  },
  "families": [
    {
      "id": "20",
      "plugins": [
        {
          "id": "97833"
        }
      ]
    },
    {
      "id": "41",
      "plugins": [
      	{
          "id": "19506"
        }
      ]
    }
  ]
}

When you receive an HTTP response to your POST /policy request, retain the id element for use in the next HTTP request (that is, the POST /scan request).

HTTP Response Example:

"type": "regular", "response": { "id": "1000007", "name": "_1513112172_0.87691100_1_1_192.0.2.186_9070_scan_e448b4e5c935ed3738b1d06527975e73", "description": "", "tags": "" }

In this example, the policy ID is 1000007.

Use the /scan endpoint to launch a remediation scan.

HTTP Request Syntax:

POST /rest/scan{parameters}

Recommended parameters include:

Parameter	Value
`assets`	Specifies the asset or assets you want the remediation scan to target. Note: You can use either the `assets` parameter or the `ipList` parameter to specify assets, but you cannot use both parameters in a single request. Use an array of objects with the `id` attribute to specify individual assets. You can obtain asset IDs from the original scan results. For example: `"assets": [ { "id": 24 }, { "id": 20 }, { "id": 19 } ]` This parameter corresponds to the Targets section of an active scan in the Tenable Security Center user interface.
`classifyMitigatedAge`	Specifies the number of days the system waits to remove vulnerabilities from the cumulative database if the related hosts do not reply to the scan. If this parameter is set to `0`, the system removes the vulnerabilities immediately. If this parameter is set to any other valid value, the system waits that number of days before removing the vulnerabilities. Valid values include: `1`, `2`, `3`, `4`, `5`, `6`, `30`, `60`, `90`, and `365` (default). This parameter corresponds to the following parameters in the Settings section of an active scan in the Tenable Security Center user interface: Immediately remove vulnerabilities from scanned hosts that do not reply Number of days to wait before removing dead hosts
`dhcpTracking`	Specifies whether the system uses tracks hosts associated with changed IP addresses. The default value is `false`. Networks using DHCP require that this parameter be set to `true` to properly track hosts. This parameter corresponds to the Track hosts which have been issued new IP address parameter in the Settings section of an active scan in the Tenable Security Center user interface.
`emailOnLaunch`	Specifies whether the system emails you a notification when the scan launches. If you set this parameter to `true`, the system uses the email associated with the user account making the API request. This parameter corresponds to the E-mail me on Launch parameter in the Post Scan section of an active scan in the Tenable Security Center user interface.
`emailOnFinish`	Specifies whether the system emails you a notification when the scan completes. If you set this parameter to `true`, the system uses the email associated with the user account making the API request. This parameter corresponds to the E-mail me on Completion parameter in the Post Scan section of an active scan in the Tenable Security Center user interface.
`ipList`	Specifies the IP address or addresses of the asset or assets you want to scan. Note: You can use either the `assets` parameter or the `ipList` parameter to specify assets, but you cannot use both parameters in a single request. This value can be an IPv4 or IPv6 address (depending on the repository to be scanned), a CIDR address, or a DNS name. For example: "ipList": "198.168.1.1" This parameter corresponds to the Targets section of an active scan in the Tenable Security Center user interface.
`maxScanTime`	Specifies the number of hours after which the scan stops running. The default value is `unlimited`. This parameter corresponds to the Max scan duration parameter in the Settings section of an active scan in the Tenable Security Center user interface.
`name`	Specifies the display name of the remediation scan. To preserve consistency with remediation scans launched from the Tenable Security Center user interface, use the following name format: Remediation Scan of Plugin #pluginID This parameter corresponds to the Name parameter in the General section of an active scan in the Tenable Security Center user interface.
`policy`	Specifies the ID of the policy you created earlier. See Step 4 in this procedure.
`pluginID`	Specifies the ID of the plugin you want to remediate. Note: The plugin family ID is not required in this request.
`repository`	Specifies the ID of the repository where you want to import the remediation scan results. The repository for the remediation scan must be the same repository as the original scan. You can obtain the repository ID from the vulnerability results of the original scan. For more information on retrieving these results, see Retrieve Vulnerability Data for a Specific Time Range. This parameter corresponds to the Import Repository parameter in the Settings section of an active scan in the Tenable Security Center user interface.
`rolloverType`	Specifies how the system schedules the rollover scan it creates. This field is required if the `timeoutAction` is set to rollover. Valid values are: `nextday`—Create a rollover scan scheduled to launch the next day at the same start time as the just completed scan. `template`—Create a rollover scan as a template for users to launch manually. This parameter corresponds to the Rollover Schedule parameter in the Settings section of an active scan in the Tenable Security Center user interface.
`scanningVirtualHosts`	Specifies whether the system treats a new DNS entry for an IP address as a virtual host as opposed to a DNS name update. The default value is `false`. This parameter corresponds to the Scan Virtual Hosts parameter in the Settings section of an active scan in the Tenable Security Center user interface.
`schedule`	Specifies the schedule for the scan. For a remediation scan, this parameter must include the following fields: `start`—The time you want the scan to launch. Use the following format: `TZID=timezone` The time zone must be in the iCalendar date-time format. `repeatRule`—The frequency of the scan. Use the following value for this field: FREQ=NOW;INTERVAL=1 `type`—The type of scan. Use the following value for this field: now This value causes the system to delete the related one-time scan policy after the scan completes. For example: `"schedule": { "start": "TZID=America/New_York:20171212T160900", "repeatRule": "FREQ=NOW;INTERVAL=1", "type": "now" },`
`timeoutAction`	Specifies how the system responds if it cannot complete the scan. Valid values are: `discard`—Do not import any of the results obtained by the scan to the database. `import`—Import the results of the current scan and discard the information for any unscanned targets. `rollover`—Import the results from the scan into the database and create a rollover scan that may be launched at a later time to complete the scan. This parameter corresponds to the Scan Timeout Action parameter in the Settings section of an active scan in the Tenable Security Center user interface.
`type`	Specifies the scan type. To use the scan policy you created earlier, this value must be `policy`.

HTTP Request Example:

{
  "name": "Remediation Scan of Plugin #97833",
  "description": "",
  "context": "",
  "createdTime": 0,
  "modifiedTime": 0,
  "groups": [],
  "repository": {
    "id": 1
  },
  "schedule": {
    "start": "TZID=America/New_York:20171212T160900",
    "repeatRule": "FREQ=NOW;INTERVAL=1",
    "type": "now"
  },
  "dhcpTracking": "true",
  "emailOnLaunch": "false",
  "emailOnFinish": "false",
  "reports": [],
  "type": "policy",
  "policy": {
    "id": 1000007
  },
  "pluginID": "97833",
  "timeoutAction": "rollover",
  "rolloverType": "template",
  "scanningVirtualHosts": "false",
  "classifyMitigatedAge": 0,
  "assets": [
    {
      "id": 24
    },
    {
      "id": 20
    },
    {
      "id": 19
    }
  ],
  "ipList": "",
  "credentials": [],
  "maxScanTime": "unlimited"
}