PE module

The PE module allows you to create more fine-grained rules for 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
}

Reference

machine

Changed in version 3.3.0.

Integer with one of the following values:

MACHINE_UNKNOWN
MACHINE_AM33
MACHINE_AMD64
MACHINE_ARM
MACHINE_ARMNT
MACHINE_ARM64
MACHINE_EBC
MACHINE_I386
MACHINE_IA64
MACHINE_M32R
MACHINE_MIPS16
MACHINE_MIPSFPU
MACHINE_MIPSFPU16
MACHINE_POWERPC
MACHINE_POWERPCFP
MACHINE_R4000
MACHINE_SH3
MACHINE_SH3DSP
MACHINE_SH4
MACHINE_SH5
MACHINE_THUMB
MACHINE_WCEMIPSV2

Example: pe.machine == pe.MACHINE_AMD64

checksum

New in version 3.6.0.

Integer with the “PE checksum” as stored in the OptionalHeader

calculate_checksum

New in version 3.6.0.

Function that calculates the “PE checksum”

Example: pe.checksum == pe.calculate_checksum()

subsystem

Integer with one of the following values:

SUBSYSTEM_UNKNOWN
SUBSYSTEM_NATIVE
SUBSYSTEM_WINDOWS_GUI
SUBSYSTEM_WINDOWS_CUI
SUBSYSTEM_OS2_CUI
SUBSYSTEM_POSIX_CUI
SUBSYSTEM_NATIVE_WINDOWS
SUBSYSTEM_WINDOWS_CE_GUI
SUBSYSTEM_EFI_APPLICATION
SUBSYSTEM_EFI_BOOT_SERVICE_DRIVER
SUBSYSTEM_EFI_RUNTIME_DRIVER
SUBSYSTEM_XBOX
SUBSYSTEM_WINDOWS_BOOT_APPLICATION

Example: pe.subsystem == pe.SUBSYSTEM_NATIVE

timestamp

PE timestamp.

entry_point

Entry point raw offset or virtual address depending on whether YARA is scanning a file or process memory respectively. This is equivalent to the deprecated entrypoint keyword.

image_base

Image base relative virtual address.

characteristics

Bitmap with PE FileHeader characteristics. Individual characteristics can be inspected by performing a bitwise AND operation with the following constants:

RELOCS_STRIPPED
EXECUTABLE_IMAGE
LINE_NUMS_STRIPPED
LOCAL_SYMS_STRIPPED
AGGRESIVE_WS_TRIM
LARGE_ADDRESS_AWARE
BYTES_REVERSED_LO
MACHINE_32BIT
DEBUG_STRIPPED
REMOVABLE_RUN_FROM_SWAP
NET_RUN_FROM_SWAP
SYSTEM
DLL
UP_SYSTEM_ONLY
BYTES_REVERSED_HI

Example: pe.characteristics & pe.DLL

linker_version

An object with two integer attributes, one for each major and minor linker version.

major

Major linker version.

minor

Minor linker version.

os_version

An object with two integer attributes, one for each major and minor OS version.

major

Major OS version.

minor

Minor OS version.

image_version

An object with two integer attributes, one for each major and minor image version.

major

Major image version.

minor

Minor image version.

subsystem_version

An object with two integer attributes, one for each major and minor subsystem version.

major

Major subsystem version.

minor

Minor subsystem version.

dll_characteristics

Bitmap with PE OptionalHeader DllCharacteristics. Do not confuse these flags with the PE FileHeader Characteristics. Individual characteristics can be inspected by performing a bitwise AND operation with the following constants:

DYNAMIC_BASE

File can be relocated - also marks the file as ASLR compatible

FORCE_INTEGRITY
NX_COMPAT

Marks the file as DEP compatible

NO_ISOLATION
NO_SEH

The file does not contain structured exception handlers, this must be set to use SafeSEH

NO_BIND
WDM_DRIVER

Marks the file as a Windows Driver Model (WDM) device driver.

TERMINAL_SERVER_AWARE

Marks the file as terminal server compatible

number_of_sections

Number of sections in the PE.

sections

New in version 3.3.0.

A zero-based array of section objects, one for each section the PE has. Individual sections can be accessed by using the [] operator. Each section object has the following attributes:

name

Section name.

