FireEye Email Threat Prevention

FireEye Email Threat Prevention is a security solution that protects against advanced email-based threats using threat intelligence and machine learning.

FireEye Email Threat Prevention is a robust platform designed to detect and prevent advanced email threats. This connector allows Swimlane Turbine users to automate the retrieval and analysis of email threat alerts, enhancing their security operations. By integrating with FireEye ETP, users can efficiently manage and respond to email threats, streamline threat detection processes, and improve overall security posture through automated workflows.

Prerequisites

Before you can use the FireEye Email Threat Prevention connector for Turbine, you'll need access to the FireEye API. This requires the following:

an API key authentication using the following parameters:

URL: The endpoint URL for accessing the FireEye API.

API Key: A unique key provided by FireEye to authenticate API requests.

Capabilities

This Connector provides the following capabilities:

Get Alerts Summary

Get Detail of Specified Alert

Message Trace Information Request

Search for Messages

Additional Documentation

FireEye Email Threat Prevention Connector Documentation

FireEye Email Threat Prevention API Documentation

Configurations

FireEye ETP API Key Authentication

Authenticates using an API Key

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
x-fireeye-api-key	FireEye API key	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Get Alerts Summary

Retrieve a summary list of advanced threat alerts from FireEye Email Threat Prevention using the provided JSON body.

Endpoint

URL: /api/v1/alerts

Method: POST

Input

Argument Name	Type	Required	Description
attributes	object	Optional	Parameter for Get Alerts Summary
attributes.etp_message_id	string	Optional	Email message ID.
attributes.email_status	string	Optional	Status value
fromLastModifiedOn	string	Optional	Date time in yyyy-mm-ddThh:mm:ss.fff format inreverse chronological order. Default is 90 days.
size	number	Optional	Number of alerts to include in response. Valid range is 1-100.

Input Example

