<chapter id="basic-usage">
<title>Basic usage</title>

<sect1 id="hdrsec">
<title>Getting headers and sections</title>

<para>
readpe is the right tool for parsing PE files without infer anything regarding
its fields and values. Using readpe you can see all basic PE file information.
For example, in order to see the <emphasis>Optional Header</emphasis>, you could
run:
</para>

<screen>
<prompt>$ </prompt><command>readpe --header optional putty.exe</command>
Optional/Image header
    Magic number:                    0x10b (PE32)
    Linker major version:            7
    Linker minor version:            10
    Size of .text section:           0x5c000
    Size of .data section:           0x27000
    Size of .bss section:            0
    Entrypoint:                      0x54eb0
    Address of .text section:        0x1000
    Address of .data section:        0x5d000
    ImageBase:                       0x400000
    Alignment of sections:           0x1000
    Alignment factor:                0x1000
    Major version of required OS:    4
    Minor version of required OS:    0
    Major version of image:          0
    Minor version of image:          0
    Major version of subsystem:      4
    Minor version of subsystem:      0
    Size of image:                   0x84000
    Size of headers:                 0x1000
    Checksum:                        0
    Subsystem required:              0x2 (IMAGE_SUBSYSTEM_WINDOWS_GUI)
    DLL characteristics:             0
    DLL characteristics names
    Size of stack to reserve:        0x100000
    Size of stack to commit:         0x1000
    Size of heap space to reserve:   0x100000
    Size of heap space to commit:    0x1000
</screen>

<tip><para>The Magic Number is 0x10b for PE32 files and 0x20b for PE32+ files.</para></tip>

<para>
In order to parse pev tools output you can use the -f / --format option. The following
example will output the <emphasis>DOS Header</emphasis> in HTML:
</para>

<screen>
<prompt>$ </prompt><command>readpe --format html --header dos putty.exe</command>
&lt;!DOCTYPE html&gt;
&lt;html lang="en" dir="ltr"&gt;
&lt;head&gt;
    &lt;meta charset="utf-8"&gt;
    &lt;title&gt;src/build/readpe --format html --header dos /home/user/PUTTY.EXE&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;div class="object"&gt;
        &lt;h2&gt;DOS Header&lt;/h2&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Magic number&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0x5a4d (MZ)&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Bytes in last page&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;144&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Pages in file&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;3&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Relocations&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Size of header in paragraphs&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;4&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Minimum extra paragraphs&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Maximum extra paragraphs&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;65535&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Initial (relative) SS value&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Initial SP value&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0xb8&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Initial IP value&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Initial (relative) CS value&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Address of relocation table&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0x40&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;Overlay number&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;OEM identifier&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;OEM information&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0&lt;/span&gt;&lt;/p&gt;
        &lt;p&gt;&lt;span class="key"&gt;&lt;b&gt;PE header offset&lt;/b&gt;&lt;/span&gt;: &lt;span class="value"&gt;0xf8&lt;/span&gt;&lt;/p&gt;
    &lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;
</screen>

<para>
By combining readpe output with a filter like grep you could easily get the PE file entrypoint in CSV format by filtering the readpe output:
</para>

<screen>
<prompt>$ </prompt><command>readpe --format csv --header optional putty.exe | grep ^Entry</command>
Entrypoint,0x4f125
</screen>

<para>
With readpe you can inspect the PE sections as well. Use -S option to see information about all PE sections, just
like this:
</para>

<screen>
<prompt>$ </prompt><command>readpe -S putty.exe</command>
Sections
    Section
        Name:                            .text
        Virtual Address:                 0x1000
        Physical Address:                0x5bd41
        Size:                            0x5c000 (376832 bytes)
        Pointer To Data:                 0x1000
        Relocations:                     0
        Characteristics:                 0x60000020
        Characteristic Names
                                             IMAGE_SCN_CNT_CODE
                                             IMAGE_SCN_MEM_EXECUTE
                                             IMAGE_SCN_MEM_READ
    Section
        Name:                            .rdata
        Virtual Address:                 0x5d000
        Physical Address:                0x1ceda
        Size:                            0x1d000 (118784 bytes)
        Pointer To Data:                 0x5d000
        Relocations:                     0
        Characteristics:                 0x40000040
        Characteristic Names
                                             IMAGE_SCN_CNT_INITIALIZED_DATA
                                             IMAGE_SCN_MEM_READ
    Section
        Name:                            .data
        Virtual Address:                 0x7a000
        Physical Address:                0x5924
        Size:                            0x2000 (8192 bytes)
        Pointer To Data:                 0x7a000
        Relocations:                     0
        Characteristics:                 0xc0000040
        Characteristic Names
                                             IMAGE_SCN_CNT_INITIALIZED_DATA
                                             IMAGE_SCN_MEM_READ
                                             IMAGE_SCN_MEM_WRITE
    Section
        Name:                            .rsrc
        Virtual Address:                 0x80000
        Physical Address:                0x3b90
        Size:                            0x4000 (16384 bytes)
        Pointer To Data:                 0x7c000
        Relocations:                     0
        Characteristics:                 0x40000040
        Characteristic Names
                                             IMAGE_SCN_CNT_INITIALIZED_DATA
                                             IMAGE_SCN_MEM_READ
