malwaredb_types/exec/pe32/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2
3/// PE-32 fields
4mod fields;
5
6use crate::exec::{
7    Architecture, ExecutableFile, ExecutableType, Imports, OperatingSystem, Section, Sections,
8};
9use crate::utils::{EntropyCalc, bytes_offset_match, u32_from_offset};
10use crate::{Ordering, SpecimenFile};
11
12use std::fmt::{Display, Formatter};
13
14use anyhow::{Result, bail};
15use chrono::{DateTime, Utc};
16use flagset::FlagSet;
17use tracing::{debug, instrument};
18use uuid::Uuid;
19
20// Microsoft documentation:
21// https://learn.microsoft.com/en-us/windows/win32/debug/pe-format
22// Wikipedia entry:
23// https://en.wikipedia.org/wiki/Portable_Executable
24
25const EXE_MAGIC: [u8; 2] = [b'M', b'Z'];
26const PE_MAGIC: [u8; 4] = [0x50, 0x45, 0x00, 0x00];
27
28/// EXE subtypes
29///
30/// PE32 files are EXE files, but not all EXE files are PE32.
31#[derive(Clone, Debug, Eq, PartialEq)]
32pub enum SubType {
33    /// MS-DOS, IBM DOS, Free DOS executable
34    DosExe,
35
36    /// .Net executable, PE32
37    DotNet,
38
39    /// Portable Executable, MS Windows
40    PE32,
41
42    /// 64-bit Portable Executable, MS Windows
43    PE32_64,
44
45    /// New Executable, 16-bit, Windows 3.1
46    NE,
47
48    /// Linear Executable, IBM OS/2
49    LE,
50}
51
52impl SubType {
53    /// Static string representation
54    #[must_use]
55    pub fn as_str(&self) -> &'static str {
56        match self {
57            SubType::DosExe => "MZ DOS executable",
58            SubType::DotNet => ".Net executable",
59            SubType::PE32 => "Portable Executable (PE32)",
60            SubType::PE32_64 => "64-bit Portable Executable (PE32+)",
61            SubType::NE => "New Executable",
62            SubType::LE => "Linear Executable",
63        }
64    }
65}
66
67impl Display for SubType {
68    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
69        write!(f, "{}", self.as_str())
70    }
71}
72
73/// PE32 files may be for different subsystems in Windows.
74///
75/// Some notable examples are graphical vs. command line applications, EFI applications, etc.
76#[derive(Clone, Debug, Eq, PartialEq)]
77pub enum SubSystem {
78    /// Unknown subsystem
79    Unknown,
80
81    /// Graphical Windows
82    WindowsGUI,
83
84    /// Command-line Windows
85    WindowsCLI,
86
87    /// Command-line OS/2
88    OS2CLI,
89
90    /// Posix subsystem
91    POSIX,
92
93    /// Native code
94    NativeCode,
95
96    /// Native driver
97    NativeDriver,
98
99    /// Windows CE (embedded)
100    WindowsCE,
101
102    /// EFI (Extensible Firmware Interface) application
103    EFI,
104
105    /// EFI driver with boot services
106    EFIBoot,
107
108    /// EFI ROM image
109    EFIRom,
110
111    /// EFI driver with runtime services
112    EFIRuntimeDriver,
113
114    /// Xbox application
115    Xbox,
116
117    /// Windows Boot application
118    WindowsBoot,
119}
120
121impl SubSystem {
122    /// Static string representation
123    #[must_use]
124    pub fn as_str(&self) -> &'static str {
125        match self {
126            SubSystem::Unknown => "Unknown subsystem",
127            SubSystem::WindowsGUI => "Windows GUI",
128            SubSystem::WindowsCLI => "Windows CLI",
129            SubSystem::OS2CLI => "OS/2 CLI",
130            SubSystem::POSIX => "Posix",
131            SubSystem::NativeCode => "Native Code",
132            SubSystem::NativeDriver => "Native Driver",
133            SubSystem::WindowsCE => "Windows CE",
134            SubSystem::EFI => "EFI",
135            SubSystem::EFIBoot => "EFI boot",
136            SubSystem::EFIRom => "EFI ROM",
137            SubSystem::EFIRuntimeDriver => "EFI driver with runtime",
138            SubSystem::Xbox => "Xbox",
139            SubSystem::WindowsBoot => "Windows Boot",
140        }
141    }
142}
143
144impl Display for SubSystem {
145    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
146        write!(f, "{}", self.as_str())
147    }
148}
149
150impl From<u16> for SubSystem {
151    fn from(value: u16) -> Self {
152        match value {
153            1 => SubSystem::NativeCode,
154            2 => SubSystem::WindowsGUI,
155            3 => SubSystem::WindowsCLI,
156            5 => SubSystem::OS2CLI,
157            7 => SubSystem::POSIX,
158            8 => SubSystem::NativeDriver,
159            9 => SubSystem::WindowsCE,
160            10 => SubSystem::EFI,
161            11 => SubSystem::EFIBoot,
162            12 => SubSystem::EFIRuntimeDriver,
163            13 => SubSystem::EFIRom,
164            14 => SubSystem::Xbox,
165            16 => SubSystem::WindowsBoot,
166            _ => SubSystem::Unknown,
167        }
168    }
169}
170
171/// The struct to partially represent EXE files.
172///
173/// Used on Windows, DOS, React OS, OS/2, and maybe others.
174///
175/// Effort is made to fail gracefully, since malware may not obey all the rules, and some information
176/// is better than none because some part of the data wasn't parsed correctly.
177#[derive(Clone, Debug)]
178pub struct EXE<'a> {
179    /// If the program is 64-bit
180    pub is64bit: bool,
181
182    /// If the binary has extra data after the last section, could be used to hide something
183    pub has_overlay: Option<bool>,
184
185    /// Instruction set architecture for this binary
186    pub arch: Architecture,
187
188    /// EXE sub-type, mostly if it's for DOS, Windows, OS/2
189    pub sub_type: SubType,
190
191    /// Operating System for this binary, likely Windows
192    pub os: OperatingSystem,
193
194    /// COFF (Common Object File Format) header of the program
195    pub coff_header: Option<fields::COFFHeader>,
196
197    /// Optional Header for this program, not optional if for Windows
198    pub optional_header: Option<fields::OptionalHeader>,
199
200    /// Executable subtype: Program or Library?
201    pub exec_type: ExecutableType,
202
203    /// Windows Subsystem used by this program
204    pub subsystem: Option<SubSystem>,
205
206    /// Sections of this binary
207    pub sections: Option<Sections<'a>>,
208
209    /// External libraries used by this application or library
210    pub imports: Option<Imports>,
211
212    /// The array containing the raw bytes used to parse this program
213    pub contents: &'a [u8],
214}
215
216impl<'a> EXE<'a> {
217    /// EXE, MZ, or PE-32 file parsed from a sequence of bytes
218    ///
219    /// # Errors
220    ///
221    /// Returns an error if parsing fails.
222    #[allow(clippy::too_many_lines)]
223    #[instrument(name = "PE32 parser", skip(contents))]
224    pub fn from(contents: &'a [u8]) -> Result<Self> {
225        if !((contents[0] == EXE_MAGIC[0] && contents[1] == EXE_MAGIC[1])
226            || (contents[0] == EXE_MAGIC[1] && contents[1] == EXE_MAGIC[0]))
227        {
228            bail!("Not a MZ, MS-DOS, or PE32 file");
229        }
230
231        if contents.len() <= 0x40 {
232            bail!("Not enough bytes in PE32 file");
233        }
234
235        let pe_magic_offset =
236            u32_from_offset(contents, 0x3C, Ordering::LittleEndian).unwrap_or_default() as usize;
237        let coff_header_offset = pe_magic_offset + 4;
238        if pe_magic_offset > contents.len()
239            || pe_magic_offset + PE_MAGIC.len() > contents.len()
240            || !bytes_offset_match(contents, pe_magic_offset, &PE_MAGIC)
241        {
242            return Ok(Self {
243                is64bit: false,
244                has_overlay: None,
245                arch: Architecture::X86,
246                sub_type: SubType::DosExe,
247                os: OperatingSystem::DOS,
248                subsystem: None,
249                sections: None,
250                coff_header: None,
251                optional_header: None,
252                exec_type: ExecutableType::Program,
253                imports: None,
254                contents,
255            });
256        }
257
258        let mut sections = Sections::default();
259        let coff = fields::COFFHeader::from(&contents[coff_header_offset..])?;
260        let Some(optional_header) =
261            fields::OptionalHeader::from(&contents[coff_header_offset + 20..])
262        else {
263            return Ok(Self {
264                is64bit: false,
265                has_overlay: None,
266                arch: Architecture::X86,
267                sub_type: SubType::DosExe,
268                os: OperatingSystem::DOS,
269                subsystem: None,
270                sections: None,
271                coff_header: None,
272                optional_header: None,
273                exec_type: ExecutableType::Program,
274                imports: None,
275                contents,
276            });
277        };
278
279        let is64bit = optional_header.is_64bit();
280        let sub_type = {
281            let mut sub_type = SubType::PE32;
282            if is64bit {
283                sub_type = SubType::PE32_64;
284            }
285
286            if let Some(data_directories) = optional_header.data_directories()
287                && data_directories.clr_runtime_header.virtual_address > 0
288            {
289                sub_type = SubType::DotNet;
290            }
291
292            sub_type
293        };
294
295        let exec_type = {
296            if coff
297                .characteristics
298                .contains(fields::CoffCharacteristics::FileDLL)
299            {
300                ExecutableType::Library
301            } else if coff
302                .characteristics
303                .contains(fields::CoffCharacteristics::ExecutableImage)
304            {
305                ExecutableType::Program
306            } else {
307                ExecutableType::Unknown(0)
308            }
309        };
310
311        let mut subsystem = None;
312        let mut has_overlay = false;
313        if coff
314            .characteristics
315            .contains(fields::CoffCharacteristics::ExecutableImage)
316        {
317            let mut offset =
318                u32_from_offset(contents, 0x3C, Ordering::LittleEndian).unwrap_or_default() + 24;
319            if let Some(subsys) = optional_header.subsystem() {
320                subsystem = Some(subsys.into());
321            }
322
323            if is64bit {
324                offset += 240;
325            } else {
326                offset += 224;
327            }
328            let mut sections_offset = 0;
329            for sec_num in 0..coff.num_sections {
330                if (offset + 40) as usize > contents.len() {
331                    break;
332                }
333                let section_name =
334                    String::from_utf8(contents[offset as usize..(offset + 8) as usize].to_vec())
335                        .unwrap_or_default();
336                let section_virtual_size =
337                    u32_from_offset(contents, (offset + 8) as usize, Ordering::LittleEndian);
338                let section_virtual_address =
339                    u32_from_offset(contents, (offset + 12) as usize, Ordering::LittleEndian);
340                let section_size =
341                    u32_from_offset(contents, (offset + 16) as usize, Ordering::LittleEndian)
342                        .unwrap_or_default() as usize;
343                let section_offset =
344                    u32_from_offset(contents, (offset + 20) as usize, Ordering::LittleEndian)
345                        .unwrap_or_default() as usize;
346                let section_characteristics = FlagSet::<fields::SectionFlags>::new(
347                    u32_from_offset(contents, (offset + 36) as usize, Ordering::LittleEndian)
348                        .unwrap_or_default(),
349                )
350                .unwrap_or_default();
351                let section_executable = section_characteristics.contains(
352                    fields::SectionFlags::Executable | fields::SectionFlags::ContainsCode,
353                );
354
355                if section_offset + section_size < contents.len() {
356                    sections.push(Section {
357                        name: section_name,
358                        is_executable: section_executable,
359                        size: section_size,
360                        offset: section_offset,
361                        virtual_address: section_virtual_address.unwrap_or_default(),
362                        virtual_size: section_virtual_size.unwrap_or_default(),
363                        entropy: contents[section_offset..(section_offset + section_size)]
364                            .to_vec()
365                            .entropy(),
366                        data: Some(&contents[section_offset..(section_offset + section_size)]),
367                    });
368                } else {
369                    debug!(
370                        "PE32: Skipping section {sec_num} '{section_name}': offset {section_offset} + size {section_size} >= file length {}",
371                        contents.len()
372                    );
373                }
374
375                if section_size + section_offset > sections_offset {
376                    sections_offset = section_size + section_offset;
377                }
378                offset += 40; // Section entries are 40 bytes
379            }
380            has_overlay = sections_offset > 0
381                && sections_offset < contents.len()
382                && contents.len() - sections_offset > 0;
383        }
384
385        let mut imports = None;
386        if let Some(data_directories) = optional_header.data_directories() {
387            let import_section = sections
388                .iter()
389                .find(|x| x.virtual_address == data_directories.import_table.virtual_address);
390
391            if let Some(import_section) = import_section
392                && import_section.size > 8
393                && import_section.offset > 0
394                && let Some(num_imports) = match optional_header {
395                    fields::OptionalHeader::OptionalHeader32(h32) => h32.num_rva_and_sizes,
396                    fields::OptionalHeader::OptionalHeader64(h64) => h64.num_rva_and_sizes,
397                }
398            {
399                imports = Some(data_directories.imports(num_imports as usize, import_section));
400            }
401        }
402
403        Ok(Self {
404            is64bit,
405            has_overlay: Some(has_overlay),
406            arch: coff.architecture(),
407            sub_type,
408            os: OperatingSystem::Windows,
409            subsystem,
410            sections: Some(sections),
411            exec_type,
412            coff_header: Some(*coff),
413            optional_header: Some(optional_header),
414            imports,
415            contents,
416        })
417    }
418}
419
420impl ExecutableFile for EXE<'_> {
421    fn architecture(&self) -> Option<Architecture> {
422        Some(self.arch)
423    }
424
425    fn pointer_size(&self) -> usize {
426        match self.sub_type {
427            SubType::PE32_64 => 64,
428            SubType::LE | SubType::NE => 16,
429            _ => 32,
430        }
431    }
432
433    fn operating_system(&self) -> OperatingSystem {
434        self.os
435    }
436
437    fn compiled_timestamp(&self) -> Option<DateTime<Utc>> {
438        self.coff_header.map(|c| c.compiled_date())
439    }
440
441    #[allow(clippy::cast_possible_truncation)]
442    fn num_sections(&self) -> u32 {
443        self.sections.as_ref().unwrap_or(&Sections::default()).len() as u32
444    }
445
446    fn sections(&self) -> Option<&Sections<'_>> {
447        self.sections.as_ref()
448    }
449
450    fn import_hash(&self) -> Option<Uuid> {
451        self.imports.as_ref().map(Imports::hash)
452    }
453
454    fn fuzzy_imports(&self) -> Option<String> {
455        self.imports.as_ref().map(Imports::fuzzy_hash)
456    }
457}
458
459impl SpecimenFile for EXE<'_> {
460    const MAGIC: &'static [&'static [u8]] = &[b"MZ", b"ZM"];
461
462    fn type_name(&self) -> &'static str {
463        self.sub_type.as_str()
464    }
465}
466
467impl Display for EXE<'_> {
468    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
469        writeln!(f, "EXE file:")?;
470        writeln!(f, "\tSubtype: {}", self.sub_type)?;
471        writeln!(f, "\tExecutable type: {}", self.exec_type)?;
472        writeln!(f, "\tOS: {}", self.os)?;
473        writeln!(f, "\tArch: {}", self.arch)?;
474        if let Some(coff) = self.coff_header {
475            writeln!(
476                f,
477                "\tCompiled: {:?}",
478                coff.compiled_date().format("%Y-%m-%d %H:%M:%S").to_string()
479            )?;
480        }
481        if let Some(subsys) = &self.subsystem {
482            writeln!(f, "\tSubsystem: {subsys}")?;
483        }
484        if let Some(sections) = &self.sections {
485            writeln!(f, "\t{} sections:", sections.len())?;
486            for section in sections {
487                writeln!(f, "\t\t{section}")?;
488            }
489        }
490        if let Some(imports) = &self.imports {
491            if imports.imports.len() == imports.expected_imports as usize {
492                writeln!(f, "\t{} imports:", imports.imports.len())?;
493            } else {
494                writeln!(
495                    f,
496                    "\t{} out of {} imports:",
497                    imports.imports.len(),
498                    imports.expected_imports
499                )?;
500            }
501            for import in &imports.imports {
502                writeln!(f, "\t\t{import}")?;
503            }
504            writeln!(f, "\t\tImport hash: {}", hex::encode(imports.hash()))?;
505            writeln!(f, "\t\tFuzzy Import hash: {}", imports.fuzzy_hash())?;
506        }
507        if self.has_overlay == Some(true) {
508            writeln!(f, "\tHas extra bytes at the end (overlay).")?;
509        }
510        writeln!(f, "\tSize: {}", self.contents.len())?;
511        writeln!(f, "\tEntropy: {:.4}", self.contents.entropy())
512    }
513}
514
515#[cfg(test)]
516mod tests {
517    use super::*;
518
519    use rstest::rstest;
520
521    // aclock binaries are from https://github.com/tenox7/aclock, and used as a stand-in for weird
522    // files instead of storing actual malware in the repository
523    #[rstest]
524    #[case::alpha(include_bytes!("../../../testdata/exe/pe32_aclock_axp.exe"), false, Architecture::Alpha, ExecutableType::Program, SubType::PE32, Some(SubSystem::WindowsCLI))]
525    #[case::alpha64(include_bytes!("../../../testdata/exe/pe64_aclock_axp64.exe"), true, Architecture::Alpha64, ExecutableType::Program, SubType::PE32_64, Some(SubSystem::WindowsCLI))]
526    #[case::arm64(include_bytes!("../../../testdata/exe/pe64_win32_console_arm64_gnu.exe"), true, Architecture::ARM64, ExecutableType::Program, SubType::PE32_64, Some(SubSystem::WindowsCLI))]
527    #[case::dot_net(include_bytes!("../../../testdata/exe/pe32_dotnet.exe"), false, Architecture::X86, ExecutableType::Program, SubType::DotNet, Some(SubSystem::WindowsCLI))]
528    #[case::efi(include_bytes!("../../../testdata/exe/efi/hello.efi"), true, Architecture::X86_64, ExecutableType::Program, SubType::PE32_64, Some(SubSystem::EFI))]
529    #[case::mips(include_bytes!("../../../testdata/exe/pe32_aclock_mips.exe"), false, Architecture::MIPSEL, ExecutableType::Program, SubType::PE32, Some(SubSystem::WindowsCLI))]
530    #[case::ppc(include_bytes!("../../../testdata/exe/pe32_aclock_ppc_winnt.exe"), false, Architecture::PowerPCLE, ExecutableType::Program, SubType::PE32, Some(SubSystem::WindowsCLI))]
531    #[case::x86_64_console(include_bytes!("../../../testdata/exe/pe64_win32_console_x86_64_gnu.exe"), true, Architecture::X86_64, ExecutableType::Program, SubType::PE32_64, Some(SubSystem::WindowsCLI))]
532    #[case::x86_64_gui(include_bytes!("../../../testdata/exe/pe64_win32_gui_x86_64_gnu.exe"), true, Architecture::X86_64, ExecutableType::Program, SubType::PE32_64, Some(SubSystem::WindowsGUI))]
533    #[case::x86_64_posix(include_bytes!("../../../testdata/exe/pe64_posix_x86_64_gnu.exe"), true, Architecture::X86_64, ExecutableType::Program, SubType::PE32_64, Some(SubSystem::POSIX))]
534    #[case::x86_64_xbox(include_bytes!("../../../testdata/exe/pe64_xbox_x86_64_gnu.exe"), true, Architecture::X86_64, ExecutableType::Program, SubType::PE32_64, Some(SubSystem::Xbox))]
535    #[case::x86_64_lib_console(include_bytes!("../../../testdata/exe/pe64_lib_console_x86_64_gnu.exe"), true, Architecture::X86_64, ExecutableType::Library, SubType::PE32_64, Some(SubSystem::WindowsCLI))]
536    #[case::x86_64_lib_gui(include_bytes!("../../../testdata/exe/pe64_lib_gui_x86_64_gnu.exe"), true, Architecture::X86_64, ExecutableType::Library, SubType::PE32_64, Some(SubSystem::WindowsGUI))]
537    #[case::x86_exe(include_bytes!("../../../testdata/exe/aclock-i386-win16.exe"), false, Architecture::X86, ExecutableType::Program, SubType::DosExe, None)]
538    #[case::i8086_exe(include_bytes!("../../../testdata/exe/aclock-i8086-win1x.exe"), false, Architecture::X86, ExecutableType::Program, SubType::DosExe, None)]
539    #[test]
540    fn binaries(
541        #[case] bytes: &[u8],
542        #[case] is_64bit: bool,
543        #[case] arch: Architecture,
544        #[case] exec_type: ExecutableType,
545        #[case] sub_type: SubType,
546        #[case] subsystem: Option<SubSystem>,
547    ) {
548        let exe = EXE::from(bytes).unwrap();
549        eprintln!("{exe}");
550        assert_eq!(exe.is64bit, is_64bit);
551        assert_eq!(exe.arch, arch);
552        assert_eq!(exe.subsystem, subsystem);
553        assert_eq!(exe.exec_type, exec_type);
554        assert_eq!(exe.sub_type, sub_type);
555
556        if arch == Architecture::X86_64 {
557            if subsystem == Some(SubSystem::EFI) {
558                assert!(exe.imports.is_none());
559            } else {
560                let imports = exe.imports.unwrap();
561                if exec_type == ExecutableType::Library {
562                    assert_eq!("466e0075eba65b201b4cc8d4d3f85cbb", hex::encode(imports.hash()));
563                } else if exec_type == ExecutableType::Program {
564                    assert_eq!("610b6b6aa37c8e01c9855a05dcf00565", hex::encode(imports.hash()));
565                }
566            }
567        }
568    }
569}
malwaredb_types/exec/pe32/mod.rs

malwaredb_types/exec/pe32/
mod.rs
