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

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

Example: pe.subsystem == pe.SUBSYSTEM_NATIVE

timestamp

PE timestamp.

entry_point

Entry point raw offset or virtual address depending if 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 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.

number_of_sections

Number of sections in the PE.

sections

New in version 3.3.0.

An 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

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.

An 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 an 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 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

An 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 validity period for this signature begins.

not_after

Unix timestamp on which validity period for this signature ends.

valid_on(timestamp)

Function returning true if the signature was valid the on 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 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.

exports(function_name)

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

Example: pe.exports(“CPlApplet”)

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”)

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)