</screen>
</sect1>

<sect1 id="functions">
<title>Looking at function directories</title>

<para>
readpe can show you the PE data directories with -d option, like this:
</para>

<screen>
<prompt>$ </prompt><command>readpe -d putty.exe</command>
Data directories
    Directory
        IMAGE_DIRECTORY_ENTRY_IMPORT:    0x78378 (240 bytes)
    Directory
        IMAGE_DIRECTORY_ENTRY_RESOURCE:  0x80000 (15248 bytes)
    Directory
        IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG: 0x78318 (72 bytes)
    Directory
        IMAGE_DIRECTORY_ENTRY_IAT:       0x5d000 (1292 bytes)
</screen>

<para>
If the executable has an import directory you may want to
see a list of imported functions with -i / --imports option:
</para>

<screen>
<prompt>$ </prompt><command>readpe -i putty.exe</command>
Imported functions
    Library
        Name:                            ADVAPI32.dll
        Functions
            Function
                Name:                            RegCloseKey
            Function
                Name:                            RegQueryValueExA
            Function
                Name:                            RegOpenKeyA
            Function
                Name:                            GetUserNameA
            Function
                Name:                            EqualSid
            Function
                Name:                            CopySid
    Library
        Name:                            COMCTL32.dll
        Functions
            Function
                Ordinal:                         14
            Function
                Ordinal:                         15
            Function
                Ordinal:                         17
            Function
                Ordinal:                         13
    Library
        Name:                            comdlg32.dll
        Functions
            Function
                Name:                            ChooseColorA
            Function
                Name:                            ChooseFontA
</screen>

<para>
You can see the exported functions as well by using readpe -e / --exports option.
</para>
</sect1>

<sect1 id="comparing">
<title>Comparing PE pieces</title>
<para>
With pehash you can calculate checksums of PE pieces and not only whole PE files.
You can for example compare two malwares by similarity using ssdeep. Have a look:
</para>

<screen>
<prompt>$ </prompt><command>pehash -s CODE ComentarioDeVoz_.cpl</command>
sections
    section
        section_name:                    CODE
        md5:                             67b498c232dfbe4f5cc0cabc5e78ac42
        sha1:                            32b5df9aaa201bc8cbfed37344aaa77bf842c1d4
        sha256:                          8f5b794da7fdbbc13f1abaae0949b4eb98935c99e7387c7e0dfef5d4f01ea298
        ssdeep:                          6144:2QrIKt9jjmVG0xcpcZTcLexXqS1XGtbNwI/4p3RLjD0OVG:2QrD3mVG0xcpcZTEexvXENv/e3RD0W
<prompt>$ </prompt><command>pehash -s CODE comentario.cpl</command>
sections
    section
        section_name:                    CODE
        md5:                             973d11759194c14071aa6963de8f55c7
        sha1:                            1934e0085c8776e3243bf658e95b8943d4f91bc9
        sha256:                          e68349bfcb04b20c11973ce27770570ebb22c8c7750133d073f15f7ec9eeda38
        ssdeep:                          6144:FQrIKt9jjmVG0xcpcZTcLexXqS1XGtbNwI/4p3Zv60G4:FQrD3mVG0xcpcZTEexvXENv/e3J6V
</screen>

<para>
Although the CODE section hashes of each files are different, their ssdeep checksum matches. So, you
could probably infer that these are variants.
</para>

<para>
You can also have the hash for each part using pehash without any option:
</para>

<screen>
<prompt>$ </prompt><command>pehash -a putty.exe</command>
file
    filepath:                        /home/user/putty.exe
    md5:                             33c9d1e56152e212367e9c5b01671e45
    sha1:                            9ded3ce2ae09c37ca173bbd3dcb57258b72cdbd5
    sha256:                          b10922648f6ad71f3f20b9acdfacf9aeff706cad6c52737cdc426307ccfa51d9
    ssdeep:                          12288:ApoNd4D7aVwSn8nW+nGQZZcLYX4RXwWLJQ6LU:UoNde7aVT8WvQ3O+4NzLu6w
    imphash:                         dae4485dd029c5e0256f477eda4797a4
headers
    header
        header_name:                     IMAGE_DOS_HEADER
        md5:                             5084c5d5cfe99932e67450023c068941
        sha1:                            856558429bb575486a46a92ba2684eaab8578cef
        sha256:                          52ea4dd296abe995cc1052a3a29325a8306fc888b3d6fea352d2cebdd83e6eaa
        ssdeep:                          3:WlWUqt/vllPln:idqH
    header
        header_name:                     IMAGE_COFF_HEADER
        md5:                             c29db8cff4c151279ea0f3e1e122bb92
        sha1:                            5df76c71b2fcb937b98d566dad7d353f23f23418
        sha256:                          4dc37a0d8a47d3c713b891a86b92acb28126729da2b7a6a5f3656d23fd8c1a9c
        ssdeep:                          3:OHwkn:wwk
    header
        header_name:                     IMAGE_OPTIONAL_HEADER
        md5:                             0de919344c187babea80d66adc2b0d9e
        sha1:                            4bdec527003b46348d8f9a1594f39f064e9dd680
        sha256:                          97e834e37ee922bca8a9388b2b1663491ddf0d3b20c6d37782aa4f2d1d9ebf64
        ssdeep:                          3:2H2l0lvl9gXH9lhtllrll3lll/ldt1l9tllH:NGlvA3
