Fortinet Document Library

Version:


Table of Contents

1.0.0
Copy Link

About the connector

ShieldX provides comprehensive, automated, and consistent network security, which is synchronized with changes in multi-cloud environments.

This document provides information about the ShieldX connector, which facilitates automated interactions with the ShieldX console using FortiSOAR™ playbooks. Add the ShieldX connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating a workload or network tag for group-based tagging operations, retrieving a list of tags, pulling events that match a threat signature, etc.

You can use FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling threat events (shieldxalerts or shieldxsecurityevents) from ShieldX. For more information, see the Data Ingestion Support section.

Version information

Connector Version: 2.0.0

FortiSOAR™ Version Tested on: 6.4.1-2133

ShieldX Version Tested on:2.1.952

Authored By: Fortinet

Certified: Yes

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:

yum install cyops-connector-shieldx

Prerequisites to configuring the connector

  • You must have the URL of the ShieldX management console to which you will connect and perform the automated operations and credentials (username-password pair) to access that console.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Permissions Required

The ShieldX connector and perform the automated operations, you must be assigned the "SuperUser" role.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the ShieldX connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Server URL IP address of ShieldX management console to which you will connect and perform the automated operations.
Username Username to access the ShieldX management console to which you will connect and perform the automated operations.
Password Password to access the ShieldX management console to which you will connect and perform the automated operations.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from version 4.10.0 and onwards:

Function Description Annotation and Category
Create Tag Creates a workload or network tag for group-based tagging operations in ShieldX based on the tag name and its key and value you have specified.  create_tag
Investigation
Get Tags Retrieves a list of tags from ShieldX or details of a specific tag from ShieldX based on the tag ID you have specified. get_tag
Investigation
Fetch Threat Events Pulls threat events matching a threat signature from ShieldX based on the index type, record count, and other input parameters you have specified. The threat events contain the attacker details (source of attack) and the target details (destination of attack) and other relevant details. search_events_by_index
Investigation
List Infrastructure

Retrieves a list of all infrastructure access configurations from ShieldX or details of a specific infrastructure access configuration from ShieldX based on the infrastructure ID you have specified.

list_infrastructure
Investigation
List Workloads

Retrieves a list of all ShieldX workloads from ShieldX or details of a specific workload from ShieldX based on the cloud infrastructure ID you have specified.

list_workloads
Investigation
Get Workload Details Retrieves details of a ShieldX workload based on the workload ID you have specified. workloads_details
Investigation
List Security Policies

Retrieves a list of all security policy sets from ShieldX or details of a specific security policy set from ShieldX based on the security policy set ID you have specified.

list_security_policy
Investigation
Update Security Policy Updates a specific security policy set in ShieldX based on the security policy ID and other input parameters you have specified. update_security_policy
Investigation
Assign Tag Assigns a tag to a workload or network ID in ShieldX based on the infrastructure ID, VM ID, tags, etc you have specified. assign_tag
Investigation
Unassign Tag Unassigns a workload or network that was tagged for quarantine purposes in ShieldX based on the infrastructure ID, VM ID, tags, etc you have specified. unassign_tag
Investigation
Get Tag List Get available ShieldX tag key:value list. list_tag
Investigation
Get List of Workload Tag Retrieves available ShieldX tag list. list_tag
Investigation

operation: Create Tag

Input parameters

Parameter Description
Tag Name Name of the tag that you want to create in ShieldX.
Tag Key Key of the tag such as. "Application" that you want to create in ShieldX.
Tag Value Value of the tag such as, "Accounting" that you want to create in ShieldX.

Output

The output contains the following populated JSON schema:
{
     "tag_id": ""
}

operation: Get Tags

Input parameters

Parameter Description
Tag ID ID of the tag whose details you want to retrieve from ShieldX.
Note: If you do not specify the tag ID, then this operation retrieves a list of all tags from ShieldX.

Output

The output contains the following populated JSON schema:

Output schema when the tag ID is not specified, i.e., {{id === ''}}:
[
     {
         "name": "",
         "key": "",
         "id": "",
         "lastModified": "",
         "value": ""
     }
]

Output schema when the tag ID is specified:
{
     "name": "",
     "key": "",
     "id": "",
     "lastModified": "",
     "value": ""
}

operation: Fetch Threat Events

Input parameters

Parameter Description
Index Type Type of index based on which you want to fetch threat events from ShieldX. You can choose between Alerts or Events.
  • Alerts: Looks up the shieldxalerts index that holds threat events. This index contains threat detection security events, including Malware and Indicator of Pivot (IoP) (east-west detection correlated with north-south) events.
  • Events: Looks up the shieldxsecurityevents security event types such as Threats, App detections, Malware, IoP, and ACL events.