characteristics

Section characteristics.

virtual_address

Section virtual address.

virtual_size

Section virtual size.

raw_data_offset

Section raw offset.

raw_data_size

Section raw size.

Example: pe.sections[0].name == ”.text”

Individual section characteristics can be inspected using a bitwise AND operation with the following constants:

SECTION_CNT_CODE
SECTION_CNT_INITIALIZED_DATA
SECTION_CNT_UNINITIALIZED_DATA
SECTION_GPREL
SECTION_MEM_16BIT
SECTION_LNK_NRELOC_OVFL
SECTION_MEM_DISCARDABLE
SECTION_MEM_NOT_CACHED
SECTION_MEM_NOT_PAGED
SECTION_MEM_SHARED
SECTION_MEM_EXECUTE
SECTION_MEM_READ
SECTION_MEM_WRITE

Example: pe.sections[1].characteristics & SECTION_CNT_CODE

overlay

New in version 3.6.0.

A structure containing the following integer members:

offset

Overlay section offset.

size

Overlay section size.

Example: uint8(0x0d) at pe.overlay.offset and pe.overlay.size > 1024

number_of_resources

Number of resources in the PE.

resource_timestamp

Resource timestamp. This is stored as an integer.

resource_version

An object with two integer attributes, major and minor versions.

major

Major resource version.

minor

Minor resource version.

resources

Changed in version 3.3.0.

A zero-based array of resource objects, one for each resource the PE has. Individual resources can be accessed by using the [] operator. Each resource object has the following attributes:

offset

Offset for the resource data.

length

Length of the resource data.

type

Type of the resource (integer).

id

ID of the resource (integer).

language

Language of the resource (integer).

type_string

Type of the resource as a string, if specified.

name_string

Name of the resource as a string, if specified.

language_string

Language of the resource as a string, if specified.

All resources must have a type, id (name), and language specified. They can be either an integer or string, but never both, for any given level.

Example: pe.resources[0].type == pe.RESOURCE_TYPE_RCDATA

Example: pe.resources[0].name_string == “F\x00I\x00L\x00E\x00”

Resource types can be inspected using the following constants:

RESOURCE_TYPE_CURSOR
RESOURCE_TYPE_BITMAP
RESOURCE_TYPE_ICON
RESOURCE_TYPE_MENU
RESOURCE_TYPE_DIALOG
RESOURCE_TYPE_STRING
RESOURCE_TYPE_FONTDIR
RESOURCE_TYPE_FONT
RESOURCE_TYPE_ACCELERATOR
RESOURCE_TYPE_RCDATA
RESOURCE_TYPE_MESSAGETABLE
RESOURCE_TYPE_GROUP_CURSOR
RESOURCE_TYPE_GROUP_ICON
RESOURCE_TYPE_VERSION
RESOURCE_TYPE_DLGINCLUDE
RESOURCE_TYPE_PLUGPLAY
RESOURCE_TYPE_VXD
RESOURCE_TYPE_ANICURSOR
RESOURCE_TYPE_ANIICON
RESOURCE_TYPE_HTML
RESOURCE_TYPE_MANIFEST

For more information refer to:

http://msdn.microsoft.com/en-us/library/ms648009(v=vs.85).aspx

version_info

New in version 3.2.0.

Dictionary containing the PE’s version information. Typical keys are:

Comments CompanyName FileDescription FileVersion InternalName LegalCopyright LegalTrademarks OriginalFilename ProductName ProductVersion

For more information refer to:

http://msdn.microsoft.com/en-us/library/windows/desktop/ms646987(v=vs.85).aspx

Example: pe.version_info[“CompanyName”] contains “Microsoft”

number_of_signatures

Number of authenticode signatures in the PE.

signatures

A zero-based array of signature objects, one for each authenticode signature in the PE file. Usually PE files have a single signature.

issuer

A string containing information about the issuer. These are some examples:

"/C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Code Signing PCA"

"/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at https://www.verisign.com/rpa (c)10/CN=VeriSign Class 3 Code Signing 2010 CA"

"/C=GB/ST=Greater Manchester/L=Salford/O=COMODO CA Limited/CN=COMODO Code Signing CA 2"
subject

A string containing information about the subject.

version

Version number.

algorithm