sections
    section
        section_name:                    .text
        md5:                             67b498c232dfbe4f5cc0cabc5e78ac42
        sha1:                            32b5df9aaa201bc8cbfed37344aaa77bf842c1d4
        sha256:                          8f5b794da7fdbbc13f1abaae0949b4eb98935c99e7387c7e0dfef5d4f01ea298
        ssdeep:                          6144:6poNd4D7aeaNqZs+iDpnRKnWDX/ZcnGs9BDT7JjZnZZGN+FAFtt6Xa//lrXwW:6poNd4D7aVwSn8nW+nGQZZcLYX4RXwW
    section
        section_name:                    .rdata
        md5:                             6087c2ffc1a7d69f82696a4f2d3aca75
        sha1:                            d69529b6402c520bdbee855c34ce4455112bd1eb
        sha256:                          30b49d20acb96827857ca125ce0d49838fafafe9d7e49523982b2ff1afe54283
        ssdeep:                          3072:mDBKmaes7rlYhoAw/Jt8Lr6hx3bO6ta/4gRul:mS+oAw/Jt836L3bA/
    section
        section_name:                    .data
        md5:                             5578c6fd3e5a0b764a7f2bcde00f9a16
        sha1:                            b71d5142594f56e896e79e12abf729e94512b9e0
        sha256:                          edd88e6b2ccf3dd5624ebd07b8911e2fa51f4ddc7912d4699ed111d28a2a53e5
        ssdeep:                          96:j/1HpvU2Ro26mTfOkf14dBPBgtbAgUhoSkb/:9o26sN2dJ9rIb/
    section
        section_name:                    .rsrc
        md5:                             24b45ea2b1620870730382fb7308a074
        sha1:                            bca5bc464c261f05751c24dce49d70458647e75c
        sha256:                          695707a6f3385838f6e5b58ab45584acb716bec2a2a953327dcb40314f0c0908
        ssdeep:                          192:Icgh8G2PnHGaAnkTjVDBY5disWxDgPWDSL73oqEnngLg:I5SG2vHi4jVDBKjPfL730ng0
</screen>

<para>
The OpenSSL library used by pev supports a wider range of hashing algorithms and you can extend pehash to use them by recompiling its source code.
</para>


</sect1>

<sect1 id="suspicious">
<title>Analyzing suspicious files</title>
<para>
Suspicious files are nice. We could probably think about lots of suspicious
characteristics that PE files may have and all we know is on pescan:
</para>

<screen>
<prompt>$ </prompt><command>pescan -v Nota.cpl </command>

file entropy:                    7.986840 (probably packed)
cpl analysis:                    malware
fpu anti-disassembly:            no
imagebase:                       normal - 0x400000
entrypoint:                      normal - va: 0x15c330 - raw: 0x65530
DOS stub:                        suspicious - raw: 0x40
TLS directory:                   not found
section count:                   3
.text:                           self-modifying
.rsrc:                           self-modifying
.reloc:                          small length
timestamp:                       normal - Wed, 26 Jun 2013 12:22:16 UTC
</screen>

<para>
pescan is the PE scanner program intented to find any suspicious characteristic
on it. It's good for an initial analysis. Further you can analyze things deeply
with readpe, pedis, peres and so on.
</para>

<para>
Strings are also good indicators in general PE file analysis. To avoid the problem with
Unicode and ASCII strings, we've developed our own strings dumper for PE files.
With pestr you know exactly where the string is inside the file and you don't need to
specify wether you are looking for ASCII or Unicode strings. pestr catches both.
</para>

<screen>
<prompt>$ </prompt><command>pestr --so dotnet.exe</command>
0x2a69c .text Button4
0x2a6a9 .text TextBox1
0x2a6b6 .text 3System.Resources.Tools.StronglyTypedResourceBuilder
0x2a6eb .text 4.0.0.0
0x2a6f7 .text KMicrosoft.VisualStudio.Editors.SettingsDesigner.SettingsSingleFileGenerator
0x2a744 .text 12.0.0.0
0x2a752 .text My.Settings
0x2a972 .text _CorExeMain
0x2a97e .text mscoree.dll
0x2be7c .rsrc IHDR
0x2be95 .rsrc pHYs
0x2beaa .rsrc IDATx
0x2c1bb .rsrc IEND
0x2d742 .rsrc VS_VERSION_INFO
0x2d79e .rsrc VarFileInfo
0x2d7be .rsrc Translation
0x2d7e2 .rsrc StringFileInfo
</screen>

<para>
All tools are provided with manpages. Check it out and discover what you
can do with pev. ;)
</para>

</sect1>
</chapter>