Record Count (Optional) Maximum number of records that this operation should fetch from ShieldX. The maximum number of records that can be fetched per query is 10,000.
Note: If you do not specify the record count, then by default this operation fetches 10 records.
Sort By (Optional) Sorts the results retrieved from ShieldX based on the fields (dimensions) that you have specified. This query sorts on two dimensions – Timestamp in an ascending or descending order (oldest events first) and on ID, which is the index for each record in the database.
Sort Order (Optional) Order to sort the results retrieved from ShieldX. You can choose between Ascending or Descending.
Offset (Optional) 0-based index of the page that this operation should return. This indicates the ID from which the next 10,000 records should be fetched, in case of pagination. This is useful only if more than 10k threats are returned in a 30 seconds window, which is highly unlikely.
Search After (Optional) Search after element to be passed when a non-zero management timestamp is available from a previous query result set with the maximum management timestamp and _id returned from the previous query. eg. [1597627505280,"HxwF-nMBk8PLPApZGruC"]
Start Time (Optional) Start datetime from when you want to retrieve threat events from ShieldX.
End Time (Optional) End datetime till when you want to retrieve threat events from ShieldX.

Output

The output contains the following populated JSON schema:
{
     "responses": [
         {
             "timed_out": "",
             "status": "",
             "took": "",
             "hits": {
                 "total": "",
                 "hits": [
                     {
                         "sort": [],
                         "_score": "",
                         "_index": "",
                         "_source": {
                             "microServiceInstanceId": "",
                             "mgmtTimeStamp": "",
                             "chassisId": "",
                             "timeStamp": "",
                             "tenantId": "",
                             "version": "",
                             "dataPlane": "",
                             "microServiceType": "",
                             "event": {
                                 "endPacketId": "",
                                 "attackerIp": "",
                                 "attackerResourceGroup": "",
                                 "targetIp": "",
                                 "appId": "",
                                 "protocol": "",
                                 "pmId": "",
                                 "srcResourceGroup": "",
                                 "cveId": "",
                                 "policyId": "",
                                 "targetVmId": "",
                                 "threatName": "",
                                 "span": "",
                                 "packetId": "",
                                 "severityLevel": "",
                                 "target": "",
                                 "attackerVmId": "",
                                 "srcIpAddress": "",
                                 "dstPort": "",
                                 "srcContextId": "",
                                 "srcPort": "",
                                 "targetResourceGroup": "",
                                 "severity": "",
                                 "targetVmName": "",
                                 "cveYear": "",
                                 "attackPacketId": "",
                                 "attackerNetworkId": "",
                                 "attackerVmName": "",
                                 "policyName": "",
                                 "sensorResponse": "",
                                 "policyResponse": "",
                                 "transactionId": "",
                                 "policyType": "",
                                 "securityPolicySetName": "",
                                 "dstIpAddress": "",
                                 "eventType": "",
                                 "protocolName": "",
                                 "dstResourceGroup": "",
                                 "dstContextId": "",
                                 "managementResponse": "",
                                 "targetNetwork": "",
                                 "targetNetworkId": "",
                                 "attacker": "",
                                 "direction": "",
                                 "startPacketId": "",
                                 "flowCookie": "",
                                 "actionTkn": "",
                                 "attackerNetwork": ""
                             },
                             "microServiceTypeString": "",
                             "doctype": "",
                             "microServiceName": ""
                         },
                         "_id": "",
                         "_type": "",
                         "_routing": ""
                     }
                 ],
                 "max_score": ""
             },
             "_shards": {
                 "skipped": "",
                 "total": "",
                 "failed": "",
                 "successful": ""
             }
         }
     ]
}

operation: List Infrastructure

Input parameters

Parameter Description
Infrastructure ID

ID of the infrastructure access configuration whose details you want to retrieve from ShieldX.
Note: If you do not specify the infrastructure access configuration ID, then this operation retrieves a list of all infrastructure access configurations from ShieldX.

Output

The output contains the following populated JSON schema:

Output schema when the infrastructure ID is not specified, i.e., {{InfraId === ''}}:
[
     {
         "id": "",
         "name": "",
         "ip": "",
         "username": "",
         "password": "",
         "type": "",
         "domain": "",
         "https": "",
         "accessKeyId": "",
         "secretAccessKey": "",
         "clientId": "",
         "clientSecretKey": "",
         "subscription": "",
         "lastJobId": "",
         "hostClusterNameMapping": "",
         "aclPolicyId": "",
         "lastModified": ""
     }
]

