Fortinet Document Library

Version:


Table of Contents

1.1.0
Copy Link

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.1.0

FortiSOAR™ Version Tested on: 6.0.0-790

Authored By: Fortinet.

Certified: Yes

Release Notes for version 1.1.0

Following enhancements have been made in the  FireEye HX connector in version 1.1.0:

  • Added the following actions and playbooks:
    • Get Quarantine List
    • Request Quarantined File Acquisition
    • Get Quarantine File Acquisition Information
    • Get Quarantine File
    • List All Scripts Details
    • Fetch a Script by ID
    • Get All Scripts
    • Data Acquisition using Script
    • List Host Data Acquisitions
    • Get Data Acquisition Status
    • Fetch a Data Acquisition Package
    • Parse Mandiant Analysis File

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 yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-fireeye-hx

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.
  • The minimum privileges that require to be assigned to users who are going to use this connector and run actions on FireEye HX must be assigned the role of "api_admin".

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 (if you are in the Grid view on the Connectors page) and in the Configurations 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
Get Quarantine List Retrieves the quarantine file list for a specific host from FireEye HX, based on the hostname you have specified. get_quarantine_list
Investigation
Request Quarantined File Acquisition Requests the acquisition of quarantined files into FireEye HX using the quarantine ID you have specified. request_acquisition
Investigation
Get Quarantine File Acquisition Information Retrieves details such as filename, filepath, MD, status, etc. about a file that is acquisition into FireEye HX based on the acquisition ID you have specified. get_acquisition_status
Investigation
Get Quarantine File Pulls quarantined files from FireEye HX based on the acquisition ID you have specified. fetch_acquisition
Investigation
List All Scripts Details Retrieves a list of all script details or specific script details from FireEye HX based on the input parameters you have specified. get_scripts
Investigation
Fetch a Script by ID Retrieves a specific script from FireEye HX in the XML format based on the script ID you have specified.
Note: This action also creates an attachment of the acquired file in FortiSOAR™, i.e, the acquired file is added in the "Attachment" module in FortiSOAR™.
fetch_script
Investigation
Get All Scripts Retrieves all available scripts from FireEye HX and adds it as ".zip" file in the "Attachment" module in FortiSOAR™. get_scripts
Investigation
Data Acquisition using Script Executes a custom data acquisition script using a predefined script ID or script on a specified host on FireEye HX based on the hostname, script name, an XML formatted data acquisition script, or script ID you have specified. request_acquisition
Investigation
List Host Data Acquisitions Retrieves a list of all data acquisitions for a specified host from FireEye HX based on the hostname and other input parameters you have specified. list_acquisitions
Investigation
Get Data Acquisition Status Retrieves details, including the status, of a data acquisition from FireEye HX based on the acquisition ID you have specified. get_acquisition_status
Investigation
Fetch a Data Acquisition Package Retrieves the output of a data acquisition request in the .mans format from FireEye HX based on the acquisition ID you have specified.
Note: This action also creates an attachment of the acquired file in FortiSOAR™, i.e, the acquired file is added in the "Attachment" module in FortiSOAR™.
fetch_acquisition
Investigation
Parse Mandiant Analysis File Parses a "Mandiant Analysis File" from the "Attachment" module in FortiSOAR™ based on the file attachment ID or IRI references you have specified. parse_mans_file
Investigation

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 from which you want to acquire the file for investigation on FireEye HX, 
File Path Path to the file to be acquired from the specified host for investigation on FireEye HX, 
File Name Name of the file to be acquired at the specified path for investigation on FireEye HX, 
External ID (Optional) External correlation ID, if applicable, of the file to be acquired for investigation on 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: 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 of the host for which you want to create a triage acquisition on 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: 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 whose output you want to retrieve 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": []
}

operation: Get Quarantine List

Input parameters

Parameter Description
Hostname Hostname whose quarantine file list you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "listing": [
         {
             "alert": {
                 "url": "",
                 "_id": ""
             },
             "hit_correlation_id": "",
             "file_md5": "",
             "_id": "",
             "file_path": "",
             "alert_infection_name": "",
             "quarantined_at": "",
             "state": "",
             "file_sha1": "",
             "reported_at": "",
             "agent_quarantine_id": "",
             "host": {
                 "url": "",
                 "_id": ""
             },
             "alert_file_creation_time": "",
             "update_time": "",
             "url": ""
         }
     ],
     "hostname": ""
}

