# 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**Example: math.count(0x00, 0, 4) < 2*

- 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**Example: math.mode() == 0x00*

- 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"*