initial project files

README.md

@@ -0,0 +1,75 @@
+# Portable Executable Parser
+
+**peparser** is a go package for parsing the [portable executable](https://docs.microsoft.com/en-us/windows/win32/debug/pe-format) file format. This package was designed with malware analysis in mind, and being resistent to PE malformations.
+
+## Features
+
+- Works with PE32/PE32+ file fomat.
+- Supports Intel x86/AMD64/ARM7ARM7 Thumb/ARM8-64/IA64/CHPE architectures.
+- MS DOS header.
+- Rich Header (calculate checksum).
+- NT Header (file header + optional header).
+- COFF symbol table and string table.
+- Sections headers + entropy calculation. 
+- Data directories
+ - Import Table + ImpHash calculation.
+ - Export Table
+ - Resource Table
+ - Exceptions Table
+ - Security Table + Authentihash calculation.
+ - Relocations Table
+ - Debug Table (CODEVIEW, POGO, VC FEATURE, REPRO, FPO, EXDLL CHARACTERISTICS debug types).
+ - TLS Table
+ - Load Config Directory (SEH, GFID, GIAT, Guard LongJumps, CHPE, Dynamic Value Reloc Table, Enclave Configuration, Volatile Metadata tables).
+ - Bound Import Table
+ - Delay Import Table
+ - COM Table (CLR Metadata Header, Metadata Table Streams)
+- Report several anomalies
+
+## Installing
+
+Using peparser is easy. First, use `go get` to install the latest version
+of the library. This command will install the `peparser` generator executable
+along with the library and its dependencies:
+
+ go get -u github.com/saferwall/pe
+
+Next, include `peparser` in your application:
+
+```go
+import "github.com/saferwall/pe"
+```
+
+## Using the library
+
+```go
+package main
+
+import (
+ peparser "github.com/saferwall/pe"
+)
+
+func main() {
+ pe, err := peparser.New("C:\\Binaries\\notepad.exe", nil)
+ if err != nil {
+ log.Fatalf("Error while opening file: %s, reason: %s", filename, err)
+ }
+
+ err = pe.Parse()
+ if err != nil {
+ log.Fatalf("Error while opening file: %s, reason: %s", filename, err)
+ }
+```
+
+## Todo:
+
+- imports MS-styled names demangling
+- PE: VB5 and VB6 typical structures: project info, DLLCall-imports, referenced modules, object table
+
+# References
+
+- [Peering Inside the PE: A Tour of the Win32 Portable Executable File Format by Matt Pietrek](http://bytepointer.com/resources/pietrek_peering_inside_pe.htm)
+- [An In-Depth Look into the Win32 Portable Executable File Format - Part 1 by Matt Pietrek](http://www.delphibasics.info/home/delphibasicsarticles/anin-depthlookintothewin32portableexecutablefileformat-part1)
+- [An In-Depth Look into the Win32 Portable Executable File Format - Part 2 by Matt Pietrek](http://www.delphibasics.info/home/delphibasicsarticles/anin-depthlookintothewin32portableexecutablefileformat-part2)
+- [Portable Executable File Format](https://blog.kowalczyk.info/articles/pefileformat.html)
+- [PE Format MSDN spec](https://docs.microsoft.com/en-us/windows/win32/debug/pe-format)

anomaly.go

@@ -0,0 +1,202 @@
+// Copyright 2021 Saferwall. All rights reserved.
+// Use of this source code is governed by Apache v2 license
+// license that can be found in the LICENSE file.
+
+package pe
+
+import (
+ "encoding/binary"
+ "time"
+)
+
+// Anomalies found in a PE
+var (
+
+ // AnoPEHeaderOverlapDOSHeader is reported when the PE headers overlaps with
+ // the DOS header.
+ AnoPEHeaderOverlapDOSHeader = "PE Header overlaps with DOS header"
+
+ // AnoPETimeStampNull is reported when the file header timestamp is 0.
+ AnoPETimeStampNull = "File Header timestamp set to 0"
+
+ // AnoPETimeStampFuture is reported when the file header timestamp is more
+ // than one day ahead of the current date timestamp.
+ AnoPETimeStampFuture = "File Header timestamp set to 0"
+
+ // NumberOfSections is reported when number of sections is larger or equal than 10.
+ AnoNumberOfSections10Plus = "Number of sections is 10+"
+
+ // AnoNumberOfSectionsNull is reported when sections count's is 0.
+ AnoNumberOfSectionsNull = "Number of sections is 0"
+
+ // AnoSizeOfOptionalHeaderNull is reported when size of optional header is 0.
+ AnoSizeOfOptionalHeaderNull = "Size of optional header is 0"
+
+ // AnoUncommonSizeOfOptionalHeader32 is reported when size of optional
+ // header for PE32 is larger than 0xE0.
+ AnoUncommonSizeOfOptionalHeader32 = `Size of optional header is larger than
+ 0xE0 (PE32)`
+
+ // AnoUncommonSizeOfOptionalHeader64 is reported when size of optional
+ // header for PE32+ is larger than 0xF0.
+ AnoUncommonSizeOfOptionalHeader64 = `Size of optional header is larger than
+ 0xF0 (PE32+)`
+
+ // AnoAddressOfEntryPointNull is reported when address of entry point is 0.
+ AnoAddressOfEntryPointNull = "Address of entry point is 0."
+
+ // AnoAddressOfEPLessSizeOfHeaders is reported when address of entry point
+ // is smaller than size of headers, the file cannot run under Windows.
+ AnoAddressOfEPLessSizeOfHeaders = `Address of entry point is smaller than 
+ size of headers, the file cannot run under Windows 8`
+
+ // AnoImageBaseNull is reported when the image base is null
+ AnoImageBaseNull = "Image base is 0"
+
+ // AnoDanSMagicOffset is reported when the `DanS` magic offset is different
+ // than 0x80.
+ AnoDanSMagicOffset = "`DanS` magic offset is different than 0x80"
+
+ // ErrInvalidFileAlignment is reported when file alignment is larger than
+ // 0x200 and not a power of 2.
+ ErrInvalidFileAlignment = "FileAlignment larger than 0x200 and not a power of 2"
+
+ // ErrInvalidSectionAlignment is reported when file alignment is lesser
+ // than 0x200 and different from section alignment.
+ ErrInvalidSectionAlignment = `FileAlignment lesser than 0x200 and different 
+ from section alignment`
+
+ // AnoMajorSubsystemVersion is reported when MajorSubsystemVersion has a
+ // value different than the standard 3 --> 6.
+ AnoMajorSubsystemVersion = `MajorSubsystemVersion is outside 3<-->6 boundary`
+
+ // AnonWin32VersionValue is reported when Win32VersionValue is different than 0
+ AnonWin32VersionValue = `Win32VersionValue is a reserved field, should be
+ normally set to 0x0.`
+
+ // AnoInvalidPEChecksum is reported when the optional header checksum field
+ // is different from what it should normally be.
+ AnoInvalidPEChecksum = `Optional header checksum is invalid.`
+
+ // AnoNumberOfRvaAndSizes is reported when NumberOfRvaAndSizes is different
+ // than 16.
+ AnoNumberOfRvaAndSizes = `Optional header NumberOfRvaAndSizes != 16`
+)
+
+// GetAnomalies reportes anomalies found in a PE binary.
+// These nomalies does prevent the Windows loader from loading the files but
+// is an interesting features for malware analysis.
+func (pe *File) GetAnomalies() error {
+
+ // ******************** Anomalies in File header ************************
+ // An application for Windows NT typically has the nine predefined sections
+ // named: .text, .bss, .rdata, .data, .rsrc, .edata, .idata, .pdata, and
+ // .debug. Some applications do not need all of these sections, while
+ // others may define still more sections to suit their specific needs.
+ // NumberOfSections can be up to 96 under XP.
+ // NumberOfSections can be up to 65535 under Vista and later.
+ if pe.NtHeader.FileHeader.NumberOfSections >= 10 {
+ pe.Anomalies = append(pe.Anomalies, AnoNumberOfSections10Plus)
+ }
+
+ // File header timestamp set to 0.
+ if pe.NtHeader.FileHeader.TimeDateStamp == 0 {
+ pe.Anomalies = append(pe.Anomalies, AnoPETimeStampNull)
+ }
+
+ // File header timestamp set to the future.
+ now := time.Now()
+ future := uint32(now.Add(24 * time.Hour).Unix())
+ if pe.NtHeader.FileHeader.TimeDateStamp > future {
+ pe.Anomalies = append(pe.Anomalies, AnoPETimeStampFuture)
+ }
+
+ // NumberOfSections can be null with low alignment PEs
+ // and in this case, the values are just checked but not really used (under XP)
+ if pe.NtHeader.FileHeader.NumberOfSections == 0 {
+ pe.Anomalies = append(pe.Anomalies, AnoNumberOfSectionsNull)
+ }
+
+ // SizeOfOptionalHeader is not the size of the optional header, but the delta
+ // between the top of the Optional header and the start of the section table.
+ // Thus, it can be null (the section table will overlap the Optional Header,
+ // or can be null when no sections are present)
+ if pe.NtHeader.FileHeader.SizeOfOptionalHeader == 0 {
+ pe.Anomalies = append(pe.Anomalies, AnoSizeOfOptionalHeaderNull)
+ }
+
+ // SizeOfOptionalHeader can be bigger than the file
+ // (the section table will be in virtual space, full of zeroes), but can't be negative.
+ // Do some check here.
+ oh32 := ImageOptionalHeader32{}
+ oh64 := ImageOptionalHeader64{}
+
+ // SizeOfOptionalHeader standard value is 0xE0 for PE32.
+ if pe.Is32 &&
+ pe.NtHeader.FileHeader.SizeOfOptionalHeader > uint16(binary.Size(oh32)) {
+ pe.Anomalies = append(pe.Anomalies, AnoUncommonSizeOfOptionalHeader32)
+ }
+
+ // SizeOfOptionalHeader standard value is 0xF0 for PE32+.
+ if pe.Is64 &&
+ pe.NtHeader.FileHeader.SizeOfOptionalHeader > uint16(binary.Size(oh64)) {
+ pe.Anomalies = append(pe.Anomalies, AnoUncommonSizeOfOptionalHeader64)
+ }
+
+ // ***************** Anomalies in Optional header *********************
+ // Under Windows 8, AddressOfEntryPoint is not allowed to be smaller than
+ // SizeOfHeaders, except if it's null.
+ switch pe.Is64 {
+ case true:
+ oh64 = pe.NtHeader.OptionalHeader.(ImageOptionalHeader64)
+ case false:
+ oh32 = pe.NtHeader.OptionalHeader.(ImageOptionalHeader32)
+ }
+
+ // Use oh for fields which are common for both structures.
+ oh := oh32
+ if oh.AddressOfEntryPoint != 0 && oh.AddressOfEntryPoint < oh.SizeOfHeaders {
+ pe.Anomalies = append(pe.Anomalies, AnoAddressOfEPLessSizeOfHeaders)
+ }
+
+ // AddressOfEntryPoint can be null in DLLs: in this case,
+ // DllMain is just not called. can be null
+ if oh.AddressOfEntryPoint == 0 {
+ pe.Anomalies = append(pe.Anomalies, AnoAddressOfEntryPointNull)
+ }
+
+ // ImageBase can be null, under XP.
+ // In this case, the binary will be relocated to 10000h
+ if (pe.Is64 && oh64.ImageBase == 0) ||
+ (pe.Is32 && oh32.ImageBase == 0) {
+ pe.Anomalies = append(pe.Anomalies, AnoImageBaseNull)
+ }
+
+ // For DLLs, MajorSubsystemVersion is ignored until Windows 8. It can have
+ // any value. Under Windows 8, it needs a standard value (3.10 < 6.30).
+ if oh.MajorSubsystemVersion < 3 || oh.MajorSubsystemVersion > 6 {
+ pe.Anomalies = append(pe.Anomalies, AnoMajorSubsystemVersion)
+ }
+
+ // Win32VersionValue officially defined as `reserved` and should be null
+ // if non null, it overrides MajorVersion/MinorVersion/BuildNumber/PlatformId
+ // OperatingSystem Versions values located in the PEB, after loading.
+ if oh.Win32VersionValue != 0 {
+ pe.Anomalies = append(pe.Anomalies, AnonWin32VersionValue)
+ }
+
+ // Checksums are required for kernel-mode drivers and some system DLLs.
+ // Otherwise, this field can be 0.
+ if pe.Checksum() != oh.CheckSum && oh.CheckSum != 0 {
+ pe.Anomalies = append(pe.Anomalies, AnoInvalidPEChecksum)
+ }
+
+ // This field contains the number of IMAGE_DATA_DIRECTORY entries.
+ // This field has been 16 since the earliest releases of Windows NT.
+ if (pe.Is64 && oh64.NumberOfRvaAndSizes == 0xA) ||
+ (pe.Is32 && oh32.NumberOfRvaAndSizes == 0xA) {
+ pe.Anomalies = append(pe.Anomalies, AnoNumberOfRvaAndSizes)
+ }
+
+ return nil
+}

arch.go

@@ -0,0 +1,11 @@
+// Copyright 2021 Saferwall. All rights reserved.
+// Use of this source code is governed by Apache v2 license
+// license that can be found in the LICENSE file.
+
+package pe
+
+// Architecture-specific data. This data directory is not used
+// (set to all zeros) for I386, IA64, or AMD64 architecture.
+func (pe *File) parseArchitectureDirectory(rva, size uint32) error {
+ return nil
+}