Output schema when the infrastructure ID is specified
{
     "id": "",
     "name": "",
     "ip": "",
     "username": "",
     "password": "",
     "type": "",
     "domain": "",
     "accessKeyId": "",
     "secretAccessKey": "",
     "lastJobId": "",
     "clientId": "",
     "aclPolicyId": "",
     "lastModified": "",
     "subscription": "",
     "clientSecretKey": "",
     "hostClusterNameMapping": null
}

operation: List Workloads

Input parameters

Parameter Description
Infrastructure ID Cloud infrastructure ID whose workload details you want to retrieve from ShieldX.
Note: If you do not specify the cloud infrastructure ID, then this operation retrieves a list of all workloads from ShieldX.

Output

The output contains the following populated JSON schema:
{
     "workloadMap": {},
     "attributesFound": "",
     "workloads": [
         {
             "environment": "",
             "tenantId": "",
             "dataRiskCount": "",
             "tags": [],
             "name": "",
             "ports": [
                 {
                     "macAddress": "",
                     "vmId": "",
                     "networkId": "",
                    "ipAddresses": [],
                     "isSegmented": ""
                 }
             ],
             "nativeTags": [],
             "id": "",
             "attackCount": "",
             "cloudId": ""
         }
     ]
}

operation: Get Workload Details

Input parameters

Parameter Description
Workload ID ID of the workload whose details you want to retrieve from ShieldX.
Note: You can retrieve the workload ID using the "Fetch Threat Events" or "List Workloads" operations.

Output

The output contains the following populated JSON schema:
{
     "ports": [
         {
             "vmId": "",
             "networkId": "",
             "networkName": "",
             "macAddress": "",
             "ipAddresses": [],
             "isSegmented": ""
         }
     ],
     "environment": "",
     "id": "",
     "name": "",
     "attackCount": "",
     "tenantName": "",
     "dataRiskCount": "",
     "cloudType": "",
     "cloudId": "",
     "tenantId": "",
     "cloudName": "",
     "tags": [
         {
             "id": "",
             "key": "",
             "name": "",
             "value": "",
             "lastModified": ""
         }
     ],
     "nativeTags": []
}

operation: List Security Policies

Input parameters

Parameter Description
Security Policy Set ID ID of the security policy set whose details you want to retrieve from ShieldX.
Note: If you do not specify the security policy set ID, then this operation retrieves a list of all security policy sets from ShieldX.

Output

The output contains the following populated JSON schema:

Output schema when the security policy set ID is not specified, i.e., {{id === ''}}:
[
     {
         "malwarePolicyName": "",
         "lastModified": "",
         "malwarePolicyId": "",
         "id": "",
         "threatPreventionPolicyId": "",
         "name": "",
         "uServices": [],
         "isEditable": "",
         "tenantId": "",
         "isNull": "",
         "isDlpPolicy": "",
         "isAnomalyDetection": "",
         "threatPreventionPolicyName": "",
         "urlfilteringPolicyName": "",
         "urlfilteringPolicyId": ""
     }
]

Output schema when the security policy set ID is specified:
{
     "malwarePolicyName": "",
     "lastModified": "",
     "malwarePolicyId": "",
     "id": "",
     "threatPreventionPolicyId": "",
     "name": "",
     "uServices": [],
     "isEditable": "",
     "tenantId": "",
     "isNull": "",
     "isDlpPolicy": "",
     "isAnomalyDetection": "",
     "threatPreventionPolicyName": "",
     "urlfilteringPolicyName": "",
     "urlfilteringPolicyId": ""
}

operation: Update Security Policy

Input parameters

Parameter Description
Security Policy ID ID of the security policy that you want to update in ShieldX.
Security Policy Name (Optional) Name of the security policy that you want to update in ShieldX.
Is Anomaly Detection (Optional) Select "True" to enable anomaly detection.
Is DLP Policy (Optional) Select "True" to enable enhanced IOP functionality.
Malware Policy ID (Optional) Identifier of the malware policy assigned to SPS.
Malware Policy Name (Optional) Name of the malware policy assigned to SPS. When SPS is fetched, the helper field provides the name of the malware policy.
Tenant ID (Optional) Identifier value of an infrastructure tenant.
Threat Prevention Policy ID (Optional) Identifier of threat prevention policy assigned to SPS.
Threat Prevention Policy Name (Optional) Name of the threat prevention policy assigned to SPS. When SPS is fetched, the helper field provides the name of the threat prevention policy.
URL Filtering Policy ID (Optional) Identifier of URL Filtering policy assigned to SPS.
URL Filtering Policy Name (Optional) Name of the URL filtering policy assigned to SPS. When SPS is fetched, the helper field provides the name of the URL filtering policy.
Last Modified (Optional) Date when the security policy was last modified.

