Didier Stevens

cut-bytes.py is a stand-alone program that implements the –cut option found in my dump programs.

cut-bytes_V0_0_1.zip (https)
MD5: 48CEBD6748E152CBF619EF10B58E8DFF
SHA256: E99BC09DA0F1310085ED1520D52FB188D06456D030BD05A941FCE2B5FE21A661

This new version of emldump comes with the new –cut option. And with support for YARA. Take a look at the man page (emldump.py –man):

Usage: emldump.py [options] [mimefile]
EML dump utility

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -m, --man             Print manual
  -d, --dump            perform dump
  -x, --hexdump         perform hex dump
  -a, --asciidump       perform ascii dump
  -H, --header          skip first line
  -s SELECT, --select=SELECT
                        select item nr or MIME type for dumping
  -y YARA, --yara=YARA  YARA rule file (or directory or @file) to check
                        streams (YARA search doesn't work with -s option)
  --yarastrings         Print YARA strings
  -D DECODERS, --decoders=DECODERS
                        decoders to load (separate decoders with a comma , ;
                        @file supported)
  --decoderoptions=DECODEROPTIONS
                        options for the decoder
  -v, --verbose         verbose output with decoder errors
  -c CUT, --cut=CUT     cut data

Manual:

emldump is a tool to analyze MIME files.
The MIME file can be provided as an argument, via stdin (piping) and it may
also be contained in a (password protected) ZIP file.
When emldump runs on a MIME file without any options, it reports the different
parts in the MIME file. Like in this example:

emldump.py sample.vir
1: M         multipart/alternative
2:       610 text/plain
3: M         multipart/related
4:      1684 text/html
5:    133896 application/octet-stream

The first number is an index added by emldump (this index does not come from
the MIME file). This index can be used to select a part.
If a part has an M indicator, then it is a multipart and can not be selected.
Next is the number of bytes in the part, and the MIME type of the part.

Some MIME files start with an info line that has to be skipped. For example
e-mails saved with Lotus Notes. Skipping this first line can be done with
option -H.

A particular part of the MIME file can be selected for further analysis with
option -s. Here is an example where we use the index 2 to select the second
part:

emldump.py sample.vir -s 2
00000000: 20 20 20 0D 0A 20 20 20 41 20 63 6F 70 79 20 6F     ..   A copy o
00000010: 66 20 79 6F 75 72 20 41 44 50 20 54 6F 74 61 6C  f your ADP Total
00000020: 53 6F 75 72 63 65 20 50 61 79 72 6F 6C 6C 20 49  Source Payroll I
00000030: 6E 76 6F 69 63 65 20 66 6F 72 20 74 68 65 20 66  nvoice for the f
00000040: 6F 6C 6C 6F 77 69 6E 67 20 70 61 79 72 6F 6C 6C  ollowing payroll
...

When a part is selected, by default the content of the part is dumped in
HEX/ASCII format (option -a). An hexdump can be obtained with option -x, like
in this example:

emldump.py sample.vir -s 2 -x
20 20 20 0D 0A 20 20 20 41 20 63 6F 70 79 20 6F
66 20 79 6F 75 72 20 41 44 50 20 54 6F 74 61 6C
53 6F 75 72 63 65 20 50 61 79 72 6F 6C 6C 20 49
6E 76 6F 69 63 65 20 66 6F 72 20 74 68 65 20 66
6F 6C 6C 6F 77 69 6E 67 20 70 61 79 72 6F 6C 6C
20 69 73 09 20 20 20 69 73 20 61 74 74 61 63 68

The raw content of the part can be dumped too with option -d. This can be used
to redirect to a file or piped into another analysis program.

Option -s (select) takes an index number, but can also take a MIME type, like
in this example:
emldump.py sample.vir -s text/plain

emldump can scan the content of the parts with YARA rules (the YARA Python
module must be installed). You provide the YARA rules with option -y. You can
provide one file with YARA rules, an at-file (@file containing the filenames
of the YARA files) or a directory. In case of a directory, all files inside
the directory are read as YARA files. All parts are scanned with the provided
YARA rules, you can not use option -s to select an individual part.

Content of example.eml:
emldump.py example.eml
1: M         multipart/mixed
2:        32 text/plain
3:    114704 application/octet-stream

YARA example:
emldump.py -y contains_pe_file.yara example.eml
3:    114704 application/octet-stream contains_pe_file.yara Contains_PE_File

In this example, you use YARA rule contains_pe_file.yara to find PE files
(executables) inside MIME files. The rule triggered for part 3, because it
contains an EXE file encoded in BASE64.

If you want more information about what was detected by the YARA rule, use
option --yarastrings like in this example:
emldump.py -y contains_pe_file.yara --yarastrings example.eml
3:    114704 application/octet-stream contains_pe_file.yara Contains_PE_File
 000010 $a 4d5a 'MZ'
 0004e4 $a 4d5a 'MZ'
 01189f $a 4d5a 'MZ'

YARA rule contains_pe_file detects PE files by finding string MZ followed by
string PE at the correct offset (AddressOfNewExeHeader).
The rule looks like this:
rule Contains_PE_File
{
    meta:
        author = "Didier Stevens (https://DidierStevens.com)"
        description = "Detect a PE file inside a byte sequence"
        method = "Find string MZ followed by string PE at the correct offset
(AddressOfNewExeHeader)"
    strings:
        $a = "MZ"
    condition:
        for any i in (1..#a): (uint32(@a[i] + uint32(@a[i] + 0x3C)) ==
0x00004550)
}

maldoc.yara are YARA rules to detect shellcode, based on Frank Boldewin's
shellcode detector used in OfficeMalScanner.

When looking for traces of Windows executable code (PE files, shellcode, ...)
with YARA rules, one must take into account the fact that the executable code
might have been encoded (for example via XOR and a key) to evade detection.
To deal with this possibility, emldump supports decoders. A decoder is another
type of plugin, that will bruteforce a type of encoding on each part. For
example, decoder_xor1 will encode each part via XOR and a key of 1 byte. So
effectively, 256 different encodings of the part will be scanned by the YARA
rules. 256 encodings because: XOR key 0x00, XOR key 0x01, XOR key 0x02, ...,
XOR key 0xFF
Here is an example:
emldump.py -y contains_pe_file.yara -D decoder_xor1 example-xor.eml
3:    114704 application/octet-stream contains_pe_file.yara Contains_PE_File
(XOR 1 byte key 0x14)

The YARA rule triggers on part 3. It contains a PE file encoded via XORing
each byte with 0x14.

You can specify more than one decoder separated by a comma ,.
emldump.py -y contains_pe_file.yara -D decoder_xor1,decoder_rol1,decoder_add1
example-xor.eml
3:    114704 application/octet-stream contains_pe_file.yara Contains_PE_File
(XOR 1 byte key 0x14)

Some decoders take options, to be provided with option --decoderoptions.

Option -c (--cut) allows for the partial selection of a stream. Use this
option to "cut out" part of the stream.
The --cut option takes an argument to specify which section of bytes to select
from the stream. This argument is composed of 2 terms separated by a colon
(:), like this:
termA:termB
termA and termB can be:
- nothing (an empty string)
- a positive number; example: 10
- an hexadecimal number (to be preceded by 0x); example: 0x10
- a case sensitive string to search for (surrounded by square brackets and
single quotes); example: ['MZ']
- an hexadecimal string to search for (surrounded by square brackets);
example: [d0cf11e0]
If termA is nothing, then the cut section of bytes starts with the byte at
position 0.
If termA is a number, then the cut section of bytes starts with the byte at
the position given by the number (first byte has index 0).
If termA is a string to search for, then the cut section of bytes starts with
the byte at the position where the string is first found. If the string is not
found, the cut is empty (0 bytes).
If termB is nothing, then the cut section of bytes ends with the last byte.
If termB is a number, then the cut section of bytes ends with the byte at the
position given by the number (first byte has index 0).
When termB is a number, it can have suffix letter l. This indicates that the
number is a length (number of bytes), and not a position.
If termB is a string to search for, then the cut section of bytes ends with
the last byte at the position where the string is first found. If the string
is not found, the cut is empty (0 bytes).
No checks are made to assure that the position specified by termA is lower
than the position specified by termB. This is left up to the user.
Examples:
This argument can be used to dump the first 256 bytes of a PE file located
inside the stream: ['MZ']:0x100l
This argument can be used to dump the OLE file located inside the stream:
[d0cf11e0]:
When this option is not used, the complete stream is selected.

emldump_V0_0_3.zip (https)
MD5: FB080006C2653F3A2AD6E889FC957D5F
SHA256: 0D55DE704BDE558B6E8E5F823C513F19F8A5FD5B2A97BB8BD5EBB5FAD18FA658