TOC & Recently Viewed

Recently Viewed Topics

Launch a Remediation Scan on SecurityCenter

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 SecurityCenter User Guide.

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

  1. 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 SecurityCenter API reference guide.
  2. 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 SecurityCenter 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).

  3. 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 SecurityCenter user interface, the system automatically creates a default policy, so there is no action in the SecurityCenter 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 “Custom Scan Policy Options” in the SecurityCenter 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" } ] } ] }
  4. 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_172.20.128.186_9070_scan_e448b4e5c935ed3738b1d06527975e73", "description": "", "tags": "" }

    In this example, the policy ID is 1000007.

  5. 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 SecurityCenter 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 SecurityCenter 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 SecurityCenter 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 SecurityCenter 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 SecurityCenter 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 SecurityCenter 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 SecurityCenter user interface.
    name

    Specifies the display name of the remediation scan.

    To preserve consistency with remediation scans launched from the SecurityCenter 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 SecurityCenter 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 SecurityCenter 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 SecurityCenter 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 SecurityCenter 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 SecurityCenter 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" }

Copyright 2017 Tenable, Inc. All rights reserved. Tenable Network Security, Nessus, SecurityCenter, SecurityCenter Continuous View and Log Correlation Engine are registered trademarks of Tenable, Inc.  Tenable, Tenable.io, Assure, and The Cyber Exposure Company are trademarks of Tenable, Inc.  All other products or services are trademarks of their respective owners.