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 
category: Messaging and Conferencing
provider: Open Source
sectionorder:
- Connect
- Collect
commonfields:
  id: Mail Listener v2
  version: -1
configuration:
- display: Mail Server Hostname / IP address
  name: MailServerURL
  required: true
  type: 0
  section: Connect
- defaultvalue: '143'
  display: IMAP Port
  name: port
  required: true
  type: 0
  section: Connect
- display: Username
  name: credentials
  required: true
  type: 9
  section: Connect
- displaypassword: Client Certificate And Private Key (List of PEMs)
  display: ""
  name: clientCertAndKey
  required: false
  section: Connect
  type: 9
  advanced: true
  hiddenusername: true
- defaultvalue: INBOX
  display: Incoming mail folder
  name: folder
  required: true
  type: 0
  section: Connect
- display: Fetch incidents
  name: isFetch
  type: 8
  section: Collect
  required: false
- display: Incident type
  name: incidentType
  type: 13
  section: Connect
  required: false
- display: Incidents Fetch Interval
  name: incidentFetchInterval
  defaultvalue: '1'
  required: false
  type: 19
  section: Collect
  advanced: true
- display: Fetch mails from these senders addresses only (eg. admin@demo.com,test@demo.com)
  name: permittedFromAdd
  type: 0
  section: Collect
  advanced: true
  required: false
- display: Fetch mails from these domains only (eg. demo.com, test.com)
  name: permittedFromDomain
  type: 0
  section: Collect
  advanced: true
  required: false
- defaultvalue: 'false'
  additionalinfo: Whether to query search with headers when filtering by sender's email address.
  display: Query search with headers
  name: with_headers
  type: 8
  section: Collect
  advanced: true
  required: false
- defaultvalue: 1 hour
  display: First fetch time
  name: first_fetch
  type: 0
  section: Collect
  required: false
- defaultvalue: '50'
  display: The maximum number of incidents to fetch each time
  name: limit
  type: 0
  section: Collect
  required: false
- display: Delete processed emails
  name: delete_processed
  type: 8
  section: Collect
  advanced: true
  required: false
- display: Include raw body in incidents
  name: Include_raw_body
  type: 8
  section: Collect
  advanced: true
  required: false
- display: Save the email .eml file
  name: save_file
  type: 8
  section: Collect
  advanced: true
  required: false
- display: Fetch by email date
  name: date_fetch
  type: 8
  defaultvalue: 'true'
  section: Collect
  advanced: true
  required: false
  additionalinfo: Whether to fetch by email date.
- defaultvalue: 'true'
  display: Use TLS for connection (defaults to True)
  name: TLS_connection
  type: 8
  section: Connect
  advanced: true
  required: false
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  section: Connect
  advanced: true
  required: false
description: Listens to a mailbox and enables incident triggering via e-mail.
display: Mail Listener v2
name: Mail Listener v2
script:
  commands:
  - description: Retrieves emails according to the configuration.
    name: mail-listener-list-emails
    outputs:
    - contextPath: MailListener.EmailPreview.Subject
      description: The subject of the email.
      type: String
    - contextPath: MailListener.EmailPreview.Date
      description: The date when the mail was received.
      type: Date
    - contextPath: MailListener.EmailPreview.To
      description: The recipient of the email.
      type: String
    - contextPath: MailListener.EmailPreview.From
      description: The sender of the email.
      type: String
    - contextPath: MailListener.EmailPreview.ID
      description: The ID of the email.
      type: string
  - arguments:
    - description: The message ID retrieved from the 'mail-listener-list-emails' command.
      name: message-id
      required: true
    description: Retrieves an email by email ID.
    name: mail-listener-get-email
    outputs:
    - contextPath: MailListener.Email.to
      description: The recipients of the email.
      type: String
    - contextPath: MailListener.Email.cc
      description: The cc of the email.
      type: String
    - contextPath: MailListener.Email.bcc
      description: The bcc of the email.
      type: String
    - contextPath: MailListener.Email.from
      description: The sender of the email.
      type: String
    - contextPath: MailListener.Email.format
      description: The format of the email.
      type: String
    - contextPath: MailListener.Email.text
      description: The plain text of the email.
      type: String
    - contextPath: MailListener.Email.HTML
      description: The HTML display of the email, if it exists.
      type: String
    - contextPath: MailListener.Email.subject
      description: The subject of the email.
      type: String
    - contextPath: MailListener.Email.attachments
      description: The attachments of the email, if it exists.
      type: String
    - contextPath: MailListener.Email.headers
      description: The headers of the email.
      type: String
  - arguments:
    - description: The message ID retrieved from the 'mail-listener-list-emails' command.
      name: message-id
      required: true
    description: Fetches an email by message ID and returns the information in an eml file format.
    name: mail-listener-get-email-as-eml
  dockerimage: demisto/py3-tools:1.0.0.10120494
  isfetch: true
  runonce: false
  script: '-'
  subtype: python3
  type: python
tests:
- Mail-Listener Test Playbook
defaultmapperin: mail-listener-mapper
defaultclassifier: mail-listener
fromversion: 5.0.0