FireEye EX v1.1.0

About the connector

FireEye Email Security helps organizations minimize the risk of costly breaches. Email Security (EX Series) on-premises appliances, accurately detect and can immediately stop advanced and targeted attacks, including spear-phishing and ransomware before they enter your environment. Email Security uses the signatureless Multi-Vector Virtual Execution™ (MVX) engine to analyze email attachments and URLs against a comprehensive cross-matrix of operating systems, applications, and web browsers. Threats are identified with minimal noise, and false positives are nearly nonexistent.

This document provides information about the FireEye EX connector, which facilitates automated interactions, with a FireEye EX server using FortiSOAR™ playbooks. Add the FireEye EX connector as a step in FortiSOAR™ playbooks and perform automated operations, such as searching and retrieving information about domains, IP addresses, or name servers that you have specified.

Version information

Connector Version: 1.1.0

Authored By: Fortinet.

Certified: No

Release Notes for version 1.1.0

Following enhancements have been made to the FireEye EX Connector in version 1.1.0:

• Added the following new operations and playbooks:
  • Get Config
  • Get Alerts
  • Get Alert Details
  • Get Alert Related IOC
  • Get Artifacts Metadata By UUID
  • Add YARA Rule
  • List YARA Rule
  • Download YARA Rule
  • Delete YARA Rule
  • List Quarantined Emails
  • Download Quarantined Email
  • Release Quarantined Emails
  • Delete Quarantined Emails

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-ex

Prerequisites to configuring the connector

• You must have the FQDN or IP address of FireEye CMS server (using which you connect to the FireEye EX server) to which you will connect and perform the automated operations and the credentials 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

Configuration parameters

In FortiSOAR™, on the Connectors page, click the FireEye EX 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
Hostname	FQDN or IP address of FireEye CMS server (using which you connect to the FireEye EX server) to which you will connect and perform the automated operations.
Username	Username to access the FireEye EX server to which you will connect and perform the automated operations.
Password	Password to access the FireEye EX server to which you will connect and perform the automated operations.
API Version	Version of the API to be used for performing automated operations. For FireEye EX connector 1.1.0, the API version is set as v2.0.0. Therefore, currently, this is a read-only field, set as v2.0.0.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True.

Note: To use the FireEye EX connector you must create a user with the API Analyst role. Then you must enable wsapi from the command line as follows:

# enable
# configure terminal
# wsapi ?
# wsapi enable

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
Get Config	Retrieves a list of all guest image profiles and application details that are available on FireEye EX.	get_config Investigation
Get Alerts	Retrieves information of all existing alerts or specific existing alerts from FireEye EX based on alert ID, URL of the alert, and other input parameters you have specified.	get_alerts Investigation
Get Alert Details	Retrieves details of a single alert from FireEye EX based on the alert ID you have specified.	get_alert_details Investigation
Get Alert Related IOC	Retrieves the IOC in the XML or JSON format that is related to a specific alert from FireEye EX based on alert ID or UUID you have specified.	get_alert_ioc Investigation
Get Artifacts Metadata By UUID	Retrieves metadata for artifacts from FireEye EX based on the alert UUID you have specified.	get_artifacts_metadata_by_uuid Investigation
Add Custom Feed	Adds a custom feed to the FireEye EX server, based on the input parameters you have specified.	add_feed Containment
Delete Custom Feed	Deletes a custom feed from the FireEye EX server, based on the feed name you have specified.	delete_feed Remediation
Get Custom Feed	Retrieves a list of existing custom IOC feeds from the FireEye EX server.	get_feeds Investigation
Add YARA Rule	Adds a YARA rule to the FireEye EX server based on the file IRI, file type, and other input parameters you have specified.	add_yara_rule Containment
List YARA Rule	Retrieves a list of all YARA rules from the FireEye EX server based on the YARA type and other input parameters you have specified.	list_yara_rule Investigation
Download YARA Rule	Downloads a YARA rule file from the FireEye EX server based on the YARA file name, YARA type, and other input parameters you have specified.	download_yara_rule Miscellaneous
Delete YARA Rule	Deletes a YARA rule file from the FireEye EX server based on the YARA file name, YARA type, and other input parameters you have specified.	delete_yara_rule Miscellaneous
List Quarantined Emails	Retrieves a list of all quarantined emails or specific quarantined emails from FireEye EX based on the input parameters you have specified.	list_quarantined_emails Investigation
Download Quarantined Email	Downloads specific quarantined emails from FireEye EX based on the queue ID and other input parameters you have specified.	download_quarantined_email Investigation
Release Quarantined Emails	Releases and deletes specific quarantined emails from FireEye EX based on the queue ID you have specified.	release_quarantined_emails Investigation
Delete Quarantined Emails	Deletes specific quarantined emails from FireEye EX based on the queue ID you have specified.	delete_quarantined_emails Investigation