{"json_body":{"attributes":{"etp_message_id":"zWwsdM66OUZHzzWwsdQW9o","email_status":"released"},"fromLastModifiedOn":"2018-10-03T00:00:00.000Z","size":3}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	array	Response data
data.attributes	object	Response data
data.attributes.meta	object	Response data
data.attributes.meta.read	boolean	Response data
data.attributes.meta.last_modified_on	string	Response data
data.attributes.meta.legacy_id	number	Response data
data.attributes.meta.acknowledged	boolean	Response data
data.attributes.ati	object	Response data
data.attributes.ati.threat_type	string	Response data
data.attributes.alert	object	Response data
data.attributes.alert.product	string	Response data
data.attributes.alert.malware_md5	string	Response data
data.attributes.alert.timestamp	string	Response data
data.attributes.email	object	Response data
data.attributes.email.status	string	Response data
data.attributes.email.smtp	object	Response data
data.attributes.email.smtp.rcpt_to	string	Response data
data.attributes.email.smtp.mail_from	string	Response data
data.attributes.email.etp_message_id	string	Response data
data.attributes.email.headers	object	Response data
data.attributes.email.headers.cc	string	Response data
data.attributes.email.headers.to	string	Response data
data.attributes.email.headers.from	string	Response data

Output Example

Get Detail of Specified Alert

Retrieve detailed information for a specific advanced threat alert in FireEye Email Threat Prevention using the provided alert ID.

Endpoint

URL: /api/v1/alerts/{{alert_id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.alert_id	string	Required	Parameters for the Get Detail of Specified Alert action

Input Example

{"path_parameters":{"alert_id":"AV7zzRy7kvIWwrKcfu0I"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	array	Response data
data.attributes	object	Response data
data.attributes.meta	object	Response data
data.attributes.meta.read	boolean	Response data
data.attributes.meta.last_modified_on	string	Response data
data.attributes.meta.legacy_id	number	Response data
data.attributes.meta.acknowledged	boolean	Response data
data.attributes.ati	object	Response data
data.attributes.alert	object	Response data
data.attributes.alert.product	string	Response data
data.attributes.alert.alert_type	array	Response data
data.attributes.alert.severity	string	Response data
data.attributes.alert.ack	string	Response data
data.attributes.alert.malware_md5	string	Response data
data.attributes.alert.explanation	object	Response data
data.attributes.alert.explanation.analysis	string	Response data
data.attributes.alert.explanation.anomaly	string	Response data
data.attributes.alert.explanation.cnc_services	object	Response data
data.attributes.alert.explanation.malware_detected	object	Response data
data.attributes.alert.explanation.os_changes	array	Response data
data.attributes.alert.explanation.protocol	string	Response data
data.attributes.alert.explanation.timestamp	string	Response data
data.attributes.alert.timestamp	string	Response data

Output Example

Message Trace Information Request

Retrieve attributes for a specific message in FireEye Email Threat Prevention using the provided ETP message ID.

Endpoint

URL: /api/v1/messages/{{etp_message_id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.etp_message_id	string	Required	The ID of the ETP message.

Input Example

{"path_parameters":{"etp_message_id":"7G5IeqTT39DVw7G5Ie3sDM"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	array	Response data
data.attributes	object	Response data
data.attributes.acceptedDateTime	string	Response data
data.attributes.countryCode	string	Response data
data.attributes.domain	string	Response data
data.attributes.downStreamMsgID	string	Response data
data.attributes.emailSize	number	Response data
data.attributes.lastModifiedDateTime	string	Response data
data.attributes.recipientHeader	array	Response data
data.attributes.recipientSMTP	array	Response data
data.attributes.senderHeader	string	Response data
data.attributes.senderSMTP	string	Response data
data.attributes.senderIP	string	Response data
data.attributes.status	string	Response data
data.attributes.subject	string	Response data
data.attributes.verdicts	object	Response data
data.attributes.verdicts.AS	string	Response data
data.attributes.verdicts.AV	string	Response data
data.attributes.verdicts.AT	string	Response data
data.attributes.verdicts.PV	string	Response data
data.included	array	Response data
data.included.type	string	Response data
data.included.id	number	Response data

Output Example

Search for Messages

Retrieve a list of messages with specified attributes from the FireEye Email Threat Prevention portal.

Endpoint

URL: /api/v1/messages/trace

Method: POST

Input

Argument Name	Type	Required	Description
search	object	Optional	Parameter for Search for Messages
search.type	string	Optional	Specify the type of the query. Currently, this can have only one value MessageAttributes.
search.size	number	Optional	The number of entries returned by the search query. Default is 20 and maximum is 100.
search.attributes	object	Optional	Parameter for Search for Messages
search.attributes.fromEmail	object	Optional	List of From email-addresses, 10 entries maximum.
search.attributes.fromEmail.value	array	Optional	Attributes From Email value.
search.attributes.fromEmail.filter	string	Optional	Attributes From Email Filter.
search.attributes.fromEmail.includes	array	Optional	Attributes From Email Includes.
search.attributes.recipients	object	Optional	Array of To/Cc email addresses, 10 entries maximum.
search.attributes.recipients.value	array	Optional	Attributes Recipients Value.
search.attributes.recipients.filter	string	Optional	Attributes Recipients filter.
search.attributes.recipients.includes	array	Optional	Attributes Recipients Includes.
search.attributes.subject	object	Optional	Text to search for in the subject.
search.attributes.subject.value	string	Optional	Attributes Subject Value.
search.attributes.subject.filter	string	Optional	Attributes Subject filter.
search.attributes.period	object	Optional	Attributes Period.
search.attributes.period.range	object	Optional	Parameter for Search for Messages
search.attributes.period.range.fromAcceptedDateTime	string	Optional	Attributes Period Range From Accepted Date Time. Format compliant with ISO8601.
search.attributes.period.range.toAcceptedDateTime	string	Optional	Attributes Period Range To Accepted Date Time. Format compliant with ISO8601.
search.attributes.lastModifiedDateTime	object	Optional	Last modified date time format compliant with ISO860
search.attributes.lastModifiedDateTime.value	string	Optional	Attributes Last Modified Date Time Value.
search.attributes.lastModifiedDateTime.filter	string	Optional	Attributes Last Modified Date Time Filter. Filter values are >=, <=, >, <.
search.attributes.status	object	Optional	Array of email status values.
search.attributes.status.value	array	Optional	Attributes Status Value.
search.attributes.status.filter	string	Optional	Attributes Status Filter.

Input Example

{"json_body":{"search":{"type":"MessageAttibutes","size":100,"attributes":{"fromEmail":{"value":["[email protected]"],"filter":"in","includes":["SMTP"]},"recipients":{"value":["[email protected]","[email protected]"],"filter":"in","includes":["SMTP","HEADER"]},"subject":{"value":"test message","filter":"in"},"period":{"range":{"fromAcceptedDateTime":"2017-07-11T04:52:26.365000+00:00","toAcceptedDateTime":"2017-07-10T04:51:26.365000+00:00"}},"lastModifiedDateTime":{"value":"2017-07-11T04:51:26.365000+00:00","filter":">="},"status":{"value":["accepted","rejected"],"filter":"in"},"rejectionReason":{"value":["DHAP failed"]},"atVerdict":{"value":["pass"],"filter":"in"},"avVerdict":{"value":["pass","fail"],"filter":"in"},"asVerdict":{"value":["pass"],"filter":"in"},"pvAction":{"value":["others"],"filter":"not in"},"hasAttachment":true,"messageSize":{"range":{"min":0,"max":1000}},"senderIP":{"value":["10.128.1.1","10.128.1.2"],"filter":"in"},"domains":{"value":["etp-testdomain5.com","etp-tesdomain5.com"]}}}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	array	Response data
data.attributes	object	Response data
data.attributes.acceptedDateTime	string	Response data
data.attributes.countryCode	string	Response data
data.attributes.domain	string	Response data
data.attributes.emailSize	number	Response data
data.attributes.rejectionReason	object	Response data
data.attributes.rejectionReason.code	string	Response data
data.attributes.rejectionReason.description	string	Response data
data.attributes.isMarkedDeleted	boolean	Response data
data.attributes.isRead	boolean	Response data
data.attributes.lastModifiedDateTime	string	Response data
data.attributes.recipientHeader	array	Response data
data.attributes.recipientSMTP	array	Response data
data.attributes.senderHeader	string	Response data
data.attributes.senderSMTP	string	Response data
data.attributes.senderIP	string	Response data
data.attributes.status	string	Response data
data.attributes.subject	string	Response data
data.attributes.verdicts	object	Response data
data.attributes.verdicts.AS	string	Response data
data.attributes.verdicts.AV	string	Response data
data.attributes.verdicts.AT	string	Response data

Output Example

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT