.. _math-module:

###########
Math module
###########

.. versionadded:: 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)*

.. c:function:: 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*

.. c:function:: entropy(string)

    Returns the entropy for the given string.

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

.. c:function:: 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*

.. c:function:: monte_carlo_pi(string)

    Return the percentage away from Pi for the given string.

.. c:function:: 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*

.. c:function:: serial_correlation(string)

    Return the serial correlation for the given string.

.. c:function:: 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*

.. c:function:: mean(string)

    Return the mean for the given string.

.. c:function:: 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*

.. c:function:: deviation(string, mean)

    Return the deviation from the mean for the given string.

.. c:function:: 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)*

.. c:function:: max(int, int)

    .. versionadded:: 3.8.0

    Returns the maximum of two unsigned integer values.

.. c:function:: min(int, int)

    .. versionadded:: 3.8.0

    Returns the minimum of two unsigned integer values.

.. c:function:: to_number(bool)

    .. versionadded:: 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*

.. c:function:: abs(int)

    .. versionadded:: 4.2.0

    Returns the absolute value of the signed integer.

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

.. c:function:: count(byte, offset, size)

    .. versionadded:: 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*

.. c:function:: percentage(byte, offset, size)

    .. versionadded:: 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*

.. c:function:: mode(offset, size)

    .. versionadded:: 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*

.. c:function:: to_string(int)

    .. versionadded:: 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"*

.. c:function:: to_string(int, base)

    .. versionadded:: 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"*