FireEye ETP

FireEye Email Threat Prevention (ETP)

Overview

Use the FireEye Email Threat Prevention (ETP) integration to import messages as incidents, search for messages with specific attributes, and retrieve alert data.

Use Cases

  • Search for messages using specific message attributes as indicators.
  • Import messages as Cortex XSOAR incidents, using the message status as indicator.

Prerequisites

Make sure you obtain the following information.

  • Valid FireEye ETP account
  • Configure an API key on the ETP Web portal. Select the product as both Email Threat Prevention and Identity Access Management. Select all entitlements.
  • Upon Authentication errors, contact FireEye Technical Support to let them know the IP address of your Cortex XSOAR Server and the URL you are accessing , e.g. https://etp.us.fireeye.com. FireEye will add these details to their Firewall rules so that the bidirectional traffic can be allowed between Cortex XSOAR and FireEye ETP.

Configure FireEye ETP on Demisto

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for FireEye ETP.
  3. Click Add instance to create and configure a new integration instance.
    • Name: a textual name for the integration instance.
    • Server URL: ETP server URL. Use the endpoint in the region that hosts your ETP service:
    • API key: The API key configured in the ETP Web Portal.
    • Messages status: All status specified messages will be imported as incidents. Valid values are:
      • accepted
      • deleted
      • delivered
      • delivered (retroactive)
      • dropped
      • dropped oob
      • dropped (oob retroactive)
      • permanent failure
      • processing
      • quarantined
      • rejected
      • temporary failure
  4. Click Test to validate the URLs and connection.

Fetched Incidents Data

To use Fetch incidents:

  1. Configure a new instance.
  2. Navigate to instance settings, and specify the message status (using the valid values).
  3. Select Fetch incidents option.

The integration will fetch alerts as incidents. It is possible to filter alerts using the specified message status.

Commands

You can execute these commands from the Demisto CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

  1. Search for messages: fireeye-etp-search-messages
  2. Get metadata of a specified message: fireeye-etp-get-message
  3. Get summary of all alerts: fireeye-etp-get-alerts
  4. Get details of a specified alert: fireeye-etp-get-alert

Search for messages

Search for messages using specific message attributes as indicators.

Base Command

fireeye-etp-search-messages

Input
ParameterDescriptionMore Information
from_emailList of sender email addressesMaximum 10 arguments
from_email_not_inList of sender email addresses to be excludedMaximum 10 arguments
recipientsList of recipient email addresses (including "cc")Maximum 10 arguments
recipients_not_inlist of recipient email addresses to be excluded (including "cc")Maximum 10 arguments
subjectList of subjects in string formatMaximum 10 arguments
from_accepted_date_timeThe start date of the search range, in time stamp formatFor example, 2017-10-24T10:48:51.000Z
to_accepted_date_timeThe end date of the search range, in time stamp formatFor example, 2017-10-24T10:48:51.000Z
rejection_reasonList of ETP rejection-reason-codesValid rejection-reason-codes are:
  • ETP102
  • ETP103
  • ETP104
  • ETP200
  • ETP201
  • ETP203
  • ETP204
  • ETP205
  • ETP300
  • ETP301
  • ETP302
  • ETP401
  • ETP402
  • ETP403
  • ETP404
  • ETP405
sender_ipList of sender IP addressesMaximum of 10 arguments
statusList of email status valuesValid statuses are:
  • accepted
  • deleted
  • delivered
  • delivered (retroactive)
  • dropped
  • dropped oob
  • dropped (oob retroactive)
  • permanent failure
  • processing
  • quarantined
  • rejected
status_not_inList of email status values to excludeValid statuses are:
  • accepted
  • deleted
  • delivered
  • delivered (retroactive)
  • dropped
  • dropped oob
  • dropped (oob retroactive)
  • permanent failure
  • processing
  • quarantined
  • rejected
last_modified_date_timeLast modification date, in timestamp format, along with one of the following operators to indicate if to limit to before or after the specified date and time:
  • >
  • <
  • >=
  • <=