operation: Request Quarantined File Acquisition

Input parameters

Parameter Description
Quarantine ID Quarantine ID of the target file for which you want to request acquisition into FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "quarantine_id": "",
     "route": "",
     "message": "",
     "details": [],
     "data": {
         "alert": {
             "url": "",
             "_id": ""
         },
         "agent_quarantine_id": "",
         "url": "",
         "_id": "",
         "host": {
             "url": "",
             "_id": ""
         },
         "state": ""
     }
}

operation: Get Quarantine File Acquisition Information

Input parameters

Parameter Description
Acquisition ID Acquisition request ID of the target file whose details such as filename, filepath, MD, status, etc. you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": {
         "route": "",
         "message": "",
         "details": [],
         "data": {
             "alert": {
                 "url": "",
                 "_id": ""
             },
             "agent_quarantine_id": "",
             "zip_passphrase": "",
             "_id": "",
             "request_time": "",
             "_revision": "",
             "host": {
                 "url": "",
                 "_id": ""
             },
             "state": "",
             "req_filename": "",
             "md5": "",
             "req_path": "",
             "comment": "",
             "error_message": "",
             "request_actor": {
                 "username": "",
                 "_id": ""
             },
             "url": ""
         }
     }
}

operation: Get Quarantine File

Input parameters

Parameter Description
Acquisition ID Acquisition ID of the quarantined file that you want to pull from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: List All Scripts Details

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 scripts) is returned.

Parameter Description
Search Term Searches all scripts on FireEye HX based on the search term. such as script ID, you have specified.
Search Offset Index (number) of the first item (scripts) that this operation should return.
Search Limit Specifies the number of records to fetch. It must be an unsigned 32-bit integer. By default, this is set as 50.
Sort By Sorts the results by the specified field in ascending or descending order. By default, sorting is done by "_id" in the ascending order.
Important: Currently sorting is only supported on the _id (script ID) parameter.
Filter By Retrieves only results that contain the specified field value from FireEye HX. For example, you can sort scripts by _id (script ID) and a filter such as, since='YYYY-MM-DDTHH:MM:SS.FFFZ', which will define the datetime from when you want to retrieve scripts from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": {
         "details": [],
         "message": "",
         "route": "",
         "data": {
             "sort": {},
             "total": "",
             "query": {},
             "offset": "",
             "entries": [
                 {
                     "last_used_at": "",
                     "download": "",
                     "url": "",
                     "_id": ""
                 }
             ],
             "limit": ""
         }
     }
}

operation: Fetch a Script by ID

Input parameters

Parameter Description
Script ID ID number of the targeted script that you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: Get All Scripts

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: Data Acquisition using Script

Input parameters

Parameter Description
Hostname Hostname, on FireEye HX on which you want to execute the custom data acquisition script and get the data acquisition.
xecutes a custom data acquisition script using a predefined script ID or script on a specified host on FireEye HX based on the hostname, script name and/or script ID you have specified.
Script Name Name of the script that you want to execute for the data acquisition on FireEye HX.
By Method Input type based on which the data acquisition script will be executed on FireEye HX.
If you choose By Script, then you must specify the following parameter:
  • Script: An XML formatted data acquisition script that you want to execute on the specified FireEye HX agent.
If you choose By Script ID, then you must specify the following parameter:
  • Script ID: A unique pre-existing data acquisition script ID, for example, f12aff009cb6e4c9f63d289d80fabb84162b6dff that you want to execute on the specified FireEye HX agent.

Output

The output contains the following populated JSON schema:
{
     "route": "",
     "message": "",
     "details": [],
     "data": {
         "script": {
             "download": "",
             "url": "",
             "_id": ""
         },
         "zip_passphrase": "",
         "_id": "",
         "host": {
             "url": "",
             "_id": ""
         },
         "name": "",
         "url": "",
         "state": "",
         "finish_time": "",
         "md5": "",
         "download": "",
         "_revision": "",
         "comment": "",
         "error_message": "",
         "request_time": "",
         "external_id": "",
         "request_actor": {
             "username": "",
             "_id": ""
         }
     }
}

operation: List Host Data Acquisitions

Input parameters