Output

The output contains a non-dictionary value.

operation: Assign Tag

Input parameters

Parameter Description
Infrastructure ID ID of the infrastructure, workload or network, to which you want to assign a tag.
VM ID VM ID of the target or attacker to which you want to assign a tag. You can retrieve the targetVmId or attackerVmId from the result of the "Fetch Threat Events" operation.
Type Type of infrastructure, WORKLOAD or NETWORK, to which you want to assign a tag.
Tags Tag name(s) that you want to assign to the specified VM. This parameter makes an API call named "list_workload_tag" to dynamically populate the Tags drop-down selections. 

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

operation: Unassign Tag

Input parameters

Parameter Description
Infrastructure ID ID of the infrastructure, workload or network, whose tag you want to unassign.
VM ID VM ID of the target or attacker whose tag you want to unassign. You can retrieve the targetVmId or attackerVmId from the result of the "Fetch Threat Events" operation.
Infrastructure Type Type of infrastructure, WORKLOAD or NETWORK, whose tag you want to unassign.
Tags Tag name(s) that you want to unassign from the specified VM. This parameter makes an API call named "list_workload_tag" to dynamically populate the Tags drop-down selections.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

Included playbooks

The Sample - ShieldX - 1.0.0 playbook collection comes bundled with the ShieldX connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the ShieldX connector.

  • Assign Tag
  • Create Tag
  • Fetch Threat Events
  • Get Tags
  • Get Workload Details
  • List Infrastructure
  • List Security Policies
  • List Workloads
  • > ShieldX > Fetch
  • >> ShieldX > Handle Macro
  • > ShieldX > Ingest
  • Unassign Tag
  • Update Security Policy

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling threat events (shieldxalerts or shieldxsecurityevents) from ShieldX. Currently, "shieldxalerts" or "shieldxsecurityevents" in ShieldX are mapped to "alerts" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.

Configure Data Ingestion

You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming ShieldX "Alerts" (shieldxalerts) or "Events" (shieldxsecurityevents) to FortiSOAR™ "Alerts".

The Data Ingestion Wizard enables you to configure scheduled pulling of data from ShieldX into FortiSOAR™. It also lets you pull some sample data from ShieldX using which you can define the mapping of data between ShieldX and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users mostly require to only map any custom fields that are added to the ShieldX alert. 

  1. To begin configuring data ingestion, click Configure Data Ingestion on the ShieldX connector’s "Configurations" page. 
    Click Let’s Start by fetching some data, to open the “Fetch Sample Data” screen.

    Sample data is required to create a field mapping between ShieldX data and FortiSOAR™. The sample data is pulled from connector actions or ingestion playbooks.
  2. On the Fetch Data screen, provide the configurations required to fetch ShieldX data.
    Users can choose to pull data from ShieldX by specifying the Threat Index Type, which could either be Alerts (shieldxalerts) or Events (shieldxsecurityevents) using which you want to pull data from ShieldX. You can also specify additional parameters such as the start datetime from when you want to pull data from ShieldX and the maximum number of records to be pulled from ShieldX. The pulled data is used to create a mapping between the ShieldX data and FortiSOAR™ alerts.

    Once you have completed specifying the configurations, click Fetch Data.
  3. On the Field Mapping screen, map the fields of a threat event (shieldxalerts or shieldxsecurityevents) to the fields of an alert present in FortiSOAR™. 
    To map a field, click the key in the sample data to add the “jinja” value of the field. For example, to map the threatname parameter of a ShieldX event to the Name parameter of a FortiSOAR™ alert, click the Name field and then click the threatname field to populate its keys:  

    For more information on field mapping, see the Data Ingestion chapter in the "Connectors Guide" in the FortiSOAR™ product documentation. Once you have completed mapping fields, click Save Mapping & Continue.

  4. Use the Scheduling screen to configure schedule-based ingestion, i.e., specify the polling frequency to ShieldX, so that the content gets pulled from the ShieldX integration into FortiSOAR™. 
    On the Scheduling screen, from the Do you want to schedule the ingestion? drop-down list, select Yes.    
    In the “Configure Schedule Settings” section, specify the Cron expression for the schedule. For example, if you want to pull data from ShieldX every 5 minutes, click Every X Minute and in the minute box enter */5. This would mean that based on the configuration you have set up, data, i.e., alerts or events will be pulled from ShieldX every 5 minutes.

    Once you have completed scheduling, click Save Settings & Continue.

  5. The Summary screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks. Click Done to complete the data ingestion and exit the Data Ingestion Wizard.

About the connector

ShieldX provides comprehensive, automated, and consistent network security, which is synchronized with changes in multi-cloud environments.

This document provides information about the ShieldX connector, which facilitates automated interactions with the ShieldX console using FortiSOAR™ playbooks. Add the ShieldX connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating a workload or network tag for group-based tagging operations, retrieving a list of tags, pulling events that match a threat signature, etc.

You can use FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling threat events (shieldxalerts or shieldxsecurityevents) from ShieldX. For more information, see the Data Ingestion Support section.

Version information

Connector Version: 2.0.0

FortiSOAR™ Version Tested on: 6.4.1-2133

ShieldX Version Tested on:2.1.952

Authored By: Fortinet

Certified: Yes

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:

yum install cyops-connector-shieldx

Prerequisites to configuring the connector

Permissions Required

The ShieldX connector and perform the automated operations, you must be assigned the "SuperUser" role.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the ShieldX connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Server URL IP address of ShieldX management console to which you will connect and perform the automated operations.
Username Username to access the ShieldX management console to which you will connect and perform the automated operations.
Password Password to access the ShieldX management console to which you will connect and perform the automated operations.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from version 4.10.0 and onwards:

Function Description Annotation and Category
Create Tag Creates a workload or network tag for group-based tagging operations in ShieldX based on the tag name and its key and value you have specified.  create_tag
Investigation
Get Tags Retrieves a list of tags from ShieldX or details of a specific tag from ShieldX based on the tag ID you have specified. get_tag
Investigation
Fetch Threat Events Pulls threat events matching a threat signature from ShieldX based on the index type, record count, and other input parameters you have specified. The threat events contain the attacker details (source of attack) and the target details (destination of attack) and other relevant details. search_events_by_index
Investigation
List Infrastructure

Retrieves a list of all infrastructure access configurations from ShieldX or details of a specific infrastructure access configuration from ShieldX based on the infrastructure ID you have specified.

list_infrastructure
Investigation
List Workloads

Retrieves a list of all ShieldX workloads from ShieldX or details of a specific workload from ShieldX based on the cloud infrastructure ID you have specified.

list_workloads
Investigation
Get Workload Details Retrieves details of a ShieldX workload based on the workload ID you have specified. workloads_details
Investigation
List Security Policies

Retrieves a list of all security policy sets from ShieldX or details of a specific security policy set from ShieldX based on the security policy set ID you have specified.

list_security_policy
Investigation
Update Security Policy Updates a specific security policy set in ShieldX based on the security policy ID and other input parameters you have specified. update_security_policy
Investigation
Assign Tag Assigns a tag to a workload or network ID in ShieldX based on the infrastructure ID, VM ID, tags, etc you have specified. assign_tag
Investigation
Unassign Tag Unassigns a workload or network that was tagged for quarantine purposes in ShieldX based on the infrastructure ID, VM ID, tags, etc you have specified. unassign_tag
Investigation
Get Tag List Get available ShieldX tag key:value list. list_tag
Investigation
Get List of Workload Tag Retrieves available ShieldX tag list. list_tag
Investigation

operation: Create Tag

Input parameters

Parameter Description
Tag Name Name of the tag that you want to create in ShieldX.
Tag Key Key of the tag such as. "Application" that you want to create in ShieldX.
Tag Value Value of the tag such as, "Accounting" that you want to create in ShieldX.

Output

The output contains the following populated JSON schema:
{
     "tag_id": ""
}

operation: Get Tags

Input parameters

Parameter Description
Tag ID ID of the tag whose details you want to retrieve from ShieldX.
Note: If you do not specify the tag ID, then this operation retrieves a list of all tags from ShieldX.

Output

The output contains the following populated JSON schema:

Output schema when the tag ID is not specified, i.e., {{id === ''}}:
[
     {
         "name": "",
         "key": "",
         "id": "",
         "lastModified": "",
         "value": ""
     }
]

Output schema when the tag ID is specified:
{
     "name": "",
     "key": "",
     "id": "",
     "lastModified": "",
     "value": ""
}

operation: Fetch Threat Events

Input parameters

