pe

The pe module allows you to create more fine-grained rules for Portable Executable (PE) files by using attributes and features of the PE file format. This module exposes most of the fields present in a PE header and provides functions which can be used to write more expressive and targeted rules. Let’s see some examples:

import "pe"

rule single_section {
    condition:
        pe.number_of_sections == 1
}

rule control_panel_applet {
    condition:
        pe.exports("CPlApplet")
}

rule is_dll {
    condition:
        pe.characteristics & pe.DLL != 0
}

rule is_pe {
    condition:
        pe.is_pe
}

Functions#

exports(fn_name)#

Returns true if the PE exports a function with the given name, or false otherwise.

exports(fn_regex)#

Returns true if the PE exports a function whose name matches the given regular expression, or false otherwise.

exports(ordinal)#

Returns true if the PE exports a function with the given ordinal, or false if otherwise.

exports_index(fn_name)#

Returns the index into the export_details array for the first exported function that matches the given name. The result is undefined if no function with such a name exists.

exports_index(fn_regex)#

Returns the index into the export_details array for the first exported function that matches the given regular expression. The result is undefined if none of the functions matches.

exports_index(ordinal)#

Returns the index into the export_details array for the first exported function that has the given ordinal number. The result is undefined if no function exists with such an ordinal exists.

imports(dll_name)#

Returns the number of functions that the PE imports from the given DLL. The DLL name is case-insensitive.

imports(dll_name, fn_name)#

Returns true if the PE imports the given function from the given DLL. The DLL name is case-insensitive, but the function name is case-sensitive.

imports(dll_name, ordinal)#

Returns true if the PE imports the given function by ordinal from the given DLL. The DLL name is case-insensitive.

imports(dll_regex, fn_regex)#

Returns the number of functions imported by the PE where the DLL name matches dll_regexp and the function name matches fn_regexp. Both arguments are case-sensitive, unless you use the /i modifier in the regexp.

Example#

import "pe"

rule ProcessMemory {
    condition:
        pe.imports(/kernel32.dll/i, /(Read|Write)ProcessMemory/) > 0
}

imports(type, dll_name, fn_name)#

Returns true if the PE imports fn_name from dll_name. The DLL name is case-insensitive. type allows to specify the kind of imports should be taken into account, the allowed values are:

Example#

import "pe"

rule ProcessMemory {
    condition:
        pe.imports(pe.IMPORT_DELAYED, "kernel32.dll", "WriteProcessMemory")
}

is_32bit()#

Returns true if the file is a 32-bit PE.

is_64bit()#

Returns true if the file is a 64-bit PE.

is_dll()#

Returns true if the file is Dynamic Link Library (DLL).

rva_to_offset(rva)#

Given a relative virtual address (RVA) returns the corresponding file offset.

calculate_checksum()#

Calculate the PE checksum. Useful for checking if the checksum in the header is correct.

Example#

import "pe"

rule WrongChecksum {
    condition:
        pe.calculate_checksum() != pe.checksum
}

section_index(name)#

Returns the index into the sections array for the section that has the given name. The name argument is case-sensitive.

section_index(offset)#

Returns the index into the sections array for the section that contains the given file offset.

imphash()#

Returns the import hash (or imphash) for the PE. The imphash is an MD5 hash of the PE’s import table after some normalization. The imphash for a PE can be also computed with pefile and you can find more information in Mandiant’s blog.

rich_signature.version(version, [toolid])#

The PE rich signature contains information about the tools involved in the creation of the PE file. This function returns the number of tools that matches the given version and toolid, where toolid is optional.

Example#

import "pe"

rule WrongChecksum {
    condition:
        pe.rich_signature.version(24215, 261) == 61
}

rich_signature.toolid(toolid, [version])#

This function is similar to rich_signature.version, but the toolid argument is required while version is optional.

Module structure#

Certificate#

This is the structure of each item in the certificates array.

CounterSignature#

DirEntry#

Export#

Function#

Import#

KeyValue#

Overlay#

VersionInfoEntry#

Resource#

RichSignature#

RichTool#

Section#

Signature#

Structure of each of the items in the signatures array.

Example#

import "pe"

rule NotVerified {
    condition:
        for any sig in pe.signatures : (
            sig.subject contains "Microsoft" and
            not sig.verified
        )
}

SignerInfo#

Version#

The structures of fields like os_version, subsystem_version, image_version, linker_version and resource_version.

Example#

import "pe"

rule Windows_5_2 {
    condition:
        pe.os_version.major == 5 and 
        pe.os_version.minor == 2
}

Characteristics#

Possible flags found in the characteristics field.

Example#

import "pe"

rule IsDLL {
    condition:
        pe.characteristics & pe.DLL != 0
}

DllCharacteristics#

Possible flags found in the dll_characteristics field.

Example#

import "pe"

rule WdmDriver {
    condition:
        pe.dll_characteristics & pe.WDM_DRIVER != 0
}

DirectoryEntry#

ImportFlags#

Machine#

Each of the possible values in the machine field.

Example#

import "pe"

rule ARM {
    condition:
        pe.machine == pe.MACHINE_ARM
}

OptionalMagic#

ResourceType#

https://learn.microsoft.com/en-us/windows/win32/menurc/resource-types?redirectedfrom=MSDN

SectionCharacteristics#

Subsystem#