Parameter Description
Hostname Hostname for which you want to fetch a list of all data acquisitions from FireEye HX.
Search Offset Index (number) of the first item (data acquisition list) that this operation should return.
Search Limit Specifies the number of records to fetch. It must be an unsigned 32-bit integer. By default, this is set as 50.
Sort By Sorts the results by the specified field in ascending or descending order. You can sort fields by "_id" (host set ID) or "request_time" (time when the data acquisition was requested).
Filter Field Retrieves only results that contain the specified field value from FireEye HX. Available filters are: "host._id" (host set ID), "external_id" (external correlation ID from a SIEM solution), and "name" (script name)

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: Get Data Acquisition Status

Input parameters

Parameter Description
Acquisition ID Acquisition ID of the target data acquisition whose details including status you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "route": "",
     "message": "",
     "details": [],
     "data": {
         "script": {
             "download": "",
             "url": "",
             "_id": ""
         },
         "zip_passphrase": "",
         "_id": "",
         "host": {
             "url": "",
             "_id": ""
         },
         "name": "",
         "url": "",
         "state": "",
         "finish_time": "",
         "md5": "",
         "download": "",
         "_revision": "",
         "comment": "",
         "error_message": "",
         "request_time": "",
         "external_id": "",
         "request_actor": {
             "username": "",
             "_id": ""
         }
     }
}

operation: Fetch a Data Acquisition Package

Input parameters

Parameter Description
Acquisition ID Acquisition ID of the target data acquisition whose output of a data acquisition request you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: Parse Mandiant Analysis File

Input parameters

Parameter Description
File Attachment/IRI Reference ID of the file attachment or IRI reference of file attachment that is used to access the file directly from the FortiSOAR™ "Attachments" module. The file specified in this field will be used to perform this operation.

Output

The output contains a non-dictionary value.

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 Host Containment 
  • Contain a Host as an Admin
  • Create a File Acquisition for a Host
  • Create a Triage Acquisition for a Host
  • Data Acquisition using Script
  • Fetch a Data Acquisition Package
  • Fetch a File Acquisition Package
  • Fetch a Script by ID
  • Fetch a Triage Collection
  • Get All Scripts
  • Get Data Acquisition Status
  • Get File Acquisition Information
  • Get Host
  • Get Quarantine File
  • Get Quarantine File Acquisition Information
  • Get Quarantine List
  • Get Triage Acquisition Information
  • List Alerts
  • List All Scripts Details
  • List Host Data Acquisitions
  • List Hosts
  • List Triage Acquisitions
  • Parse Mandiant Analysis File
  • Release Host from Containment
  • Request Host Containment
  • Request Quarantined File Acquisition

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.

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.1.0

FortiSOAR™ Version Tested on: 6.0.0-790

Authored By: Fortinet.

Certified: Yes

Release Notes for version 1.1.0

Following enhancements have been made in the  FireEye HX connector in version 1.1.0:

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 yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-fireeye-hx

Prerequisites to configuring the connector

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 (if you are in the Grid view on the Connectors page) and in the Configurations 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
Get Quarantine List Retrieves the quarantine file list for a specific host from FireEye HX, based on the hostname you have specified. get_quarantine_list
Investigation
Request Quarantined File Acquisition Requests the acquisition of quarantined files into FireEye HX using the quarantine ID you have specified. request_acquisition
Investigation
Get Quarantine File Acquisition Information Retrieves details such as filename, filepath, MD, status, etc. about a file that is acquisition into FireEye HX based on the acquisition ID you have specified. get_acquisition_status
Investigation
Get Quarantine File Pulls quarantined files from FireEye HX based on the acquisition ID you have specified. fetch_acquisition
Investigation
List All Scripts Details Retrieves a list of all script details or specific script details from FireEye HX based on the input parameters you have specified. get_scripts
Investigation
Fetch a Script by ID Retrieves a specific script from FireEye HX in the XML format based on the script ID you have specified.
Note: This action also creates an attachment of the acquired file in FortiSOAR™, i.e, the acquired file is added in the "Attachment" module in FortiSOAR™.
fetch_script
Investigation
Get All Scripts Retrieves all available scripts from FireEye HX and adds it as ".zip" file in the "Attachment" module in FortiSOAR™. get_scripts
Investigation
Data Acquisition using Script Executes a custom data acquisition script using a predefined script ID or script on a specified host on FireEye HX based on the hostname, script name, an XML formatted data acquisition script, or script ID you have specified. request_acquisition
Investigation
List Host Data Acquisitions Retrieves a list of all data acquisitions for a specified host from FireEye HX based on the hostname and other input parameters you have specified. list_acquisitions
Investigation
Get Data Acquisition Status Retrieves details, including the status, of a data acquisition from FireEye HX based on the acquisition ID you have specified. get_acquisition_status
Investigation
Fetch a Data Acquisition Package Retrieves the output of a data acquisition request in the .mans format from FireEye HX based on the acquisition ID you have specified.
Note: This action also creates an attachment of the acquired file in FortiSOAR™, i.e, the acquired file is added in the "Attachment" module in FortiSOAR™.
fetch_acquisition
Investigation
Parse Mandiant Analysis File Parses a "Mandiant Analysis File" from the "Attachment" module in FortiSOAR™ based on the file attachment ID or IRI references you have specified. parse_mans_file
Investigation

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 from which you want to acquire the file for investigation on FireEye HX, 
File Path Path to the file to be acquired from the specified host for investigation on FireEye HX, 
File Name Name of the file to be acquired at the specified path for investigation on FireEye HX, 
External ID (Optional) External correlation ID, if applicable, of the file to be acquired for investigation on 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: 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 of the host for which you want to create a triage acquisition on 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: 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 whose output you want to retrieve 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": []
}

