Tenable.io

LAST UPDATED: APR 30, 2025

Overview

Tenable.io provides actionable insight into an infrastructure's security risks, making it easy to identify, investigate, and prioritize vulnerabilities and misconfigurations in an IT environment.

D3 SOAR is providing REST operations to function with Tenable.io.

Tenable.io is available for use in:

D3 SOAR	V12.7.241+
Category	Vulnerability Management
Deployment Options	Option II, Option IV

Known Limitations

Tenable Vulnerability Management performs rate limiting on API requests to ensure that all customers experience the same level of service. For more information, refer to Rate Limiting from Tenable's documentation.

Connection

To connect to Tenable.io from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The server URL of the Tenable.io environment.	https://cloud.tenable.com
API Access Key	The API access key to authenticate the connection.	*****
API Secret Key	The API secret key to authenticate the connection.	*****

Permission Requirements

Each endpoint in the Tenable.io API requires a certain permission scope. The roles listed below represent the minimum permissions required to execute the commands in this integration.

Command	Required Permission
Download Exported Scan	All roles can be used
Export Scan	All roles can be used
Get Scan Details	Basic User will only return limited information. All other roles can be used.
Get Scan Status	All roles can be used
Get Vulnerabilities by Asset	All roles can be used
Get Vulnerability Details	All roles can be used
Launch Scan	Administrator
List Plugin Outputs	All roles can be used
Get Scan History	All roles can be used
List Scans	All roles, but non-administrator role will return less data
List Vulnerability Filters V2	All roles can be used
Query Vulnerability Details	All roles can be used
Test Connection	Any role except for Basic User

As Tenable.io is using role-based access control (RBAC), the API Access Key and API Secret Key are generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the Tenable.io console for each command in this integration.

READER NOTE

Tenable.io's default user profiles are as follows:

Basic - Basic users can only view scan results and manage their user profile.
Scan Operator - Scan Operator users can create and run scans based on templates which the company has authorized.
Standard - Standard users can create scans, templates, and user target groups.
Scan Manager - Scan Manager users have the same privileges as the standard user, and can also manage agents, exclusions, and scanners.
Administrator - Administrators have the same privileges as the scan manager user, and can also manage users, groups, system target groups, and access groups. Additionally, administrators can view scans created by all users.
Disabled - Disabled user accounts cannot be used to log in to Tenable Vulnerability Management.

Configuring Tenable.io to Work with D3 SOAR

Log in to Tenable.io. Navigate to the Settings menu on the Tenable.io dashboard. Select Access Control and then choose the Users tab. Click on Create User to add a new user account.
After creating the user, locate and click on the newly created user profile. Ensure that the API Key option is enabled.

For role assignment, note that the Basic User role is not sufficient for integration with D3 SOAR. However, it may still be utilized for running commands, albeit with potential limitations. To understand the specific role requirements for commands and connectors, refer to the Permission Requirements section.

Go to My Account and select API Key. Click on Generate to create a new API key.
A warning message will appear. Read it and click Continue.
Once the API key is generated, a key and a secret will be provided. Ensure to save these credentials in a secure and accessible location for future reference and use.

Configuring D3 SOAR to Work with Tenable.io

Log in to D3 SOAR.
Find the Tenable.io integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Tenable.io in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Tenable.io.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users have the option to choose the specific tenant sites to share the connection with. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  
  1. Input the Server URL. The default value is https://cloud.tenable.com.
  2. Input the API Access Key obtained from Tenable. Refer to step 4 of Configuring Tenable.io to Work with D3 SOAR for more information.
  3. Input the API Secret obtained from Tenable. Refer to step 4 of Configuring Tenable.io to Work with D3 SOAR for more information.
10. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
11. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green check mark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Tenable.io includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Tenable.io API, please refer to the Tenable.io API reference.

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Tenable.io to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.

The selected time format will now be visible when configuring Date/Time command input parameters.

Add Agents to Groups

Creates a bulk operation task to add agents to specified agent groups.

READER NOTE

Group IDs is a required parameter to run this command.

Run the List Agent Groups command to obtain the Group IDs. Group IDs can be found in the raw data at the path $.Results[*].id (for Group ID) or $.Results[*].uuid (for Group UUID).