For example, to search for messages that were last modified before this specific date and time, use the following value:
<2017-10-24T18:00:00.000Z
domainList of domain names
has_attachmentsIndicates if the message has attachmentsBoolean value
max_message_sizeMaximum message sizeDefault value is 20 KB.
Maximum value is 100 KB.
Context Output
PathDescription
FireEyeETP.Message.acceptedDateTimeDate and time that the message was accepted
FireEyeETP.Message.countryCodeCountry code of sender
FireEyeETP.Message.domainDomain
FireEyeETP.Message.emailSizeEmail size in KB
FireEyeETP.Message.lastModifiedDateTimeLast modification date of message
FireEyeETP.Message.recipientHeaderList of message recipients display names and email addresses
FireEyeETP.Message.recipientsList of message recipients
FireEyeETP.Message.senderHeaderDisplay name and email address of the message sender
FireEyeETP.Message.senderEmail address of message sender
FireEyeETP.Message.senderSMTPSMTP of Message sender
FireEyeETP.Message.senderIPMessage sender IP address
FireEyeETP.Message.statusMessage status
FireEyeETP.Message.subjectMessage subject
FireEyeETP.Message.verdicts.ASVerdict for AS (pass/fail)
FireEyeETP.Message.verdicts.AVVerdict for AV (pass/fail)
FireEyeETP.Message.verdicts.ATVerdict for AT (pass/fail)
FireEyeETP.Message.verdicts.PVVerdict for PV (pass/fail)
FireEyeETP.Message.idMessage ID
Command example 1

!fireeye-etp-search-messages to_accepted_date_time=2017-10- 24T10:00:00.000Z from_accepted_date_time=2017-10- 24T10:30:00.000Z

Command example 2

!fireeye-etp-search-messages from_email=diana@corp.com,charles@corp.com

Raw Output
{
"data": [
{
"attributes": {
"acceptedDateTime": "2018-06-09T10:49:32.000Z",
"countryCode": "US",
"domain": "demisto.com",
"downStreamMsgID": "250 2.0.0 OK 100041373 d14-v6si970000qtb.70 - gsmtp",
"emailSize": 9.89,
"lastModifiedDateTime": "2018-06-09T10:49:33.329Z",
"recipientHeader": [
"Security Operations Center <SOC@corp.com>"
],
"recipientSMTP": [
"jason@demisto.com"
],
"senderHeader": "\"soc@demisto.com\" <bot@demisto.com >",
"senderSMTP": "prvs=691a94fds62a=demisto@demisto.com ",
"senderIP": "***.***.***.***",
"status": "delivered",
"subject": "Attack TCP: SYN Host Sweep (Medium)",
"verdicts": {
"AS": "",
"AV": "",
"AT": "pass",
"PV": ""
}
},
"included": [
{
"type": "domain",
"id": 29074,
"attributes": {
"name": " demisto.com "
}
}
],
"id": "C88B18749AAAAB1B55fc0fa78",
"type": "trace"
}
],
"meta": {
"total": 85347,
"copyright": "Copyright 2018 Fireeye Inc",
"fromLastModifiedOn": {
"start": "2018-06-09T10:49:33.329Z",
"end": "2018-06-09T10:50:59.034Z"
}
}
}

Get metadata of a specified message

Get the metadata of a specified message.

Base Command

fireeye-etp-get-message

Input
ParameterDescription
message_idMessage ID
Context Output
PathDescription
FireEyeETP.Message.acceptedDateTimeDate and time that the message was accepted
FireEyeETP.Message.countryCodeCountry code of sender
FireEyeETP.Message.domainDomain
FireEyeETP.Message.emailSizeEmail size in KB
FireEyeETP.Message.lastModifiedDateTimeMessage last modification date
FireEyeETP.Message.recipientHeaderList of message recipients display names and email addresses
FireEyeETP.Message.recipientsList of message recipients
FireEyeETP.Message.senderHeaderDisplay name and email address of the message sender
FireEyeETP.Message.senderMessage sender address
FireEyeETP.Message.senderSMTPMessage sender SMTP
FireEyeETP.Message.senderIPMessage sender IP address
FireEyeETP.Message.statusMessage status
FireEyeETP.Message.subjectMessage subject
FireEyeETP.Message.verdicts.ASVerdict for AS (pass/fail)
FireEyeETP.Message.verdicts.AVVerdict for AV (pass/fail)
FireEyeETP.Message.verdicts.ATVerdict for AT (pass/fail)
FireEyeETP.Message.verdicts.PVVerdict for PV (pass/fail)
FireEyeETP.Message.idMessage ID
Command example