operation: Get Quarantine List

Input parameters

Parameter Description
Hostname Hostname whose quarantine file list you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "listing": [
         {
             "alert": {
                 "url": "",
                 "_id": ""
             },
             "hit_correlation_id": "",
             "file_md5": "",
             "_id": "",
             "file_path": "",
             "alert_infection_name": "",
             "quarantined_at": "",
             "state": "",
             "file_sha1": "",
             "reported_at": "",
             "agent_quarantine_id": "",
             "host": {
                 "url": "",
                 "_id": ""
             },
             "alert_file_creation_time": "",
             "update_time": "",
             "url": ""
         }
     ],
     "hostname": ""
}

operation: Request Quarantined File Acquisition

Input parameters

Parameter Description
Quarantine ID Quarantine ID of the target file for which you want to request acquisition into FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "quarantine_id": "",
     "route": "",
     "message": "",
     "details": [],
     "data": {
         "alert": {
             "url": "",
             "_id": ""
         },
         "agent_quarantine_id": "",
         "url": "",
         "_id": "",
         "host": {
             "url": "",
             "_id": ""
         },
         "state": ""
     }
}

operation: Get Quarantine File Acquisition Information

Input parameters

Parameter Description
Acquisition ID Acquisition request ID of the target file whose details such as filename, filepath, MD, status, etc. you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": {
         "route": "",
         "message": "",
         "details": [],
         "data": {
             "alert": {
                 "url": "",
                 "_id": ""
             },
             "agent_quarantine_id": "",
             "zip_passphrase": "",
             "_id": "",
             "request_time": "",
             "_revision": "",
             "host": {
                 "url": "",
                 "_id": ""
             },
             "state": "",
             "req_filename": "",
             "md5": "",
             "req_path": "",
             "comment": "",
             "error_message": "",
             "request_actor": {
                 "username": "",
                 "_id": ""
             },
             "url": ""
         }
     }
}

operation: Get Quarantine File

Input parameters

Parameter Description
Acquisition ID Acquisition ID of the quarantined file that you want to pull from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: List All Scripts Details

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 scripts) is returned.

Parameter Description
Search Term Searches all scripts on FireEye HX based on the search term. such as script ID, you have specified.
Search Offset Index (number) of the first item (scripts) that this operation should return.
Search Limit Specifies the number of records to fetch. It must be an unsigned 32-bit integer. By default, this is set as 50.
Sort By Sorts the results by the specified field in ascending or descending order. By default, sorting is done by "_id" in the ascending order.
Important: Currently sorting is only supported on the _id (script ID) parameter.
Filter By Retrieves only results that contain the specified field value from FireEye HX. For example, you can sort scripts by _id (script ID) and a filter such as, since='YYYY-MM-DDTHH:MM:SS.FFFZ', which will define the datetime from when you want to retrieve scripts from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": {
         "details": [],
         "message": "",
         "route": "",
         "data": {
             "sort": {},
             "total": "",
             "query": {},
             "offset": "",
             "entries": [
                 {
                     "last_used_at": "",
                     "download": "",
                     "url": "",
                     "_id": ""
                 }
             ],
             "limit": ""
         }
     }
}

operation: Fetch a Script by ID

Input parameters