Parameter Description
Index Type Type of index based on which you want to fetch threat events from ShieldX. You can choose between Alerts or Events.
  • Alerts: Looks up the shieldxalerts index that holds threat events. This index contains threat detection security events, including Malware and Indicator of Pivot (IoP) (east-west detection correlated with north-south) events.
  • Events: Looks up the shieldxsecurityevents security event types such as Threats, App detections, Malware, IoP, and ACL events.
Record Count (Optional) Maximum number of records that this operation should fetch from ShieldX. The maximum number of records that can be fetched per query is 10,000.
Note: If you do not specify the record count, then by default this operation fetches 10 records.
Sort By (Optional) Sorts the results retrieved from ShieldX based on the fields (dimensions) that you have specified. This query sorts on two dimensions – Timestamp in an ascending or descending order (oldest events first) and on ID, which is the index for each record in the database.
Sort Order (Optional) Order to sort the results retrieved from ShieldX. You can choose between Ascending or Descending.
Offset (Optional) 0-based index of the page that this operation should return. This indicates the ID from which the next 10,000 records should be fetched, in case of pagination. This is useful only if more than 10k threats are returned in a 30 seconds window, which is highly unlikely.
Search After (Optional) Search after element to be passed when a non-zero management timestamp is available from a previous query result set with the maximum management timestamp and _id returned from the previous query. eg. [1597627505280,"HxwF-nMBk8PLPApZGruC"]
Start Time (Optional) Start datetime from when you want to retrieve threat events from ShieldX.
End Time (Optional) End datetime till when you want to retrieve threat events from ShieldX.

Output

The output contains the following populated JSON schema:
{
     "responses": [
         {
             "timed_out": "",
             "status": "",
             "took": "",
             "hits": {
                 "total": "",
                 "hits": [
                     {
                         "sort": [],
                         "_score": "",
                         "_index": "",
                         "_source": {
                             "microServiceInstanceId": "",
                             "mgmtTimeStamp": "",
                             "chassisId": "",
                             "timeStamp": "",
                             "tenantId": "",
                             "version": "",
                             "dataPlane": "",
                             "microServiceType": "",
                             "event": {
                                 "endPacketId": "",
                                 "attackerIp": "",
                                 "attackerResourceGroup": "",
                                 "targetIp": "",
                                 "appId": "",
                                 "protocol": "",
                                 "pmId": "",
                                 "srcResourceGroup": "",
                                 "cveId": "",
                                 "policyId": "",
                                 "targetVmId": "",
                                 "threatName": "",
                                 "span": "",
                                 "packetId": "",
                                 "severityLevel": "",
                                 "target": "",
                                 "attackerVmId": "",
                                 "srcIpAddress": "",
                                 "dstPort": "",
                                 "srcContextId": "",
                                 "srcPort": "",
                                 "targetResourceGroup": "",
                                 "severity": "",
                                 "targetVmName": "",
                                 "cveYear": "",
                                 "attackPacketId": "",
                                 "attackerNetworkId": "",
                                 "attackerVmName": "",
                                 "policyName": "",
                                 "sensorResponse": "",
                                 "policyResponse": "",
                                 "transactionId": "",
                                 "policyType": "",
                                 "securityPolicySetName": "",
                                 "dstIpAddress": "",
                                 "eventType": "",
                                 "protocolName": "",
                                 "dstResourceGroup": "",
                                 "dstContextId": "",
                                 "managementResponse": "",
                                 "targetNetwork": "",
                                 "targetNetworkId": "",
                                 "attacker": "",
                                 "direction": "",
                                 "startPacketId": "",
                                 "flowCookie": "",
                                 "actionTkn": "",
                                 "attackerNetwork": ""
                             },
                             "microServiceTypeString": "",
                             "doctype": "",
                             "microServiceName": ""
                         },
                         "_id": "",
                         "_type": "",
                         "_routing": ""
                     }
                 ],
                 "max_score": ""
             },
             "_shards": {
                 "skipped": "",
                 "total": "",
                 "failed": "",
                 "successful": ""
             }
         }
     ]
}

operation: List Infrastructure

Input parameters

Parameter Description
Infrastructure ID

ID of the infrastructure access configuration whose details you want to retrieve from ShieldX.
Note: If you do not specify the infrastructure access configuration ID, then this operation retrieves a list of all infrastructure access configurations from ShieldX.

Output

The output contains the following populated JSON schema:

Output schema when the infrastructure ID is not specified, i.e., {{InfraId === ''}}:
[
     {
         "id": "",
         "name": "",
         "ip": "",
         "username": "",
         "password": "",
         "type": "",
         "domain": "",
         "https": "",
         "accessKeyId": "",
         "secretAccessKey": "",
         "clientId": "",
         "clientSecretKey": "",
         "subscription": "",
         "lastJobId": "",
         "hostClusterNameMapping": "",
         "aclPolicyId": "",
         "lastModified": ""
     }
]

