Configure Scan Plugins

Required User Role: SCAN OPERATOR [24]

You can use the Create scan or Update scan endpoints to configure which plugins run during a scan. Plugins are organized into families (for example, Web Servers, Windows, DNS), and you can enable or disable plugins at both the family level and individual plugin level.

For background information about plugins, see Plugins in the Tenable Vulnerability Management User Guide.

Overview

The plugins object in the scan request body controls which plugin families and individual plugins are included in the scan. Each key in the object is a plugin family name, and the value defines the family's configuration.

📘
Note
The property names in the plugins object are dynamic — each key corresponds to a plugin family name. Use the List plugin families endpoint to retrieve available family names and IDs. Use the List plugins in family endpoint to find individual plugin IDs within a family.

Plugin Family Status

Each plugin family has a status that determines its behavior:

Status	Behavior
`enabled`	All plugins in the family are enabled for the scan.
`disabled`	All plugins in the family are disabled (excluded from the scan).
`mixed`	Some plugins in the family differ from the family default. Use the `individual` property to specify which plugins are overridden.

Plugin Family Properties

Property	Type	Description
`id`	integer	The unique identifier of the plugin family.
`status`	string	The overall status of the family: `enabled`, `disabled`, or `mixed`.
`individual`	object	An object mapping individual plugin IDs to `enabled` or `disabled`. Used when `status` is `mixed`.
`selectedStatus`	string	The default status for plugins not listed in `individual`.
`mixedDefault`	string	When `status` is `mixed`, the default applied to plugins not overridden.
`lock_state`	string	Controls whether scan operators can modify the plugin selections for this family in the user interface. See Lock State below.

Lock State

When a plugin family has status set to mixed (individual plugins overridden), the system automatically sets the family to Locked. A locked family prevents scan operators from modifying plugin selections in the user interface.

To allow scan operators to modify plugin selections within a mixed family via the user interface, explicitly set lock_state to Unlocked:

{
  "plugins": {
    "Misc.": {
      "id": 3,
      "status": "mixed",
      "individual": {
        "156166": "disabled"
      },
      "selectedStatus": "enabled",
      "mixedDefault": "enabled",
      "lock_state": "Unlocked"
    }
  }
}

📘
Note
If you omit lock_state when using mixed status, the family defaults to Locked.

Before You Begin

Required	Task
yes	Use the List plugin families endpoint to retrieve available family names and IDs.
no	Use the List plugins in family endpoint to find specific plugin IDs within a family.
no	Determine whether you want to lock or unlock families that use mixed status.

Common Configuration Patterns

Enable All Plugins in a Family

To enable all plugins in a family, set status to enabled:

{
  "plugins": {
    "Web Servers": {
      "id": 4,
      "status": "enabled"
    }
  }
}

Disable an Entire Family

To exclude all plugins in a family from the scan, set status to disabled:

{
  "plugins": {
    "SCADA": {
      "id": 39,
      "status": "disabled"
    }
  }
}

Disable Specific Plugins Within an Enabled Family

To keep a family enabled but disable one or more specific plugins, use mixed status with individual overrides. The selectedStatus and mixedDefault specify that the default for non-overridden plugins is enabled:

{
  "plugins": {
    "Misc.": {
      "id": 3,
      "status": "mixed",
      "individual": {
        "156166": "disabled",
        "200000": "disabled"
      },
      "selectedStatus": "enabled",
      "mixedDefault": "enabled",
      "lock_state": "Unlocked"
    }
  }
}

Enable Specific Plugins Within a Disabled Family

To keep a family disabled but enable only specific plugins (common for remediation scans), use mixed status with selectedStatus set to disabled:

{
  "plugins": {
    "Windows": {
      "id": 8,
      "status": "mixed",
      "individual": {
        "150373": "enabled",
        "158710": "enabled",
        "178245": "enabled"
      },
      "selectedStatus": "disabled"
    }
  }
}

Configure Multiple Families

You can configure multiple families in a single request:

{
  "plugins": {
    "Web Servers": {
      "id": 4,
      "status": "enabled"
    },
    "DNS": {
      "id": 34,
      "status": "enabled"
    },
    "SCADA": {
      "id": 39,
      "status": "disabled"
    },
    "Misc.": {
      "id": 3,
      "status": "mixed",
      "individual": {
        "156166": "disabled"
      },
      "selectedStatus": "enabled",
      "mixedDefault": "enabled",
      "lock_state": "Unlocked"
    }
  }
}

Related Resources

Create a Scan
Manage Remediation Scans (remediation scans use mixed plugins extensively)
Plugins in the Tenable Vulnerability Management User Guide