Math module

New in version 3.3.0.

The Math module allows you to calculate certain values from portions of your file and create signatures based on those results.

Important

Where noted these functions return floating point numbers. YARA is able to convert integers to floating point numbers during most operations. For example this will convert 7 to 7.0 automatically, because the return type of the entropy function is a floating point value:

math.entropy(0, filesize) >= 7

The one exception to this is when a function requires a floating point number as an argument. For example, this will cause a syntax error because the arguments must be floating point numbers:

math.in_range(2, 1, 3)

entropy(offset, size)

Returns the entropy for size bytes starting at offset. When scanning a running process the offset argument should be a virtual address within the process address space. The returned value is a float.

Example: math.entropy(0, filesize) >= 7

entropy(string)

Returns the entropy for the given string.

Example: math.entropy("dummy") > 7

monte_carlo_pi(offset, size)

Returns the percentage away from Pi for the size bytes starting at offset when run through the Monte Carlo from Pi test. When scanning a running process the offset argument should be a virtual address within the process address space. The returned value is a float.

Example: math.monte_carlo_pi(0, filesize) < 0.07

monte_carlo_pi(string)

Return the percentage away from Pi for the given string.

serial_correlation(offset, size)

Returns the serial correlation for the size bytes starting at offset. When scanning a running process the offset argument should be a virtual address within the process address space. The returned value is a float between 0.0 and 1.0.

Example: math.serial_correlation(0, filesize) < 0.2

serial_correlation(string)

Return the serial correlation for the given string.

mean(offset, size)

Returns the mean for the size bytes starting at offset. When scanning a running process the offset argument should be a virtual address within the process address space. The returned value is a float.

Example: math.mean(0, filesize) < 72.0

mean(string)

Return the mean for the given string.

deviation(offset, size, mean)

Returns the deviation from the mean for the size bytes starting at offset. When scanning a running process the offset argument should be a virtual address within the process address space. The returned value is a float.

The mean of an equally distributed random sample of bytes is 127.5, which is available as the constant math.MEAN_BYTES.

Example: math.deviation(0, filesize, math.MEAN_BYTES) == 64.0

deviation(string, mean)

Return the deviation from the mean for the given string.

in_range(test, lower, upper)

Returns true if the test value is between lower and upper values. The comparisons are inclusive.

Example: math.in_range(math.deviation(0, filesize, math.MEAN_BYTES), 63.9, 64,1)

max(int, int)

New in version 3.8.0.

Returns the maximum of two unsigned integer values.

min(int, int)

New in version 3.8.0.

Returns the minimum of two unsigned integer values.

to_number(bool)

New in version 4.1.0.

Returns 0 or 1, it's useful when writing a score based rule.

Example: math.to_number(SubRule1) * 60 + math.to_number(SubRule2) * 20 + math.to_number(SubRule3) * 70 > 80

abs(int)

New in version 4.2.0.

Returns the absolute value of the signed integer.

Example: math.abs(@a - @b) == 1

count(byte, offset, size)

New in version 4.2.0.

Returns how often a specific byte occurs, starting at offset and looking at the next size bytes. When scanning a running process the offset argument should be a virtual address within the process address space. offset and size are optional; if left empty, the complete file is searched.

Example: math.count(0x4A) >= 10

percentage(byte, offset, size)

New in version 4.2.0.

Returns the occurrence rate of a specific byte, starting at offset and looking at the next size bytes. When scanning a running process the offset argument should be a virtual address within the process address space. The returned value is a float between 0 and 1. offset and size are optional; if left empty, the complete file is searched.

Example: math.percentage(0xFF, filesize-1024, filesize) >= 0.9

Example: math.percentage(0x4A) >= 0.4

mode(offset, size)

New in version 4.2.0.

Returns the most common byte, starting at offset and looking at the next size bytes. When scanning a running process the offset argument should be a virtual address within the process address space. The returned value is a float. offset and size are optional; if left empty, the complete file is searched.

Example: math.mode(0, filesize) == 0xFF

to_string(int)

New in version 4.3.0.

Convert the given integer to a string. Note: integers in YARA are signed.

Example: math.to_string(10) == "10" Example: math.to_string(-1) == "-1"

to_string(int, base)

New in version 4.3.0.

Convert the given integer to a string in the given base. Supported bases are 10, 8 and 16. Note: integers in YARA are signed.

Example: math.to_string(32, 16) == "20" Example: math.to_string(-1, 16) == "ffffffffffffffff"

to_int(string)

New in version 4.3.0.

Convert the given string to a signed integer. If the string starts with "0x" it is treated as base 16. If the string starts with "0" it is treated base 8. Leading '+' or '-' is also supported.

Example: math.to_int("1234") == 1234 Example: math.to_int("-10") == -10 Example: math.to_int("-010" == -8

to_int(string, base)

New in version 4.3.0.

Convert the given string, interpreted with the given base, to a signed integer. Base must be 0 or between 2 and 32 inclusive. If it is zero then the string will be intrepreted as base 16 if it starts with "0x" or as base 8 if it starts with "0". Leading '+' or '-' is also supported.

Example: math.to_int("011", 8) == "9" Example: math.to_int("-011", 0) == "-9"