Agent Names and Agent IDs are optional parameters to run this command.

Run the List Agents command to obtain the Agent Names. Agent Names can be found in the raw data at the path $.agents[*].name.
Run the List Agents command to obtain the Agent IDs. Agent IDs can be found in the raw data at the path $.agents[*].id.

Either Agent Names or Agent IDs must be provided.

Input

Input Parameter	Required/Optional	Description	Example
Group IDs	Required	The IDs or UUIDs of the agent groups to which the agents are added. Group IDs can be obtained using the List Agent Groups command.	JSON `[ "*****" ]`
Agent Names	Optional	The names of the agents to add to the agent groups. Either Agent Names or Agent IDs must be provided. Agent Names can be obtained using the List Agents command.	JSON `[ "***", "***" ]`
Agent IDs	Optional	The IDs of the agents to add to the agent groups. Either Agent Names or Agent IDs must be provided. Agent IDs can be obtained using the List Agents command. Only Agent IDs are supported; Agent UUIDs are not accepted.	JSON `[ ***** ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Add Agents to Groups failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: AgentGroup with id ***** not found.

Error Sample Data

Add Agents to Groups failed.

Status Code: 404.

Message: AgentGroup with id ***** not found.

Download Exported Scan

Downloads an exported scan.

READER NOTE

Scan ID and File ID are required parameters to run this command.

Run the List Scans command to obtain Scan ID. Scan ID can be found in the returned raw data at the path $.scans[*].id.
Run the Export Scan command to obtain File ID. File ID can be found in the returned raw data at the path $.file.

Input

Input Parameter	Required/Optional	Description	Example
Scan ID	Required	The ID of scan to export as a scan report. Scan IDs can be obtained using the List Scans command.	***
File ID	Required	The ID of the file to poll. File IDs can be obtained using the Export Scan command.	*****

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Download Exported Scan failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Download Exported Scan failed:name 'time' is not defined.

Error Sample Data

Download Exported Scan failed.

Status Code: 400.

Message: Download Exported Scan failed:name 'time' is not defined.

Export Scan

Exports the specified scan.

READER NOTE

Scan ID is a required parameter to run this command.

Run the List Scans command to obtain Scan ID. Scan ID can be found in the returned raw data at the path $.scans[*].id.

History ID is an optional parameter to run this command.

Run the Get Scan History command to obtain History ID. History ID can be found in the returned raw data at the path $.id.

Input

Input Parameter	Required/Optional	Description	Example
Scan ID	Required	The ID of the scan to export. Scan IDs can be obtained using the List Scans command.	***
History ID	Optional	The ID of the historical data to export. History IDs can be obtained using the Get Scan History command. If this parameter is not defined, the latest data will be exported.	*****
Report Format	Required	The format of the exported report. The available options are Nessus, HTML, PDF, CSV, or DB. For scans that are older than 60 days, only the Nessus and CSV formated are supported.	HTML (Need Chapters parameter)
Chapters	Optional	The chapters to include in the export. This parameter accepts a semi-colon delimited string comprised of some combination of the following options: vuln_hosts_summary, vuln_by_host, compliance_exec, remediations, vuln_by_plugin, compliance). Note: This parameter is required if the file format is PDF or HTML.	vuln_hosts_summary;vuln_by_host;compliance_exec;remediations;vuln_by_plugin;compliance
Password	Optional	The password used to encrypt database exports. This parameter is required when exporting as DB.	PASSWORD

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Export Scan failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Scan ID) is invalid.

Error Sample Data

Export Scan failed.

Status Code: 400.

Message: The value for parameter (Scan ID) is invalid.

Export Vulnerabilities

Exports vulnerabilities that match the request criteria.

Input

Input Parameter	Required/Optional	Description	Example
Assets Number	Optional	The number of assets used to chunk the vulnerabilities. The vulnerabilities export is divided by the number of asset IDs per chunk. The exported data of a chunk is the sum of all vulnerabilities for each asset in that chunk. The range for the number of assets in a chunk is 50 to a maximum of 5,000. By default, the value is 50. If a value outside of this range is provided, the system uses the upper or lower-bound value.	100
Include Unlicensed	Optional	Whether to include unlicensed assets. By default, the value is set to False.	True
Asset IP	Required	The IP Address of the asset for which to export vulnerabilities.	*...*
Filters Object	Optional	Filters for exported vulnerabilities. Exports include accepted and non-accepted vulnerabilities found or fixed within the last 30 days if no time-based filters (indexed_at, last_fixed, last_found, or first_found) are provided. Refer to Export Vulnerabilities for the filter object structure.	JSON `{"severity":["critical","high"],"state":["OPEN"]}`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Export Vulnerabilities failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The Asset IP *...* is invalid IP Address.

Error Sample Data

Export Vulnerabilities failed.

Status Code: 400.

Message: The Asset IP ***.***.***.*** is invalid IP Address.

Get Scan Details

Returns scan results for a specific scan. Tenable.io returns results from the latest run of the specified scan.

READER NOTE

Scan ID is a required parameter to run this command.

Run the List Scans command to obtain Scan ID. Scan ID can be found in the returned raw data at the path $.scans[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Scan ID	Required	The ID of the scan to retrieve details. Scan IDs can be obtained using the List Scans command.	***

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Scan Details failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Scan ID) is invalid.

Error Sample Data

Get Scan Details failed.

Status Code: 400.

Message: The value for parameter (Scan ID) is invalid.

Get Scan History

Returns a list of scan run objects, each of which represents an individual run of the specified scan.

READER NOTE

Scan ID is a required parameter to run this command.

Run the List Scans command to obtain Scan ID. Scan ID can be found in the returned raw data at the path $.scans[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Scan ID	Required	The ID of the scan to retrieve scan history. Scan ID can be obtained using the List Scans command.	***
Limit	Optional	The maximum number of scans to return. If this parameter is not defined, the default limit is 50.	50
Offset	Optional	The initial scan run to retrieve. If this parameter is not defined, the offset defaults to 0.	0

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Scan History failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Scan ID) is invalid.

Error Sample Data

Get Scan History failed.

Status Code: 400.

Message: The value for parameter (Scan ID) is invalid.

Get Scan Status

Returns the latest status for the specified scan. Scans can have following statuses: aborted, canceled, completed, empty, imported, initializing, pausing, paused, pending, processing, resuming, running, stopped or stopping.

READER NOTE

Scan ID is a required parameter to run this command.

Run the List Scans command to obtain Scan ID. Scan ID can be found in the returned raw data at the path $.scans[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Scan ID	Required	The ID of the scan to retrieve its status. Scan IDs can be obtained using the List Scans command.	***

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Scan Status failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Scan ID) is invalid.

Error Sample Data

Get Scan Status failed.

Status Code: 400.

Message: The value for parameter (Scan ID) is invalid.

Get Vulnerabilities by Asset

Returns information on vulnerabilities associated with the specified host.

READER NOTE

The input IP address must already exist in the system.

Input

Input Parameter	Required/Optional	Description	Example
Target	Required	The IP address of the host to retrieve vulnerabilities.	*...*

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Vulnerabilities by Asset failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Get Vulnerabilities By Asset failed:'vulnerabilities.

Error Sample Data

Get Vulnerabilities by Asset failed.

Status Code: 400.

Message: Get Vulnerabilities By Asset failed:'vulnerabilities.

Get Vulnerability Details

Retrieves the details for a vulnerability by plugin ID.

READER NOTE

Plugin ID is a required parameter to run this command.

Run the Get Scan Details command to obtain Plugin ID. Plugin ID can be found in the returned raw data at the path $.vulnerabilities[*].plugin_id.

Input

Input Parameter	Required/Optional	Description	Example
Plugin ID	Required	The ID of the plugin to retrieve vulnerability details. Plugin IDs can be obtained using the Get Scan Details command.	*****

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Vulnerability Details failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Expecting value: line 1 column 1 (char 0).

Error Sample Data

Get Vulnerability Details failed.

Status Code: 400.

Message: Expecting value: line 1 column 1 (char 0).

Get Vulnerabilities Export Report

Downloads exported vulnerabilities as a JSON file. Chunks are available for download for up to 24 hours after they have been created.

READER NOTE

Export UUID is a required parameter to run this command.

Run the Export Vulnerabilities command to obtain the Export UUID. Export UUIDs can be found in the raw data at the path $.export_uuid.

Input

Input Parameter	Required/Optional	Description	Example
Export UUID	Required	The UUID for the vulnerability export request to download report. Export UUID can be obtained using the Export Vulnerabilities command.	*****
Export Fields	Optional	The vulnerability fields to be exported. Separate multiple field names with commas. By default, all fields are included. Field names may differ from those in the API payload; verify the correct names in the API response.	asset.fqdn,asset.ipv4,plugin.cve,plugin.cvss_base_score,plugin.family,plugin.name,plugin.patch_publication_date,plugin.see_also,plugin.solution,plugin.synopsis,plugin.vpr.score,plugin.id,output,port.port,port.protocol,severity,state

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Vulnerabilities Export Report failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Not found.

Error Sample Data

Get Vulnerabilities Export Report failed.

Status Code: 404.

Message: Not found.

Launch Scan

Launches the specified scan.

READER NOTE

Scan ID is a required parameter to run this command.

Run the List Scans command to obtain Scan ID. Scan ID can be found in the returned raw data at the path $.scans[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Scan ID	Required	The ID of the scan to launch. Scan IDs can be obtained using the List Scan command.	***

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Launch Scan failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Insufficient scope.

Error Sample Data

Launch Scan failed.

Status Code: 403.

Message: Insufficient scope.

List Agent Groups

Retrieves a list of agent groups.

Input

Input Parameter	Required/Optional	Description	Example
Group Name	Optional	Filters agent groups by group name. By default, agent groups regardless of group name are returned.	CIS Test

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Agent Groups failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid credentials.

Error Sample Data

List Agent Groups failed.

Status Code: 401.

Message: Invalid credentials.

List Agents

Returns a list of agents matching specified criteria. The returned agents are sorted by name alphabetically.

READER NOTE

It is recommended to narrow search results using available input parameters. A large agent count may cause slow loading or incomplete data due to response size limits.

Input

Input Parameter	Required/Optional	Description	Example
Host Name	Optional	The name of the agent to retrieve.	GRD-LPTP
IP	Optional	The IP address of the agent to retrieve.	*...*
Platform	Optional	The platform of the agents to retrieve. Valid values include "WINDOWS" and "LINUX".	WINDOWS

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Agents failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid credentials.

Error Sample Data

List Agents failed.

Status Code: 401.

Message: Invalid credentials.

List Agents by Group

Returns a list of agents for the specified agent group. The returned agents are sorted by name alphabetically.

READER NOTE

Group ID is a required parameter to run this command.

Run the List Agent Groups command to obtain the Group ID. Group IDs can be found in the raw data at the path $.Results[*].id (for Group ID) or $.Results[*].uuid (for Group UUID).

Input

Input Parameter	Required/Optional	Description	Example
Group ID	Required	The ID or UUID of the agent group for which to agents. Group ID can be obtained using the List Agent Groups command.	*****
Host Name	Optional	The name of the agent to retrieve.	GRD-LPTP
IP	Optional	The IP address of the agent to retrieve.	*...*
Platform	Optional	The platform of the agents to retrieve. Valid values include "WINDOWS" and "LINUX".	WINDOWS

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Agents by Group failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: AgentGroup with id ***** not found.

Error Sample Data

List Agents by Group failed.

Status Code: 404.

Message: AgentGroup with id ***** not found.

List Plugin Outputs

Retrieves the output of vulnerabilities for a plugin. The output is restricted to a maximum of 5,000 entries.

READER NOTE

Plugin ID is a required parameter to run this command.

Run the Get Scan Details command to obtain Plugin ID. Plugin ID can be found in the returned raw data at the path $.vulnerabilities[*].plugin_id.
If you input an invalid Plugin ID, the command will run successfully with no results.

Input

Input Parameter	Required/Optional	Description	Example
Plugin ID	Required	The ID of the plugin to list outputs. Plugin IDs can be obtained using the Query Vulnerability Details command.	*****

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Plugin Outputs failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Test connection failed Insufficient scope.

Error Sample Data

List Plugin Outputs failed.

Status Code: 403.

Message: Test connection failed Insufficient scope.

List Scans

Returns a list of scans according to the optional filters (Folder ID and Last Modification Date).

Input

Input Parameter	Required/Optional	Description	Example
Folder ID	Optional	The ID of the folder to retrieve scans.	11
Last Scan Run Date	Optional	The date to filter search results including scans that were conducted on or after the specified date, provided in UTC time.	2020-07-29 00:00

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Scans failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Test connection failed Insufficient scope.

Error Sample Data

List Scans failed.

Status Code: 403.

Message: Test connection failed Insufficient scope.

List Vulnerability Filters V2

Returns available filters for the vulnerabilities workbench.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Vulnerability Filters V2 failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Test connection failed Insufficient scope.

Error Sample Data

List Vulnerability Filters V2 failed.

Status Code: 403.

Message: Test connection failed Insufficient scope.

Query Vulnerability Details

Retrieves vulnerability details based on the specified search conditions.

READER NOTE

Plugin ID is an optional parameter to run this command.

Run the Get Scan Details command to obtain Plugin ID. Plugin ID can be found in the returned raw data at the path $.vulnerabilities[*].plugin_id.

Input

Input Parameter	Required/Optional	Description	Example
Plugin Name	Optional	The name of the plugin to retrieve vulnerabilities.	RHEL
Plugin ID	Optional	The ID of the plugin to retrieve vulnerabilities. Plugin IDs can be obtained using the Get Scan Details command.	*****
Description	Optional	The description text to filter vulnerabilities.	The remote web server is affected by a command injection vulnerability
VPR Score	Optional	The minimum VPR score to filter vulnerabilities.	7.0
Severity	Optional	The severity level to filter vulnerabilities. If this parameter is not defined, vulnerabilities of all severity levels will be returned.	Critical Severity
CVEs	Optional	The IDs of the CVEs to filter vulnerabilities.	JSON `[ "CVE-2023-1637" , "CVE-2008-5161" ]`
Host Names or IPs	Optional	The host names or IP addresses of the hosts to filter vulnerabilities.	JSON `[ "*...", "...*" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Query Vulnerability Details failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Test connection failed Insufficient scope.

Error Sample Data

Query Vulnerability Details failed.

Status Code: 403.

Message: Test connection failed Insufficient scope.

Remove Agents From Groups

Creates a bulk operation task to remove agents from specified agent groups.

READER NOTE

Group IDs is a required parameter to run this command.

Run the List Agent Groups command to obtain the Group IDs. Group IDs can be found in the raw data at the path $.Results[*].id (for Group ID) or $.Results[*].uuid (for Group UUID).

Agent Names and Agent IDs are optional parameters to run this command.

Run the List Agents by Group command to obtain the Agent Names. Agent Names can be found in the raw data at the path $.Results[*].name.
Run the List Agents by Group command to obtain the Agent IDs. Agent IDs can be found in the raw data at the path $.Results[*].id.

Either Agent Names or Agent IDs must be provided.

Input

Input Parameter	Required/Optional	Description	Example
Group IDs	Required	The IDs or UUIDs of the agent groups from which the agents are removed. Group IDs can be obtained using the List Agent Groups command.	JSON `[ "*****" ]`
Agent Names	Optional	The names of the agents to remove from the agent groups. Either Agent Names or Agent IDs must be provided. Agent Names can be obtained using the List Agents by Group command.	JSON `[ "***", "***" ]`
Agent IDs	Optional	The IDs of the agents to remove from the agent groups. Either Agent Names or Agent IDs must be provided. Agent IDs can be obtained using the List Agents by Group command. Only Agent IDs are supported; Agent UUIDs are not accepted.	JSON `[ ***** ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Remove Agents From Groups failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid credentials.

Error Sample Data

Remove Agents From Groups failed.

Status Code: 401.

Message: Invalid credentials.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Output Type

Description

Return Data Type

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

More details about an error can be viewed in the Error tab.

String

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Tenable.io portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Test connection failed Insufficient scope.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: Test connection failed Insufficient scope.