Mail Listener v2

Listens to a mailbox and enables incident triggering via e-mail.

Messaging and Conferencing · Mail Listener

Details

IDMail Listener v2
ProviderOpen Source
CategoryMessaging and Conferencing
From Version5.0.0
Docker Imagedemisto/py3-tools:1.0.0.10120494
Supported ModulesAgentix XSIAM

README

Overview

Listens to a mailbox and enables incident triggering via e-mail.

Configure Mail Listener v2 in Cortex

Parameter Description Required
Mail Server Hostname / IP address   True
IMAP Port Default is 143. True
Username   True
Incoming mail folder Default is INBOX. True
Fetch incidents   False
Incident type   False
Fetch mails from these senders addresses only (eg. admin@demo.com,test@demo.com)   False
Fetch mails from these domains only (eg. demo.com, test.com)   False
Query search with headers Whether to query search with headers when filtering by sender’s email address. Default is false. False
First fetch time Default is 1 hour. False
The maximum number of incidents to fetch each time Default is 50. False
Delete processed emails   False
Include raw body in incidents   False
Save the email .eml file   False
Fetch by email date Whether to fetch by email date. Default is true. False
Use TLS for connection (defaults to True) Default is true. False
Trust any certificate (not secure)   False
Client Certificate And Private Key (List of PEMs)   False

Commands

mail-listener-list-emails

Fetch mails according to the configuration

Base Command

mail-listener-list-emails

Input

There are no input arguments for this command.

Context Output

Path Type Description
MailListener.EmailPreview.Subject String The subject of the mail
MailListener.EmailPreview.Date Date The date when the mail was received.
MailListener.EmailPreview.To String The recipient of the mail.
MailListener.EmailPreview.From String The sender of the mail.
MailListener.EmailPreview.ID string The ID of the mail.

Command Example


#### Context Example

{
“MailListener”: {
“EmailPreview”: {
“Date”: “2020-08-12T11:13:35+00:00”,
“From”: “test@demistodev.com”,
“ID”: 65445,
“Subject”: “foooSubject”,
“To”: [
“test@demistodev.com”
]
}
}
}


#### Human Readable Output

>### Results
>
>|Date|From|ID|Subject|To|
>|---|---|---|---|---|
>| 2020-08-12T11:13:35+00:00 | test@demistodev.com | 65445 | foooSubject | test@demistodev.com |

### mail-listener-get-email

***
Fetches an email by email ID

#### Base Command

`mail-listener-get-email`

#### Input

| **Argument Name** | **Description** | **Required** |
| --- | --- | --- |
| message-id | Message ID as fetched in 'mail-listener-list-emails' command. | Required |

#### Context Output

| **Path** | **Type** | **Description** |
| --- | --- | --- |
| MailListener.Email.to | String | The recipients of the mail. |
| MailListener.Email.cc | String | The mail's cc. |
| MailListener.Email.bcc | String | The mail's bcc. |
| MailListener.Email.from | String | The sender of the mail. |
| MailListener.Email.format | String | The format of the mail. |
| MailListener.Email.text | String | The plain text of the mail. |
| MailListener.Email.HTML | String | The HTML display of the mail if exists. |
| MailListener.Email.subject | String | The subject of the mail. |
| MailListener.Email.attachments | String | The attachments of the mail if exists. |
| MailListener.Email.headers | String | The headers of the mail. |

#### Command Example

```!mail-listener-get-email message-id=65445```

#### Context Example

{
“MailListener”: {
“Email”: {
“attachments”: [],
“bcc”: “”,
“cc”: “”,
“format”: “text/plain”,
“from”: “test@demistodev.com”,
“headers”: {
“Content-Transfer-Encoding”: “quoted-printable”,
“Content-Type”: “text/plain; charset=UTF-8”,
“Date”: “Wed, 12 Aug 2020 11:13:35 +0000”,
“From”: “test@demistodev.com”,
“Message-ID”: “5f33cedf.1c69fb81.e5562.38a5@mx.google.com”,
“Mime-Version”: “1.0”,
“Received”: “from localhost (13.100.68.34.bc.googleusercontent.com. [192.0.0.1])\r\n by smtp.gmail.com with ESMTPSA id t5sm917197ilp.15.2020.08.12.04.13.35\r\n for test@demistodev.com\r\n (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);\r\n Wed, 12 Aug 2020 04:13:35 -0700 (PDT)”,
“Return-Path”: “test@demistodev.com”,
“Subject”: “foooSubject”,
“To”: “test@demistodev.com”,
“X-Google-Original-From”: “koko@demisto.com”
},
“rawHeaders”: “Return-Path: test@demistodev.com\nReceived: from localhost (13.100.68.34.bc.googleusercontent.com. [34.68.100.13])\r\n by smtp.gmail.com with ESMTPSA id t5sm917197ilp.15.2020.08.12.04.13.35\r\n for test@demistodev.com\r\n (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);\r\n Wed, 12 Aug 2020 04:13:35 -0700 (PDT)\nMessage-ID: 5f33cedf.1c69fb81.e5562.38a5@mx.google.com\nFrom: test@demistodev.com\nX-Google-Original-From: koko@demisto.com\nMime-Version: 1.0\nDate: Wed, 12 Aug 2020 11:13:35 +0000\nTo: test@demistodev.com\nSubject: foooSubject\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: quoted-printable”,
“subject”: “foooSubject”,
“text”: “foooBody”,
“to”: “test@demistodev.com”
}
}
}


#### Human Readable Output