operation: Get Config

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"ns2:sysconfig": {
"@sensor_name": "",
"sensors": {
"sensor": [
{
"features": {
"feature": {
"@name": "",
"@enabled": ""
}
},
"profiles": {
"profile": [
{
"@name": "",
"applications": {
"application": [
{
"@name": "",
"@id": ""
}
]
},
"@id": ""
}
]
},
"@address": "",
"@id": ""
}
]
},
"osdetails": {
"osdetail": {
"composite": "",
"product": "",
"release": ""
}
}
}
}

operation: Get Alerts

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter	Description
Alert ID	ID of the alert whose information you want to retrieve from FireEye EX.
Information Level	Level of information to be retrieved for alerts from FireEye EX. You can choose from the following options: Concise (default), Normal, or Extended.
Alert URL	URL or the alert for which you want to search and retrieve information from FireEye EX.
File Name	Name of the malware file for which you want to search and retrieve information from FireEye EX.
File Type	Type of the malware file for which you want to search and retrieve information from FireEye EX.
Malware Name	Name of the malware object for which you want to search and retrieve information from FireEye EX.
Malware Type	Type of malware object for which you want to search and retrieve information from FireEye EX. For example, domain_match, malware_callback, malware_object, web_infection, infection_match etc.
Start Time	DateTime from when you want to retrieve alerts from FireEye EX.
End Time	DateTime till when you want to retrieve alerts from FireEye EX.

Output

The output contains the following populated JSON schema:
{
"alertsCount": "",
"version": "",
"msg": "",
"alert": [
{
"applianceId": "",
"id": "",
"action": "",
"vlan": "",
"name": "",
"ack": "",
"smtpMessage": {
"subject": ""
},
"occurred": "",
"scVersion": "",
"severity": "",
"product": "",
"uuid": "",
"explanation": {
"malwareDetected": {
"malware": [
{
"md5Sum": "",
"name": "",
"sha256": ""
}
]
},
"osChanges": []
},
"malicious": "",
"src": {
"smtpMailFrom": ""
},
"dst": {
"smtpTo": ""
},
"rootInfection": "",
"sensorIp": "",
"sensor": "",
"alertUrl": ""
}
],
"appliance": ""
}

operation: Get Alert Details

Input parameters

Parameter	Description
Alert ID	ID of the alert whose information you want to retrieve from FireEye EX.

Output

The output contains the following populated JSON schema:
{
"alertsCount": "",
"appliance": "",
"msg": "",
"alert": [
{
"name": "",
"explanation": {
"malwareDetected": {
"malware": [
{
"md5Sum": "",
"name": "",
"sha256": ""
}
]
},
"osChanges": []
},
"action": "",
"vlan": "",
"alertUrl": "",
"applianceId": "",
"rootInfection": "",
"occurred": "",
"scVersion": "",
"product": "",
"severity": "",
"id": "",
"uuid": "",
"smtpMessage": {
"subject": ""
},
"malicious": "",
"src": {
"smtpMailFrom": ""
},
"dst": {
"smtpTo": ""
},
"sensorIp": "",
"sensor": "",
"ack": ""
}
],
"version": ""
}

