diff --git a/docs/modules.rst b/docs/modules.rst index 869c7091..9259db87 100644 --- a/docs/modules.rst +++ b/docs/modules.rst @@ -17,6 +17,7 @@ the :ref:`writing-modules` section. Cuckoo Magic Hash + Math diff --git a/docs/modules/math.rst b/docs/modules/math.rst new file mode 100644 index 00000000..e8982dc5 --- /dev/null +++ b/docs/modules/math.rst @@ -0,0 +1,100 @@ + +.. _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 often 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)* diff --git a/docs/modules/pe.rst b/docs/modules/pe.rst index 94a0ea47..42c38841 100644 --- a/docs/modules/pe.rst +++ b/docs/modules/pe.rst @@ -37,11 +37,33 @@ Reference Integer with one of the following values: - .. c:type:: MACHINE_I386 + .. c:type:: MACHINE_UNKNOWN + .. c:type:: MACHINE_AM33 .. c:type:: MACHINE_AMD64 + .. c:type:: MACHINE_ARM + .. c:type:: MACHINE_ARMNT + .. c:type:: MACHINE_ARM64 + .. c:type:: MACHINE_EBC + .. c:type:: MACHINE_I386 + .. c:type:: MACHINE_IA64 + .. c:type:: MACHINE_M32R + .. c:type:: MACHINE_MIPS16 + .. c:type:: MACHINE_MIPSFPU + .. c:type:: MACHINE_MIPSFPU16 + .. c:type:: MACHINE_POWERPC + .. c:type:: MACHINE_POWERPCFP + .. c:type:: MACHINE_R4000 + .. c:type:: MACHINE_SH3 + .. c:type:: MACHINE_SH3DSP + .. c:type:: MACHINE_SH4 + .. c:type:: MACHINE_SH5 + .. c:type:: MACHINE_THUMB + .. c:type:: MACHINE_WCEMIPSV2 *Example: pe.machine == pe.MACHINE_AMD64* + .. versionadded:: Expanded in 3.3.0 + .. c:type:: subsystem Integer with one of the following values: @@ -181,6 +203,118 @@ Reference *Example: pe.sections[0].name == ".text"* + Individual section characteristics can be inspected using a bitwise AND + operation with the following constants: + + .. c:type:: SECTION_CNT_CODE + .. c:type:: SECTION_CNT_INITIALIZED_DATA + .. c:type:: SECTION_CNT_UNINITIALIZED_DATA + .. c:type:: SECTION_GPREL + .. c:type:: SECTION_MEM_16BIT + .. c:type:: SECTION_LNK_NRELOC_OVFL + .. c:type:: SECTION_MEM_DISCARDABLE + .. c:type:: SECTION_MEM_NOT_CACHED + .. c:type:: SECTION_MEM_NOT_PAGED + .. c:type:: SECTION_MEM_SHARED + .. c:type:: SECTION_MEM_EXECUTE + .. c:type:: SECTION_MEM_READ + .. c:type:: SECTION_MEM_WRITE + + .. versionadded:: Constants added in 3.3.0 + +.. c:type:: number_of_resources + + Number of resources in the PE. + +.. c:type:: resource_timestamp + + Resource timestamp. This is stored as an integer. + +.. c:type:: resource_version + + An object with two integer attributes, major and minor versions. + + .. c:member:: major + + Major resource version. + + .. c:member:: minor + + Minor resource version. + +.. c:type:: resources + + 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: + + .. c:member:: offset + + Offset for the resource data. + + .. c:member:: length + + Length of the resource data. + + .. c:member:: type + + Type of the resource (integer). + + .. c:member:: id + + ID of the resource (integer). + + .. c:member:: language + + Language of the resource (integer). + + .. c:member:: type_string + + Type of the resource as a string, if specified. + + .. c:member:: name_string + + Name of the resource as a string, if specified. + + .. c:member:: 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.sections[0].type == pe.RESOURCE_TYPE_RCDATA and pe.sections[0].name == "F\x00I\x00L\x00E\x00"* + + Resource types can be inspected using the following constants: + + .. c:type:: RESOURCE_TYPE_CURSOR + .. c:type:: RESOURCE_TYPE_BITMAP + .. c:type:: RESOURCE_TYPE_ICON + .. c:type:: RESOURCE_TYPE_MENU + .. c:type:: RESOURCE_TYPE_DIALOG + .. c:type:: RESOURCE_TYPE_STRING + .. c:type:: RESOURCE_TYPE_FONTDIR + .. c:type:: RESOURCE_TYPE_FONT + .. c:type:: RESOURCE_TYPE_ACCELERATOR + .. c:type:: RESOURCE_TYPE_RCDATA + .. c:type:: RESOURCE_TYPE_MESSAGETABLE + .. c:type:: RESOURCE_TYPE_GROUP_CURSOR + .. c:type:: RESOURCE_TYPE_GROUP_ICON + .. c:type:: RESOURCE_TYPE_VERSION + .. c:type:: RESOURCE_TYPE_DLGINCLUDE + .. c:type:: RESOURCE_TYPE_PLUGPLAY + .. c:type:: RESOURCE_TYPE_VXD + .. c:type:: RESOURCE_TYPE_ANICURSOR + .. c:type:: RESOURCE_TYPE_ANIICON + .. c:type:: RESOURCE_TYPE_HTML + .. c:type:: RESOURCE_TYPE_MANIFEST + + For more information refer to: + + http://msdn.microsoft.com/en-us/library/ms648009(v=vs.85).aspx + + .. versionadded:: Expanded in 3.3.0 + .. c:type:: version_info Dictionary containing PE's version information. Typical keys are: @@ -333,3 +467,19 @@ Reference *Example: pe.imphash() == "b8bb385806b89680e13fc0cf24f4431e"* .. versionadded:: 3.2.0 + +.. c:function:: 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")* + +.. c:function:: section_index(addr) + + 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)* + + .. versionadded:: 3.3.0