Algorithm used for this signature. Usually “sha1WithRSAEncryption”.

serial

A string containing the serial number. This is an example:

"52:00:e5:aa:25:56:fc:1a:86:ed:96:c9:d4:4b:33:c7"
not_before

Unix timestamp on which the validity period for this signature begins.

not_after

Unix timestamp on which the validity period for this signature ends.

valid_on(timestamp)

Function returning true if the signature was valid on the date indicated by timestamp. The following sentence:

pe.signatures[n].valid_on(timestamp)

Is equivalent to:

timestamp >= pe.signatures[n].not_before and timestamp <= pe.signatures[n].not_after
rich_signature

Structure containing information about the PE’s rich signature as documented here.

offset

Offset where the rich signature starts. It will be undefined if the file doesn’t have a rich signature.

length

Length of the rich signature, not including the final “Rich” marker.

key

Key used to encrypt the data with XOR.

raw_data

Raw data as it appears in the file.

clear_data

Data after being decrypted by XORing it with the key.

version(version, [toolid])

New in version 3.5.0: Function returning true if the PE has the specified version in the PE’s rich signature. Provide the optional toolid argument to only match when both match for one entry. More information can be found here:

http://www.ntcore.com/files/richsign.htm

Example: pe.rich_signature.version(21005)

toolid(toolid, [version])

New in version 3.5.0: Function returning true if the PE has the specified id in the PE’s rich signature. Provide the optional version argument to only match when both match for one entry. More information can be found here:

http://www.ntcore.com/files/richsign.htm

Example: pe.rich_signature.toolid(222)

exports(function_name)

Function returning true if the PE exports function_name or false otherwise.

Example: pe.exports(“CPlApplet”)

exports(ordinal)

New in version 3.6.0.

Function returning true if the PE exports ordinal or false otherwise.

Example: pe.exports(72)

number_of_exports

New in version 3.6.0.

Number of exports in the PE.

number_of_imports

New in version 3.6.0.

Number of imports in the PE.

imports(dll_name, function_name)

Function returning true if the PE imports function_name from dll_name, or false otherwise. dll_name is case insensitive.

Example: pe.imports(“kernel32.dll”, “WriteProcessMemory”)

imports(dll_name)

New in version 3.5.0.

Function returning true if the PE imports anything from dll_name, or false otherwise. dll_name is case insensitive.

Example: pe.imports(“kernel32.dll”)

imports(dll_name, ordinal)

New in version 3.5.0.

Function returning true if the PE imports ordinal from dll_name, or false otherwise. dll_name is case insensitive.

Example: pe.imports(“WS2_32.DLL”, 3)

locale(locale_identifier)

New in version 3.2.0.

Function returning true if the PE has a resource with the specified locale identifier. Locale identifiers are 16-bit integers and can be found here:

http://msdn.microsoft.com/en-us/library/windows/desktop/dd318693(v=vs.85).aspx

Example: pe.locale(0x0419) // Russian (RU)

language(language_identifier)

New in version 3.2.0.

Function returning true if the PE has a resource with the specified language identifier. Language identifiers are 8-bit integers and can be found here:

http://msdn.microsoft.com/en-us/library/windows/desktop/dd318693(v=vs.85).aspx

Example: pe.language(0x0A) // Spanish

imphash()

New in version 3.2.0.

Function returning the import hash or imphash for the PE. The imphash is a 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.

Example: pe.imphash() == “b8bb385806b89680e13fc0cf24f4431e”

section_index(name)

Function returning the index into the sections array for the section that has name. name is case sensitive.

Example: pe.section_index(”.TEXT”)

section_index(addr)

New in version 3.3.0: Function returning the index into the sections array for the section that has addr. addr can be an offset into the file or a memory address.

Example: pe.section_index(pe.entry_point)

is_dll()

New in version 3.5.0.

Function returning true if the PE is a DLL.

Example: pe.is_dll()

is_32bit()

New in version 3.5.0.

Function returning true if the PE is 32bits.

Example: pe.is_32bit()

is_64bit()

New in version 3.5.0.

Function returning true if the PE is 64bits.

Example: pe.is_64bit()

rva_to_offset(addr)

New in version 3.6.0: Function returning the file offset for RVA addr.

Example: pe.rva_to_offset(pe.entry_point)