operation: Get Alert Related IOC

Input parameters

Parameter	Description
Filter by	Select whether you want to filter the IOC filter by Alert ID or Alert UUID. If you select Alert UUID, then in the Alert UUID field specify the UUID of the alert whose associated IOC information you want to retrieve from FireEye EX. If you select Alert ID, then in the Alert ID field specify the ID of the alert whose associated IOC information you want to retrieve from FireEye EX.
Response Format	Select the format in which you want the response data to be returned. You can choose between XML or JSON.

Output

The output contains the following populated JSON schema:
{
"OpenIOC": {
"@published-date": "",
"@xmlns": "",
"@id": "",
"metadata": {
"short_description": "",
"authored_by": "",
"links": {
"link": [
{
"@rel": "",
"@href": "",
"#text": ""
}
]
},
"description": "",
"authored_date": ""
},
"criteria": {
"Indicator": {
"IndicatorItem": [
{
"@preserve-case": "",
"Context": {
"@document": "",
"@search": "",
"@type": ""
},
"@condition": "",
"Content": {
"@type": "",
"#text": ""
},
"@id": "",
"@negate": ""
}
],
"@operator": "",
"@id": ""
}
},
"@last-modified": ""
}
}

operation: Get Artifacts Metadata By UUID

Input parameters

Parameter	Description
Alert UUID	UUID of the alert whose artifacts metadata you want to retrieve from FireEye EX.

Output

The output contains the following populated JSON schema:
{
"artifactsInfoList": [
{
"artifactType": "",
"artifactName": "",
"artifactSize": ""
}
]
}

operation: Add Custom Feed

Input parameters

Parameter	Description
Feed Name	Name of the new feed or name of an existing feed that you want to modify or add to the FireEye EX server.
Feed Type	Type of the feed that you want to add to the FireEye EX server. Currently, only IP type feed is supported. The future versions of this connector could support feed types such as URL, Domain, or Hash.
Feed Action	Type of notification that will be received, if a match is found. For example, Alert. If you add Alert in this field, then an alert notification will be generated.
Feed Source	Source of the feed.
IOC Feed Data(CSV or List Format)	Actual IP address, URL, Domain name or Hash value that needs to be blocked on the FireEye EX server. You can add multiple IP addresses, URLs, Domain names or Hash values in these fields using the CSV or list format. For example, you can add a list of URLs as abc.com, xyz.com, def.com
Overwrite Existing Feed	Select this option, i.e. set this option to true, if you are updating an existing feed on the FireEye EX server. Clear this option, i.e. set this option to false, if you are adding a new feed to the FireEye EX server.

Output

The JSON output contains the status of the add custom feed operation. The JSON output returns a Successmessage if the custom feed is successfully added or updated (in case of an existing feed) on the FireEye EX server or an Error message containing the reason for failure.

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

operation: Delete Custom Feed

Input parameters

Parameter	Description
Feed Name	Name of the custom feed that you want to delete from the FireEye EX server.

Output

The JSON output contains the status of the delete custom feed operation. The JSON output returns a Successmessage if the custom feed is successfully deleted from the FireEye EX server or an Error message containing the reason for failure.

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

operation: Get Custom Feed

Input parameters

None.

Output

The JSON output contains a list of existing custom IOC feeds from the FireEye EX server.

The output contains the following populated JSON schema:
{
"customFeedInfo": [
{
"feedType": "",
"feedAction": "",
"status": "",
"feedSource": "",
"contentMeta": [],
"feedName": "",
"uploadDate": ""
}
]
}

operation: Add YARA Rule

Input parameters

Parameter	Description
File IRI	IRI of the file that you want to submit as a YARA rule to the FireEye EX server.
File Type	File type of the YARA rule file that you are submitting to the FireEye EX server. Supported file types are .exe, .pdf, .xls, or .ppt.
Target Type	Select the content type to which you want to apply the new YARA rule. You can choose from the following options: Active Content, Base (Default), or All.

