mail_to_misp

Build Status codecov

mail_to_misp

Connect your mail infrastructure to MISP in order to create events based on the information contained within mails.

Features

You can send mails with attachments to mail_to_misp and tell it, to treat the attachment as a benign document (in contrast to the default behaviour: treating it as a malware sample). You need to set a keyword in the configuration: m2m_attachment_keyword = 'attachment:benign'

For OSINT collection purposes (like collecting URLs to OSINT reports), you can tell mail_to_misp to only extract URLs (--urlsonly) and append them to a predefined MISP event (--event N). The subject of such a mail goes into the comment field of the value.

Example:

osinturlcollection: "|/path/to/mail_to_misp.py --urlsonly --event 12345 -"

Pass parameters in the email body

m2m:<parameter>:<Value>

# Examples
m2m:attachment:benign  # Email attachment considered benign (attachment in MISP, malware-sample by default)
m2m:attach_original_mail:1  # Attach the full original email to the MISP Event (may contain private information)

m2m:m2mkey:YOUSETYOURKEYHERE  # Key required for some actions
# The following key are ignored if M2M:m2mkey is invalid
m2m:distribution:<0-3,5> # Note: impossible to pass a sharing group yet.
m2m:threat_level:<0-2>
m2m:analysis:<0-3>
m2m:publish:1  # Autopublish

Implementation

The implemented workflow is mainly for mail servers like Postfix. Client side implementations exist but are no longer supported:

  1. Postfix and others

Email -> mail_to_misp

  1. Office 365

Email -> Outlook -> O365MISPClient -> mail_to_misp

  1. Apple Mail [unmaintained]

Email -> Apple Mail -> Mail rule -> AppleScript -> mail_to_misp -> PyMISP -> MISP

  1. Mozilla Thunderbird [unmaintained]

Email -> Thunderbird -> Mail rule -> filterscript -> thunderbird_wrapper -> mail_to_misp -> PyMISP -> MISP

Installation

Postfix (or other MTA) - preferred method

  1. Setup a new email address in the aliases file (e.g. /etc/aliases) and configure the correct path:

misp_handler: "|/path/to/mail_to_misp.py -"

  1. Rebuild the DB:

$ sudo newaliases

  1. Configure mail_to_misp_config.py

You should now be able to send your IoC-containing mails to misp_handler@YOURDOMAIN.

Bonus: Fake-SMTPD spamtrap

If you want to process all incoming junk mails automatically and collect the contained information in a separate throw-away MISP instance, you could use the fake_smtp.py script. It listens on port 25, accepts all mails and pushes them through mail_to_misp to a MISP instance. It can also be configured to listen on an SSL port. (465)

  1. Configure mail_to_misp_config.py

  2. cp fake_smtp_config.py-example fake_smtp_config.py

  3. Make port 25 accessible to normal users

$ sudo apt install authbind
$ sudo touch /etc/authbind/byport/25
$ sudo chown misp:misp /etc/authbind/byport/25
$ sudo chmod 770 /etc/authbind/byport/25
  1. Run fake_smtp.py

$ python3 fake_smtp.py

Office 365

Run mail_to_misp_o365.py to get the last 1 day of messages

$ python3 mail_to_misp_0365.py -nd 1

Apple Mail [unmaintained]

  1. Mail rule script
    • git clone this repository
    • open the AppleScript file MUA/Apple/Mail/MISP Mail Rule Action.txt in Apple’s ‘Script Editor’
    • adjust the path to the python installation and location of the mail_to_misp.py script
    • save it in ~/Library/Application Scripts/com.apple.mail/
  2. Create a mail rule based on your needs, executing the AppleScript defined before
  3. Configure mail_to_misp_config.py

Thunderbird [unmaintained]

  1. Git clone https://github.com/rommelfs/filterscript and install plugin (instructions within the project description)
  2. Mail rule script
    • git clone this repository
    • open the bash script MUA/Mozilla/Thunderbird/thunderbird_wrapper.sh and adujst the paths
    • adjust the path to the python installation and location of the mail_to_misp.py script
  3. Create a mail rule based on your needs, executing the thunderbird_wrapper.sh script
  4. Configure mail_to_misp_config.py

You should be able to create MISP events now.

Outlook [unmaintained]

Outlook is not implemented due to lack of test environment. However, it should be feasible to do it this way:

import win32com.client
import pythoncom

class Handler_Class(object):
    def OnNewMailEx(self, receivedItemsIDs):
        for ID in receivedItemsIDs.split(","):
            # Microsoft.Office.Interop.Outlook _MailItem properties:
            # https://msdn.microsoft.com/en-us/library/microsoft.office.interop.outlook._mailitem_properties.aspx
            mailItem = outlook.Session.GetItemFromID(ID)
            print "Subj: " + mailItem.Subject
            print "Body: " + mailItem.Body.encode( 'ascii', 'ignore' )
            print "========"

outlook = win32com.client.DispatchWithEvents("Outlook.Application", Handler_Class)
pythoncom.PumpMessages()

(from: https://blog.matthewurch.ca/?p=236)

Obviously, you would like to filter mails based on subject or from address and pass subject and body to mail_to_misp.py in order to do something useful. Pull-requests welcome for actual implementations :)

Requirements

The easy way

pip install --user poetry

# Install other python requirements
poetry install -E fileobjects -E openioc -E virustotal -E email -E url

# Test if the script is working
./mail_to_misp.py -h

General

Office 365

Thunderbird [unmaintained]

License

This software is licensed under GNU Affero General Public License version 3

This site is open source. Improve this page.