Today I’ll show you how to use imap2thehive to pull emails from a mailbox, extract as many unique observables as possible, and generate a case in TheHive. It won’t be a long post as the author of imap2thehive has done an excellent job with his script and some small configuration changes are all that are required.
I’m assuming you already have a running instance of TheHive. If not, start with my post on TheHive installation.
Create a folder named imap2thehive and grab the files we need.
mkdir imap2thehive
cd imap2thehive/
wget https://github.com/xme/dockers/blob/master/imap2thehive/requirements.txt
wget https://github.com/xme/dockers/blob/master/imap2thehive/imap2thehive.whitelists
wget https://github.com/xme/dockers/blob/master/imap2thehive/imap2thehive.py
wget https://github.com/xme/dockers/blob/master/imap2thehive/imap2thehive.conf
Install the requirements.
pip install -r requirements.txt
Now go to your instance of TheHive and create a new user for these alerts. Generate an API key for the user. Note that this is the user that will be listed as the case Assignee.
Modify imap2thehive configuration settings.
nano imap2thehive.conf
Modify the connection settings for your mailbox. I’m connecting to GMail.
[imap]
host: imap.gmail.com
port: 993
user: <username>@gmail.com
password: <Password goes here>
folder: inbox
expunge: false
spam: (X-Spam-Flag: YES)
Note the renamed folder:
Modify the connection settings to find TheHive.
[thehive]
url: http://x.x.x.x:9000
apikey: <Paste API key here>
observables: true
whitelists: imap2thehive.whitelists
Under [alert] change the tlp: from 3 to 2. Having such a high alert prevents some analyzers from running in Cortex. Do the same under [case].
Create a new case template in TheHive for these emails or use an existing template. Replace template: thehive_template with the name of your template.
Also under [case] you’ll want to list all the mime types you want to ingest as observables for further analysis. GMail is perhaps different than other mail systems in this regard. I’m using files: application/octet-stream since trial-and-error told me that’s what I wanted.
To discover this I modified imap2thehive.py. After line 238 I added a line with print(filename), and after the mimetype = line I added a new line with print(mimetype). this will show you the mime type info in the console as the program runs.
else:
# Extract MIME parts
filename = part.get_filename()
print(filename)
mimetype = part.get_content_type()
print(mimetype)
if filename and mimetype:
Now you’re ready to run the script. I’d have just a single unread email with some IPs and URLs in the message body waiting in the mailbox you’re testing against.
python3 imap2thehive.py --config imap2thehive.conf
[WARNING]: Both case template and tasks are defined. Template (email_template) will be used.
[INFO]: Processing <username>@gmail.com@imap.gmail.com:993/inbox
[INFO]: Connected to IMAP server.
[INFO]: 1 unread messages to process
[INFO]: From: Arnaud <xxxxxx@arnaudloos.com> Subject: Test Email
None
multipart/mixed
None
multipart/alternative
Evilpdf.pdf
application/octet-stream
[INFO]: Found attachment: Evilpdf.pdf (application/octet-stream)
Maliciousdoc.docx
application/octet-stream
[INFO]: Found attachment: Maliciousdoc.docx (application/octet-stream)
MaliciousExcel.xls
application/octet-stream
[INFO]: Found attachment: MaliciousExcel.xls (application/octet-stream)
[DEBUG]: Found observable url: https://maliciousurl.com/files/content/page.hta
[DEBUG]: Found observable ip: 103.14.229.253
[DEBUG]: Found observable ip: 103.25.58.34
[DEBUG]: Found observable ip: 1.186.77.13
[DEBUG]: Found observable ip: 73.164.105.200
[DEBUG]: Found observable domain: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[DEBUG]: Found observable domain: maliciousurl.com
[DEBUG]: Found observable mail: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: https://maliciousurl.com/files/content/page.hta
[INFO]: Ignoring duplicate observable: 103.14.229.253
[INFO]: Ignoring duplicate observable: 103.25.58.34
[INFO]: Ignoring duplicate observable: 1.186.77.13
[INFO]: Ignoring duplicate observable: 73.164.105.200
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: maliciousurl.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: https://maliciousurl.com/files/content/page.hta
[INFO]: Ignoring duplicate observable: https://maliciousurl.com/files/content/page.hta
[INFO]: Ignoring duplicate observable: 103.14.229.253
[INFO]: Ignoring duplicate observable: 103.25.58.34
[INFO]: Ignoring duplicate observable: 1.186.77.13
[INFO]: Ignoring duplicate observable: 73.164.105.200
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: maliciousurl.com
[INFO]: Ignoring duplicate observable: maliciousurl.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: https://maliciousurl.com/files/content/page.hta
[INFO]: Ignoring duplicate observable: 103.14.229.253
[INFO]: Ignoring duplicate observable: 103.25.58.34
[INFO]: Ignoring duplicate observable: 1.186.77.13
[INFO]: Ignoring duplicate observable: 73.164.105.200
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: maliciousurl.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: https://maliciousurl.com/files/content/page.hta
[INFO]: Ignoring duplicate observable: 103.14.229.253
[INFO]: Ignoring duplicate observable: 103.25.58.34
[INFO]: Ignoring duplicate observable: 1.186.77.13
[INFO]: Ignoring duplicate observable: 73.164.105.200
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: maliciousurl.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: https://maliciousurl.com/files/content/page.hta
[INFO]: Ignoring duplicate observable: https://maliciousurl.com/files/content/page.hta
[INFO]: Ignoring duplicate observable: 103.14.229.253
[INFO]: Ignoring duplicate observable: 103.25.58.34
[INFO]: Ignoring duplicate observable: 1.186.77.13
[INFO]: Ignoring duplicate observable: 73.164.105.200
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: arnaudloos.com
[INFO]: Ignoring duplicate observable: maliciousurl.com
[INFO]: Ignoring duplicate observable: maliciousurl.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Ignoring duplicate observable: xxxxxx@arnaudloos.com
[INFO]: Removed duplicate observables: 72 -> 8
[DEBUG]: Searching for \S*(ALERT|VTMIS)\S* in 'Fwd: test 18'
[INFO]: Created case 29
[INFO]: Added observable /tmp/Evilpdf.pdf to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable /tmp/Maliciousdoc.docx to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable /tmp/MaliciousExcel.xls to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable url: https://maliciousurl.com/files/content/page.hta to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable ip: 103.14.229.253 to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable ip: 103.25.58.34 to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable ip: 1.186.77.13 to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable ip: 73.164.105.200 to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable domain: arnaudloos.com to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable domain: maliciousurl.com to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Added observable mail: xxxxxx@arnaudloos.com to case ID AWoEXp2TI5SmE1Wz2WvB
[INFO]: Message 33 successfully processed and flagged as read
Notice how the script elegently trims the number of observables down to just the unique entries.
You should now see a newly created Case in TheHive dashboard.