!fireeye-etp-get-message message_id= C88B18749AAAAB1B55fc0fa78

Raw Output

There is no raw output for this command.

Get summary of all alerts

Get summary-format information about the alerts. Alerts that are more than 90 days old are not available.

Base Command

fireeye-etp-get-alerts

Input
ParameterDescriptionMore Information
legacy_idAlert ID as shown in ETP Web Portal
from_last_modified_onLast modification date and time in the following format:
yyy-mm-ddThh:mm:ss.fff
Default is last 90 days.
etp_message_idEmail message ID
sizeNumber of alerts intended in responseDefault is 20.
Valid range is 1-100.
Context Output
PathDescription
FireEyeETP.Alerts.meta.readHas the email been read?
FireEyeETP.Alerts.meta.last_modified_onLast modification date in timestamp format
FireEyeETP.Alerts.meta.legacy_idAlert ID as shown in ETP web portal
FireEyeETP.Alerts.alert.productProduct alerted
FireEyeETP.Alerts.alert.timestampAlert timestamp
FireEyeETP.Alerts.alert.malware_md5MD5 of file attached
FireEyeETP.Alerts.email.statusEmail status
FireEyeETP.Alerts.email.source_ipEmail source IP address
FireEyeETP.Alerts.email.smtp.rcpt_toRecipient SMTP
FireEyeETP.Alerts.email.smtp.mail_fromSender SMTP
FireEyeETP.Alerts.email.etp_message_idMessage ID
FireEyeETP.Alerts.email.headers.ccEmail 'cc' recipients
FireEyeETP.Alerts.email.headers.toEmail recipients
FireEyeETP.Alerts.email.headers.fromEmail sender
FireEyeETP.Alerts.email.headers.subjectEmail subject
FireEyeETP.Alerts.email.attachmentFile name or URL pointing to file
FireEyeETP.Alerts.email.timestamp.acceptedTime the email was accepted
FireEyeETP.Alerts.idAlert ID
Command example

!fireeye-etp-get-alerts legacy_id=50038117

Raw Output
{
"data": [
{
"attributes": {
"meta": {
"read": false,
"last_modified_on": "2018-04-02T22:28:46.133",
"legacy_id": 50038117,
"acknowledged": false
},
"ati": {},
"alert": {
"product": "ETP",
"timestamp": "2018-04-02T22:28:41.328"
},
"email": {
"status": "quarantined",
"source_ip": "xx.xxx.xxx.xxx",
"smtp": {
"rcpt_to": "demisto@demisto.com",
"mail_from": "bot@demisto.com"
},
"etp_message_id": "0103174000EA2CA54302e5ef",
"headers": {
"cc": "<birdperson@demisto.com>",
"to": "< morty@demisto.com >",
"from": " rick@demisto.com ",
"subject": "[ CAT 6 ] DOHMH: Suspicious Activity Detected | 11810"
},
"attachment": "hxxp://xyzt.com/REX/slick.php?utma=gorc'",
"timestamp": {
"accepted": "2018-04-02T22:28:38"
}
},
"id": "AWKIehnC9Y6JVVonz9xG",
"links": {
"detail": "/api/v1/alerts/AWKIehnC9Y6JVVonz9xG"
}},
"total": 109,
"copyright": "Copyright 2018 Fireeye Inc"
}],
"type": "alerts"
}

Get details of specified alert

Returns detailed information for any specified alert. Alerts that are more than 90 days old are not available.

Base Command

fireeye-etp-get-alert