Output schema when the infrastructure ID is specified
{
     "id": "",
     "name": "",
     "ip": "",
     "username": "",
     "password": "",
     "type": "",
     "domain": "",
     "accessKeyId": "",
     "secretAccessKey": "",
     "lastJobId": "",
     "clientId": "",
     "aclPolicyId": "",
     "lastModified": "",
     "subscription": "",
     "clientSecretKey": "",
     "hostClusterNameMapping": null
}

operation: List Workloads

Input parameters

Parameter Description
Infrastructure ID Cloud infrastructure ID whose workload details you want to retrieve from ShieldX.
Note: If you do not specify the cloud infrastructure ID, then this operation retrieves a list of all workloads from ShieldX.

Output

The output contains the following populated JSON schema:
{
     "workloadMap": {},
     "attributesFound": "",
     "workloads": [
         {
             "environment": "",
             "tenantId": "",
             "dataRiskCount": "",
             "tags": [],
             "name": "",
             "ports": [
                 {
                     "macAddress": "",
                     "vmId": "",
                     "networkId": "",
                    "ipAddresses": [],
                     "isSegmented": ""
                 }
             ],
             "nativeTags": [],
             "id": "",
             "attackCount": "",
             "cloudId": ""
         }
     ]
}

operation: Get Workload Details

Input parameters

Parameter Description
Workload ID ID of the workload whose details you want to retrieve from ShieldX.
Note: You can retrieve the workload ID using the "Fetch Threat Events" or "List Workloads" operations.

Output

The output contains the following populated JSON schema:
{
     "ports": [
         {
             "vmId": "",
             "networkId": "",
             "networkName": "",
             "macAddress": "",
             "ipAddresses": [],
             "isSegmented": ""
         }
     ],
     "environment": "",
     "id": "",
     "name": "",
     "attackCount": "",
     "tenantName": "",
     "dataRiskCount": "",
     "cloudType": "",
     "cloudId": "",
     "tenantId": "",
     "cloudName": "",
     "tags": [
         {
             "id": "",
             "key": "",
             "name": "",
             "value": "",
             "lastModified": ""
         }
     ],
     "nativeTags": []
}

operation: List Security Policies

Input parameters

Parameter Description
Security Policy Set ID ID of the security policy set whose details you want to retrieve from ShieldX.
Note: If you do not specify the security policy set ID, then this operation retrieves a list of all security policy sets from ShieldX.

Output

The output contains the following populated JSON schema:

Output schema when the security policy set ID is not specified, i.e., {{id === ''}}:
[
     {
         "malwarePolicyName": "",
         "lastModified": "",
         "malwarePolicyId": "",
         "id": "",
         "threatPreventionPolicyId": "",
         "name": "",
         "uServices": [],
         "isEditable": "",
         "tenantId": "",
         "isNull": "",
         "isDlpPolicy": "",
         "isAnomalyDetection": "",
         "threatPreventionPolicyName": "",
         "urlfilteringPolicyName": "",
         "urlfilteringPolicyId": ""
     }
]

Output schema when the security policy set ID is specified:
{
     "malwarePolicyName": "",
     "lastModified": "",
     "malwarePolicyId": "",
     "id": "",
     "threatPreventionPolicyId": "",
     "name": "",
     "uServices": [],
     "isEditable": "",
     "tenantId": "",
     "isNull": "",
     "isDlpPolicy": "",
     "isAnomalyDetection": "",
     "threatPreventionPolicyName": "",
     "urlfilteringPolicyName": "",
     "urlfilteringPolicyId": ""
}

operation: Update Security Policy

Input parameters

Parameter Description
Security Policy ID ID of the security policy that you want to update in ShieldX.
Security Policy Name (Optional) Name of the security policy that you want to update in ShieldX.
Is Anomaly Detection (Optional) Select "True" to enable anomaly detection.
Is DLP Policy (Optional) Select "True" to enable enhanced IOP functionality.
Malware Policy ID (Optional) Identifier of the malware policy assigned to SPS.
Malware Policy Name (Optional) Name of the malware policy assigned to SPS. When SPS is fetched, the helper field provides the name of the malware policy.
Tenant ID (Optional) Identifier value of an infrastructure tenant.
Threat Prevention Policy ID (Optional) Identifier of threat prevention policy assigned to SPS.
Threat Prevention Policy Name (Optional) Name of the threat prevention policy assigned to SPS. When SPS is fetched, the helper field provides the name of the threat prevention policy.
URL Filtering Policy ID (Optional) Identifier of URL Filtering policy assigned to SPS.
URL Filtering Policy Name (Optional) Name of the URL filtering policy assigned to SPS. When SPS is fetched, the helper field provides the name of the URL filtering policy.
Last Modified (Optional) Date when the security policy was last modified.

