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: 1.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.
- 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.
- 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.
-
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.
-
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.
-
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.