Parameter Description
Script ID ID number of the targeted script that you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: Get All Scripts

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: Data Acquisition using Script

Input parameters

Parameter Description
Hostname Hostname, on FireEye HX on which you want to execute the custom data acquisition script and get the data acquisition.
xecutes a custom data acquisition script using a predefined script ID or script on a specified host on FireEye HX based on the hostname, script name and/or script ID you have specified.
Script Name Name of the script that you want to execute for the data acquisition on FireEye HX.
By Method Input type based on which the data acquisition script will be executed on FireEye HX.
If you choose By Script, then you must specify the following parameter:
  • Script: An XML formatted data acquisition script that you want to execute on the specified FireEye HX agent.
If you choose By Script ID, then you must specify the following parameter:
  • Script ID: A unique pre-existing data acquisition script ID, for example, f12aff009cb6e4c9f63d289d80fabb84162b6dff that you want to execute on the specified FireEye HX agent.

Output

The output contains the following populated JSON schema:
{
     "route": "",
     "message": "",
     "details": [],
     "data": {
         "script": {
             "download": "",
             "url": "",
             "_id": ""
         },
         "zip_passphrase": "",
         "_id": "",
         "host": {
             "url": "",
             "_id": ""
         },
         "name": "",
         "url": "",
         "state": "",
         "finish_time": "",
         "md5": "",
         "download": "",
         "_revision": "",
         "comment": "",
         "error_message": "",
         "request_time": "",
         "external_id": "",
         "request_actor": {
             "username": "",
             "_id": ""
         }
     }
}

operation: List Host Data Acquisitions

Input parameters

Parameter Description
Hostname Hostname for which you want to fetch a list of all data acquisitions from FireEye HX.
Search Offset Index (number) of the first item (data acquisition list) that this operation should return.
Search Limit Specifies the number of records to fetch. It must be an unsigned 32-bit integer. By default, this is set as 50.
Sort By Sorts the results by the specified field in ascending or descending order. You can sort fields by "_id" (host set ID) or "request_time" (time when the data acquisition was requested).
Filter Field Retrieves only results that contain the specified field value from FireEye HX. Available filters are: "host._id" (host set ID), "external_id" (external correlation ID from a SIEM solution), and "name" (script name)

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: Get Data Acquisition Status

Input parameters

Parameter Description
Acquisition ID Acquisition ID of the target data acquisition whose details including status you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "route": "",
     "message": "",
     "details": [],
     "data": {
         "script": {
             "download": "",
             "url": "",
             "_id": ""
         },
         "zip_passphrase": "",
         "_id": "",
         "host": {
             "url": "",
             "_id": ""
         },
         "name": "",
         "url": "",
         "state": "",
         "finish_time": "",
         "md5": "",
         "download": "",
         "_revision": "",
         "comment": "",
         "error_message": "",
         "request_time": "",
         "external_id": "",
         "request_actor": {
             "username": "",
             "_id": ""
         }
     }
}

operation: Fetch a Data Acquisition Package

Input parameters

Parameter Description
Acquisition ID Acquisition ID of the target data acquisition whose output of a data acquisition request you want to retrieve from FireEye HX.

Output

The output contains the following populated JSON schema:
{
     "data": [
         {
             "createDate": "",
             "createUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "@id": "",
             "modifyUser": {
                 "userType": "",
                 "modifyDate": "",
                 "createUser": "",
                 "avatar": "",
                 "@id": "",
                 "modifyUser": "",
                 "@type": "",
                 "userId": "",
                 "@settings": "",
                 "id": "",
                 "name": "",
                 "createDate": ""
             },
             "type": "",
             "description": "",
             "@type": "",
             "file": {
                 "uploadDate": "",
                 "size": "",
                 "file": {
                     "@type": ""
                 },
                 "metadata": "",
                 "filename": "",
                 "@id": "",
                 "@type": "",
                 "@context": "",
                 "mimeType": "",
                 "owners": [
                     ""
                 ]
             },
             "modifyDate": "",
             "@context": "",
             "name": "",
             "id": ""
         }
     ]
}

operation: Parse Mandiant Analysis File

Input parameters

Parameter Description
File Attachment/IRI Reference ID of the file attachment or IRI reference of file attachment that is used to access the file directly from the FortiSOAR™ "Attachments" module. The file specified in this field will be used to perform this operation.

Output

The output contains a non-dictionary value.

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.

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.