Output

The output contains a non-dictionary value.

operation: Assign Tag

Input parameters

Parameter Description
Infrastructure ID ID of the infrastructure, workload or network, to which you want to assign a tag.
VM ID VM ID of the target or attacker to which you want to assign a tag. You can retrieve the targetVmId or attackerVmId from the result of the "Fetch Threat Events" operation.
Type Type of infrastructure, WORKLOAD or NETWORK, to which you want to assign a tag.
Tags Tag name(s) that you want to assign to the specified VM. This parameter makes an API call named "list_workload_tag" to dynamically populate the Tags drop-down selections. 

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

operation: Unassign Tag

Input parameters

Parameter Description
Infrastructure ID ID of the infrastructure, workload or network, whose tag you want to unassign.
VM ID VM ID of the target or attacker whose tag you want to unassign. You can retrieve the targetVmId or attackerVmId from the result of the "Fetch Threat Events" operation.
Infrastructure Type Type of infrastructure, WORKLOAD or NETWORK, whose tag you want to unassign.
Tags Tag name(s) that you want to unassign from the specified VM. This parameter makes an API call named "list_workload_tag" to dynamically populate the Tags drop-down selections.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

Included playbooks

The Sample - ShieldX - 1.0.0 playbook collection comes bundled with the ShieldX connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the ShieldX connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling threat events (shieldxalerts or shieldxsecurityevents) from ShieldX. Currently, "shieldxalerts" or "shieldxsecurityevents" in ShieldX are mapped to "alerts" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.

Configure Data Ingestion

You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming ShieldX "Alerts" (shieldxalerts) or "Events" (shieldxsecurityevents) to FortiSOAR™ "Alerts".

The Data Ingestion Wizard enables you to configure scheduled pulling of data from ShieldX into FortiSOAR™. It also lets you pull some sample data from ShieldX using which you can define the mapping of data between ShieldX and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users mostly require to only map any custom fields that are added to the ShieldX alert. 

  1. To begin configuring data ingestion, click Configure Data Ingestion on the ShieldX connector’s "Configurations" page. 
    Click Let’s Start by fetching some data, to open the “Fetch Sample Data” screen.

    Sample data is required to create a field mapping between ShieldX data and FortiSOAR™. The sample data is pulled from connector actions or ingestion playbooks.
  2. On the Fetch Data screen, provide the configurations required to fetch ShieldX data.
    Users can choose to pull data from ShieldX by specifying the Threat Index Type, which could either be Alerts (shieldxalerts) or Events (shieldxsecurityevents) using which you want to pull data from ShieldX. You can also specify additional parameters such as the start datetime from when you want to pull data from ShieldX and the maximum number of records to be pulled from ShieldX. The pulled data is used to create a mapping between the ShieldX data and FortiSOAR™ alerts.

    Once you have completed specifying the configurations, click Fetch Data.
  3. On the Field Mapping screen, map the fields of a threat event (shieldxalerts or shieldxsecurityevents) to the fields of an alert present in FortiSOAR™. 
    To map a field, click the key in the sample data to add the “jinja” value of the field. For example, to map the threatname parameter of a ShieldX event to the Name parameter of a FortiSOAR™ alert, click the Name field and then click the threatname field to populate its keys:  

    For more information on field mapping, see the Data Ingestion chapter in the "Connectors Guide" in the FortiSOAR™ product documentation. Once you have completed mapping fields, click Save Mapping & Continue.

  4. Use the Scheduling screen to configure schedule-based ingestion, i.e., specify the polling frequency to ShieldX, so that the content gets pulled from the ShieldX integration into FortiSOAR™. 
    On the Scheduling screen, from the Do you want to schedule the ingestion? drop-down list, select Yes.    
    In the “Configure Schedule Settings” section, specify the Cron expression for the schedule. For example, if you want to pull data from ShieldX every 5 minutes, click Every X Minute and in the minute box enter */5. This would mean that based on the configuration you have set up, data, i.e., alerts or events will be pulled from ShieldX every 5 minutes.

    Once you have completed scheduling, click Save Settings & Continue.

  5. The Summary screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks. Click Done to complete the data ingestion and exit the Data Ingestion Wizard.