About the connector
FireEye HX brings advanced protection to endpoints. Its comprehensive endpoint visibility and threat intelligence enables analysts to adapt their defense based on real-time details to deploy informed, tailored responses to threat activity.
This document provides information about the FireEye HX connector, which facilitates automated interactions with the FireEye HX server using FortiSOAR™ playbooks. Add the FireEye HX connector as a step in FortiSOAR™ playbooks and perform automated operations such as containing hosts, releasing hosts from containment, and listing alerts from FireEye HX.
Version information
Connector Version: 1.0.0
FortiSOAR™ Version Tested on: 4.12.0-746
Authored By: Fortinet
Certified: Yes
Installing the connector
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:
yum install cyops-connector-fireeye-hx
For the detailed procedure to install a connector, click here
Prerequisites to configuring the connector
- You must have the URL of FireEye HX server to which you will connect and perform automated operations and credentials (username-password pair) to access that server.
- To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
Configuring the connector
For the procedure to configure a connector, click here
Configuration parameters
In FortiSOAR™, on the connectors page, select the FireEye HX connector row, and in the Configure tab enter the required configuration details.
| Parameter |
Description |
| Host URL |
URL of the FireEye HX server to which you will connect and perform automated operations. |
| Port |
Port number used for connecting to the FireEye HX server. |
| Username |
Username to access the FireEye HX server to which you will connect and perform automated operations. |
| Password |
Password to access the FireEye HX server to which you will connect and perform automated operations. |
| Verify SSL |
(Optional) Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
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 FortiSOAR™ release 4.10.0 onwards:
| Function |
Description |
Annotation and Category |
| Contain a Host as an Admin |
Requests and approves a host for containment on FireEye HX, based on the agent ID you have specified. This action can be performed only by the user with administrator permissions. |
full_containment
Containment |
| Create a File Acquisition for a Host |
Specifies a file to be acquired from a host for investigation on FireEye HX, based on the agent ID and other input parameters you have specified. |
new_file_acquisition
Investigation |
| Create a Triage Acquisition for a Host |
Launches a triage operation on a host on FireEye HX, based on the agent ID you have specified. |
new_triage_acquisition
Investigation |
| Request Host Containment |
Submits a request to contain a host on FireEye HX, based on the agent ID you have specified. This request has to be approved by a user with administrator permissions. |
request_containment
Containment |
| Get Host |
Fetches the summary information about an agent ID on the host on FireEye HX, based on the agent ID you have specified. |
get_host
Investigation |
| Get File Acquisition Information |
Fetches the details of a file acquisition, including its status, from FireEye HX, based on the acquisition ID you have specified. |
get_file_acquisition_status
Investigation |
| Fetch a File Acquisition Package |
Fetches the output of a file acquisition request in the .zip format from FireEye HX, based on the acquisition ID you have specified. This action also creates an attachment of the acquired file in FortiSOAR™, i.e, the acquired file is added to the Attachment module in FortiSOAR™. |
get_file_acquisition_package
Investigation |
| Get Triage Acquisition Information |
Fetches the details of a triage acquisition, including its status, from FireEye HX, based on the triage ID you have specified. |
get_triage_acquisition_status
Investigation |
| Fetch a Triage Collection |
Fetches the output of a triage acquisition request in the .mans format from FireEye HX, based on the triage ID you have specified. |
get_triage_collection
Investigation |
| List Alerts |
Fetches the list of first 50 alerts on all hosts, starting with the number that you have specified in the offset input parameter from FireEye HX. |
list_alerts
Investigation |
| List Hosts |
Fetches a list of all hosts from FireEye HX. You can optionally filter the list of hosts by the presence of alerts. |
list_hosts
Investigation |
| List Triage Acquisitions |
Fetches a list of triage acquisitions on all hosts from FireEye HX. You can optionally filter the list of hosts by based on any field you specify. |
list_triage_acquisitions
Investigation |
| Approve Host Containment |
Approves a host for containment on FireEye HX, based on the agent ID you have specified. The approval can be provided by the user with administrator permissions only. |
approve_containment
Containment |
| Release Host from Containment |
Releases a contained host from containment on FireEye HX, based on the agent ID you have specified. |
release_containment
Containment |
operation: Contain a Host as an Admin
Input parameters
| Parameter |
Description |
| Agent ID |
Agent ID of the target host that you want to contain on FireEye HX. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"route": "",
"details": []
}
operation: Create a File Acquisition for a Host
Input parameters
| Parameter |
Description |
| Agent ID |
Agent ID of the target host. |
| File Path |
Path to the file to be acquired on the host. |
| File Name |
Name of the file to be acquired at the specified path. |
| External Id |
(Optional) External correlation ID, if applicable. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"data": {
"host": {
"url": "",
"_id": ""
},
"zip_passphrase": "",
"comment": "",
"request_time": "",
"url": "",
"_id": "",
"request_actor": {
"_id": "",
"username": ""
},
"req_filename": "",
"external_id": "",
"state": "",
"error_message": "",
"finish_time": "",
"md5": "",
"req_use_api": "",
"req_path": "",
"alert": {
"url": "",
"_id": ""
},
"_revision": "",
"indicator": {
"url": "",
"_id": ""
},
"condition": {
"url": "",
"_id": ""
}
},
"route": "",
"details": []
}
operation: Create a Triage Acquisition for a Host
Input parameters
| Parameter |
Description |
| Agent ID |
Agent ID of the target host for which you want to create a triage acquisition on FireEye HX. |
| External Id |
(Optional) External correlation ID, if applicable. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"data": {
"condition": {
"url": "",
"_id": ""
},
"request_time": "",
"host": {
"url": "",
"_id": ""
},
"_id": "",
"request_actor": {
"_id": "",
"username": ""
},
"external_id": "",
"state": "",
"error_message": "",
"finish_time": "",
"md5": "",
"req_timestamp": "",
"alert": {
"url": "",
"_id": ""
},
"_revision": "",
"indicator": {
"url": "",
"_id": ""
},
"url": ""
},
"route": "",
"details": []
}
operation: Request Host Containment
Input parameters
| Parameter |
Description |
| Agent ID |
Agent ID of the target host on which you want to request a host containment on FireEye HX. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"route": "",
"details": []
}
operation: Get Host
Input parameters
| Parameter |
Description |
| Agent ID |
Agent ID of the target host whose summary information you want to retrieve from FireEye HX. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"data": {
"last_exploit_block": "",
"last_alert_timestamp": "",
"last_alert": "",
"sysinfo": {
"url": ""
},
"containment_missing_software": "",
"_id": "",
"last_audit_timestamp": "",
"domain": "",
"timezone": "",
"hostname": "",
"last_exploit_block_timestamp": "",
"reported_clone": "",
"os": {
"bitness": "",
"kernel_version": "",
"platform": "",
"patch_level": "",
"product_name": ""
},
"containment_state": "",
"primary_mac": "",
"primary_ip_address": "",
"gmt_offset_seconds": "",
"last_poll_timestamp": "",
"url": "",
"stats": {
"exploit_alerts": "",
"exploit_blocks": "",
"alerting_conditions": "",
"alerts": "",
"malware_alerts": "",
"acqs": ""
},
"agent_version": "",
"last_poll_ip": "",
"excluded_from_containment": "",
"initial_agent_checkin": ""
},
"route": "",
"details": []
}
operation: Get File Acquisition Information
Input parameters
| Parameter |
Description |
| Acquisition ID |
Acquisition ID of the target file whose file acquisition information you want to retrieve from FireEye HX. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"data": {
"host": {
"url": "",
"_id": ""
},
"zip_passphrase": "",
"comment": "",
"request_time": "",
"url": "",
"_id": "",
"request_actor": {
"_id": "",
"username": ""
},
"req_filename": "",
"external_id": "",
"state": "",
"error_message": "",
"finish_time": "",
"md5": "",
"req_use_api": "",
"req_path": "",
"alert": {
"url": "",
"_id": ""
},
"_revision": "",
"indicator": {
"url": "",
"_id": ""
},
"condition": {
"url": "",
"_id": ""
}
},
"route": "",
"details": []
}
operation: Fetch a File Acquisition Package
Input parameters
| Parameter |
Description |
| Acquisition ID |
ID of the target file acquisition request for which you want to retrieve output from FireEye HX.
This operation also creates an attachment of the acquired file in FortiSOAR™, i.e, the acquired file is added to the Attachment module in FortiSOAR™. |
Output
The output contains the following populated JSON schema:
{
"filepath": ""
}
operation: Get Triage Acquisition Information
Input parameters
| Parameter |
Description |
| Triage ID |
ID of the target triage acquisition whose details you want to retrieve from FireEye HX. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"data": {
"condition": {
"url": "",
"_id": ""
},
"request_time": "",
"host": {
"url": "",
"_id": ""
},
"_id": "",
"request_actor": {
"_id": "",
"username": ""
},
"external_id": "",
"state": "",
"error_message": "",
"finish_time": "",
"md5": "",
"req_timestamp": "",
"alert": {
"url": "",
"_id": ""
},
"_revision": "",
"indicator": {
"url": "",
"_id": ""
},
"url": ""
},
"route": "",
"details": []
}
operation: Fetch a Triage Collection
Input parameters
| Parameter |
Description |
| Triage ID |
ID of the target triage acquisition request for which you want to retrieve output from FireEye HX. |
Output
The output contains the following populated JSON schema:
{
"filepath": ""
}
operation: List Alerts
Input parameters
| Parameter |
Description |
| Offset |
Index (number) of the first item (alert) that this operation should return. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"data": {
"entries": [
{
"condition": {
"url": "",
"_id": ""
},
"request_time": "",
"host": {
"url": "",
"_id": ""
},
"_id": "",
"request_actor": {
"_id": "",
"username": ""
},
"external_id": "",
"state": "",
"error_message": "",
"finish_time": "",
"md5": "",
"req_timestamp": "",
"alert": {
"url": "",
"_id": ""
},
"_revision": "",
"indicator": {
"url": "",
"_id": ""
},
"url": ""
},
{
"condition": {
"url": "",
"_id": ""
},
"request_time": "",
"host": {
"url": "",
"_id": ""
},
"_id": "",
"request_actor": {
"_id": "",
"username": ""
},
"external_id": "",
"state": "",
"error_message": "",
"finish_time": "",
"md5": "",
"req_timestamp": "",
"alert": {
"url": "",
"_id": ""
},
"_revision": "",
"indicator": {
"url": "",
"_id": ""
},
"url": ""
}
],
"limit": "",
"offset": "",
"sort": {},
"query": {},
"total": ""
},
"route": "",
"details": []
}
operation: List Hosts
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list (of hosts) is returned.
| Parameter |
Description |
| Filter |
Filters the list of hosts retrieved from FireEye HX by the presence of alerts, or by the presence of active alerts for matching hosts. |
| Search Term |
Searches all hosts connected to the specified FireEye HX appliance based on the Search Term you have specified. The Search Term can be any hostname, IP address, or an agent ID. |
| Offset |
Index (number) of the first item (host) that this operation should return. |
Output
The output contains the following populated JSON schema:
{
"data": {
"entries": [
{
"last_exploit_block": "",
"last_alert_timestamp": "",
"last_alert": "",
"sysinfo": {
"url": ""
},
"containment_missing_software": "",
"_id": "",
"last_audit_timestamp": "",
"domain": "",
"timezone": "",
"hostname": "",
"last_exploit_block_timestamp": "",
"reported_clone": "",
"os": {
"bitness": "",
"kernel_version": "",
"platform": "",
"patch_level": "",
"product_name": ""
},
"containment_state": "",
"primary_mac": "",
"primary_ip_address": "",
"gmt_offset_seconds": "",
"last_poll_timestamp": "",
"url": "",
"stats": {
"exploit_alerts": "",
"exploit_blocks": "",
"alerting_conditions": "",
"alerts": "",
"malware_alerts": "",
"acqs": ""
},
"agent_version": "",
"last_poll_ip": "",
"excluded_from_containment": "",
"initial_agent_checkin": ""
}
],
"limit": "",
"offset": "",
"sort": "",
"query": "",
"total": ""
}
}
operation: List Triage Acquisitions
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list (of triage acquisitions) is returned.
| Parameter |
Description |
| Filter Field |
Name of the field based on which you want to filter the list of triage acquisitions retrieved from FireEye HX. |
| Filter Value |
Value of the field specified based on which you want to filter the list of triage acquisitions retrieved from FireEye HX. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"data": {
"entries": [
{
"host": {
"url": "",
"_id": ""
},
"zip_passphrase": "",
"comment": "",
"request_time": "",
"url": "",
"_id": "",
"request_actor": {
"_id": "",
"username": ""
},
"req_filename": "",
"external_id": "",
"state": "",
"error_message": "",
"finish_time": "",
"md5": "",
"req_use_api": "",
"req_path": "",
"alert": {
"url": "",
"_id": ""
},
"_revision": "",
"indicator": {
"url": "",
"_id": ""
},
"condition": {
"url": "",
"_id": ""
}
},
{
"host": {
"url": "",
"_id": ""
},
"zip_passphrase": "",
"comment": "",
"request_time": "",
"url": "",
"_id": "",
"request_actor": {
"_id": "",
"username": ""
},
"req_filename": "",
"external_id": "",
"state": "",
"error_message": "",
"finish_time": "",
"md5": "",
"req_use_api": "",
"req_path": "",
"alert": {
"url": "",
"_id": ""
},
"_revision": "",
"indicator": {
"url": "",
"_id": ""
},
"condition": {
"url": "",
"_id": ""
}
}
],
"limit": "",
"offset": "",
"sort": {},
"query": {},
"total": ""
},
"route": "",
"details": []
}
operation: Approve Host Containment
Input parameters
| Parameter |
Description |
| Agent ID |
Agent ID of the target host whose containment you want to approve on FireEye HX. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"route": "",
"details": []
}
operation: Release Host from Containment
Input parameters
| Parameter |
Description |
| Agent ID |
Agent ID of the target host that you want to release from containment on FireEye HX. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"route": "",
"details": []
}
Included playbooks
The Sample - FireEye-HX- 1.0.0 playbook collection comes bundled with the FireEye HX 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 FireEye HX connector.
- Approve Containment Request
- Check File Acquisition Status
- Check Triage Acquisition Status
- Contain Host
- Create File Acquisition
- Create Triage Acquisition
- Fetch a File Acquisition Package
- Fetch Triage Acquisition Collection
- Get Host
- List Alerts
- List Hosts
- List Triage Acquisitions
- Release Contained Host
- Submit Containment Request
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 connector upgrade and delete.