>### Results
>
>|attachments|bcc|cc|format|from|headers|rawHeaders|subject|text|to|
>|---|---|---|---|---|---|---|---|---|---|
>|  |  |  | text/plain | test@demistodev.com | Return-Path: <test@demistodev.com><br/>Received: from localhost (13.100.68.34.bc.googleusercontent.com. [34.68.100.13])<br/>        by smtp.gmail.com with ESMTPSA id t5sm917197ilp.15.2020.08.12.04.13.35<br/>        for <test@demistodev.com><br/>        (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);<br/>        Wed, 12 Aug 2020 04:13:35 -0700 (PDT)<br/>Message-ID: <5f33cedf.1c69fb81.e5562.38a5@mx.google.com><br/>From: test@demistodev.com<br/>X-Google-Original-From: koko@demisto.com<br/>Mime-Version: 1.0<br/>Date: Wed, 12 Aug 2020 11:13:35 +0000<br/>To: test@demistodev.com<br/>Subject: foooSubject<br/>Content-Type: text/plain; charset=UTF-8<br/>Content-Transfer-Encoding: quoted-printable | Return-Path: <test@demistodev.com><br/>Received: from localhost (13.100.68.34.bc.googleusercontent.com. [34.68.100.13])<br/>        by smtp.gmail.com with ESMTPSA id t5sm917197ilp.15.2020.08.12.04.13.35<br/>        for <test@demistodev.com><br/>        (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);<br/>        Wed, 12 Aug 2020 04:13:35 -0700 (PDT)<br/>Message-ID: <5f33cedf.1c69fb81.e5562.38a5@mx.google.com><br/>From: test@demistodev.com<br/>X-Google-Original-From: koko@demisto.com<br/>Mime-Version: 1.0<br/>Date: Wed, 12 Aug 2020 11:13:35 +0000<br/>To: test@demistodev.com<br/>Subject: foooSubject<br/>Content-Type: text/plain; charset=UTF-8<br/>Content-Transfer-Encoding: quoted-printable | foooSubject | foooBody | test@demistodev.com |

### mail-listener-get-email-as-eml

***
Fetches an email by message ID and download it's eml file

#### Base Command

`mail-listener-get-email-as-eml`

#### Input

| **Argument Name** | **Description** | **Required** |
| --- | --- | --- |
| message-id | Message ID as fetched in 'mail-listener-list-emails' command. | Required |

#### Context Output

There is no context output for this command.

#### Command Example

```!mail-listener-get-email-as-eml message-id=65445```

#### Context Example

{
“File”: {
“EntryID”: “1276@97a9b81e-928e-4c93-80bc-2729ca35cb1c”,
“Extension”: “eml”,
“Info”: “message/rfc822”,
“MD5”: “4411c30b672dd8fee62d332c970e07bb”,
“Name”: “original-email-file.eml”,
“SHA1”: “1713dc8369f89bc1c3f665eeffc3a2b7de4c2f7b”,
“SHA256”: “d6e145175a9abd9b51f3af71a6a4971ec922888addd2f96cdd484c52ff6fcb43”,
“SHA512”: “0b4af9cd6899e15fcbb3fbdde4592ccd44f681769c554afd437214984cdc254923167563e6d7b763bb96cc3de40f684e9852ec2617ba90efdf6d9342564dddfd”,
“SSDeep”: “12:k11sxpBGVTdLS4NuFWsRqzR2kAmM4YTxXX6oFTrYQWptR9zHxXARx2mi7xoQFQ0f:SydGVTdLS4cJGRzCT96odcpHR2x2milL”,
“Size”: 680,
“Type”: “SMTP mail text, ASCII text, with CRLF line terminators”
}
}
```

Additional Information

  • In the first fetch iteration, some emails may be skipped and not fetched as incidents - the integration will fetch just the last available emails for the given day, as set in The maximum number of incidents to fetch each time and First fetch time. This behavior is due to the fact that IMAP time filter is limited to day based filter.

    Subsequent fetch iterations should fetch emails as they are received, without further issue.

  • The occurred time for emails with no received date field will be the time it was fetched to the system.

Configuration parameters

  • MailServerURL — Mail Server Hostname / IP address (required)
  • port — IMAP Port (required)
  • credentials — Username (required)
  • clientCertAndKey —
  • folder — Incoming mail folder (required)
  • isFetch — Fetch incidents
  • incidentType — Incident type
  • incidentFetchInterval — Incidents Fetch Interval
  • permittedFromAdd — Fetch mails from these senders addresses only (eg. admin@demo.com,test@demo.com)
  • permittedFromDomain — Fetch mails from these domains only (eg. demo.com, test.com)
  • with_headers — Query search with headers
  • first_fetch — First fetch time
  • limit — The maximum number of incidents to fetch each time
  • delete_processed — Delete processed emails
  • Include_raw_body — Include raw body in incidents
  • save_file — Save the email .eml file
  • date_fetch — Fetch by email date
  • TLS_connection — Use TLS for connection (defaults to True)
  • insecure — Trust any certificate (not secure)

Commands (3)

  • mail-listener-get-email

    Retrieves an email by email ID.

  • mail-listener-get-email-as-eml

    Fetches an email by message ID and returns the information in an eml file format.

  • mail-listener-list-emails

    Retrieves emails according to the configuration.

Source

MailListenerV2.py MailListenerV2_test.py MailListenerV2.yml MailListenerV2_description.md command_examples.txt
Download History Raw 
This integration allows listening to a mailbox and spawn an incident from the receipt of the email.
While this integration is designed to work with any IMAP server such as AT&T, Yahoo, BT Connect, etc.
If You are using Exchange on-premise, Exchange Online, or Gmail - we do recommend working with the product specific integrations.

If the IMAP server requires client certificates and private keys, please configure the **Client Certificate And Private Key (List of PEMs)** parameter with the appropriate keys.