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.