Output

The output contains a non-dictionary value.

operation: List YARA Rule

Input parameters

Parameter	Description
YARA Type	Type of the YARA file whose associated list of YARA rules you want to retrieve from the FireEye EX server. Supported YARA types are .exe, .pdf, .xls, or .ppt.
Sensor Name	(Optional) Name of the sensor based on which you want to retrieve the list of YARA rules from the FireEye EX server. This parameter is required for Central Management.

Output

The output contains a non-dictionary value.

operation: Download YARA Rule

Input parameters

Parameter	Description
YARA Type	Type of the YARA file that you want to download from the FireEye EX server. Supported YARA types are .exe, .pdf, .xls, or .ppt.
YARA File Name	Name of the YARA file that you want to download from the FireEye EX server.
Sensor Name	(Optional) Name of the sensor whose associated YARA rule you want to download from the FireEye EX server. This parameter is required for Central Management.

Output

The output contains the following populated JSON schema:
{
"file_iri": "",
"attachments_iri": ""
}

operation: Delete YARA Rule

Input parameters

Parameter	Description
YARA Type	Type of the YARA file that you want to delete from the FireEye EX server. Supported YARA types are .exe, .pdf, .xls, or .ppt.
YARA File Name	Name of the YARA file that you want to delete from the FireEye EX server.
Target Type	Select the content type from which you want to remove the YARA rule. You can choose from the following options: Active Content, Base (Default), or All.

Output

The output contains a non-dictionary value.

operation: List Quarantined Emails

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter	Description
Filter by Time	Select this checkbox, if you want to retrieve quarantined emails from FireEye Ex based on time. If you select this checkbox, i.e., set is as true, then you must specify the following parameters: Start Time: Start DateTime from which you want to retrieve Emails from FireEye Ex. Specify this parameter in conjunction with End Time End Time: End DateTime till which you want to retrieve Emails from FireEye Ex. Specify this parameter in conjunction with Start Time UTC Time Offset: Time offset from UTC. The format is OH:om. For example. 07:00.
From	Sender of the email whose associated quarantined emails you want to retrieve from FireEye Ex.
Subject	Subject of the email based on which you want to retrieve quarantined emails from FireEye Ex.
Limit	Maximum number of records, based on your filter criterion, you want to include in the output of this operation. By default, it is set as 10000.

Output

The output contains the following populated JSON schema:
{
"email_uuid": "",
"queue_id": "",
"quarantine_path": "",
"completed_at": "",
"subject": "",
"message_id": "",
"appliance_id": "",
"from": ""
}

operation: Download Quarantined Email

Input parameters

Parameter	Description
Queue ID	Queue ID of the quarantined emails that you want to download from FireEye EX.
Sensor Name	(Optional) Display name of the sensor whose associated quarantined emails that you want to download from FireEye EX

Output

The output contains the following populated JSON schema:
{
"file_iri": "",
"attachments_iri": ""
}

operation: Release Quarantined Emails

Input parameters

Parameter	Description
Queue IDs	List of queue IDs whose associated quarantined emails you want to release from FireEye Ex.

Output

The output contains a non-dictionary value.

operation: Delete Quarantined Emails

Input parameters

Parameter	Description
Queue IDs	List of queue IDs whose associated quarantined emails you want to delete from FireEye Ex.

Output

The output contains a non-dictionary value.

Included playbooks

The Sample - FireEye-EX - 1.1.0 playbook collection comes bundled with the FireEye EX connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the FireEye EX connector.

• Add Custom Feed
• Add YARA Rule
• Delete Custom Feed
• Delete Quarantined Emails
• Delete YARA Rule
• Download Quarantined Email
• Download YARA Rule
• Get Alert Details
• Get Alert Related IOC
• Get Alerts
• Get Artifacts Metadata By UUID
• Get Config
• Get Custom Feeds
• List Quarantined Emails
• List YARA Rule
• Release Quarantined Emails

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.