Input
ParameterDescription
alert_idAlert ID
Context Output
PathDescription
FireEyeETP.Alerts.meta.readHas the email been read?
FireEyeETP.Alerts.meta.last_modified_onLast modification date in timestampformat
FireEyeETP.Alerts.meta.legacy_idAlert ID as shown in ETP web portal
FireEyeETP.Alerts.meta.acknowledgedIf acknowledged
FireEyeETP.Alerts.alert.productProduct that generated the alert
FireEyeETP.Alerts.alert.alert_typeAAlert type code
FireEyeETP.Alerts.alert.severitySeverity code
FireEyeETP.Alerts.alert.explanation.analysisAnalysis
FireEyeETP.Alerts.alert.explanation.anomalyAnomaly
FireEyeETP.Alerts.alert.explanation.malware_detected.malware.domainMalware domain
FireEyeETP.Alerts.alert.explanation.malware_detected.malware.downloaded_atTime malware was downloaded in timestamp format
FireEyeETP.Alerts.alert.explanation.malware_detected.malware.executed_atMalware executed at timestamp
FireEyeETP.Alerts.alert.explanation.malware_detected.malware.nameMalware name
FireEyeETP.Alerts.alert.explanation.malware_detected.malware.sidMalware SID
FireEyeETP.Alerts.alert.explanation.malware_detected.malware.stypeMalware type
FireEyeETP.Alerts.alert.explanation.malware_detected.malware.submitted_atWhere the malware was submitted
FireEyeETP.Alerts.alert.explanation.protocolProtocol
FireEyeETP.Alerts.alert.explanation.timestampExplanation timestamp
FireEyeETP.Alerts.alert.timestampAlert timestamp
FireEyeETP.Alerts.alert.actionAlert action
FireEyeETP.Alerts.alert.nameAlert name
FireEyeETP.Alerts.email.statusEmail status
FireEyeETP.Alerts.email.source_ipEmail source IP address
FireEyeETP.Alerts.email.smtp.rcpt_toRecipient SMTP
FireEyeETP.Alerts.email.smtp.mail_fromSender SMTP
FireEyeETP.Alerts.email.etp_message_idFireEye ETP unique message ID
FireEyeETP.Alerts.email.headers.ccEmail cc recipients
FireEyeETP.Alerts.email.headers.toEmail recipients
FireEyeETP.Alerts.email.headers.fromEmail sender
FireEyeETP.Alerts.email.headers.subjectEmail subject
FireEyeETP.Alerts.email.attachmentFile name or URL pointing to file
FireEyeETP.Alerts.email.timestamp.acceptedTime that the email was accepted
FireEyeETP.Alerts.idThe alert unique ID
Command example

!fireeye-etp-get-alert alert_id= AWKMOs-2_r7_CWOc2okO

Raw Output
{
"data": [
{
"attributes": {
"meta": {
"read": false,
"last_modified_on": "2018-04-03T15:58:07.280",
"legacy_id": 52564988,
"acknowledged": false
},
"ati": {
"data": {
}
},
"alert": {
"product": "ETP",
"alert_type": [
"at"
],
"severity": "major",
"ack": "no",
"explanation": {
"analysis": "binary",
"anomaly": "",
"cnc_services": {
},
"malware_detected": {
"malware": [
{
"domain": "xxx.xxx.xx.xxx",
"downloaded_at": "2018-04-03T15:57:58Z",
"executed_at": "2018-04-03T15:57:59Z",
"name": "Phish.LIVE.DTI.URL",
"sid": "88000012",
"stype": "known-url",
"submitted_at": "2018-04-03T15:57:58Z"
}
]
},
"os_changes": [
],
"protocol": "",
"timestamp": "2018-04-03T15:57:59Z"
},
"timestamp": "2018-04-03T15:58:01.614",
"action": "notified",
"name": "malware-object"
},
"email": {
"status": "quarantined",
"source_ip": "xx.xxx.xxx.xx",
"smtp": {
"rcpt_to": "demisto@demisto.com",
"mail_from": "bot@demisto.com"
},
"etp_message_id": "76CF1709028AAAA5d61a8dbe",
"headers": {
"cc": "\u003cbot@soc.com\u003e|\u003csoc@bot.com\u003e",
"to": "\u003cdemisto@demisto.com\u003e",
"from": "bot@demisto.com",
"subject": "[CAT 6] HRA: Suspicious Executable | 11819"
},
"attachment": "hxxp://xxx.xxx.xx.xxx/shop/ok.exe',([System.IO.Path]::GetTempPath()+'\\KQEW.exe')",
"timestamp": {
"accepted": "2018-04-03T15:57:55"
}
}
},
"id": "AWKMOs-2_r7_CWOc2okO"
}
],
"meta": {
"total": 1,
"copyright": "Copyright 2017 Fireeye Inc."
},
"type": "alerts"
}