[Forensics-changes] [yara] 340/407: Add docs for new stuff.
Hilko Bengen
bengen at moszumanska.debian.org
Sat Jul 1 10:28:43 UTC 2017
This is an automated email from the git hooks/post-receive script.
bengen pushed a commit to annotated tag v3.3.0
in repository yara.
commit b8cfec8d603bef5651c70ae7a9726fc701ae0804
Author: Wesley Shields <wxs at atarininja.org>
Date: Sat Jan 10 23:11:58 2015 -0500
Add docs for new stuff.
---
docs/modules.rst | 1 +
docs/modules/math.rst | 100 +++++++++++++++++++++++++++++++++
docs/modules/pe.rst | 152 +++++++++++++++++++++++++++++++++++++++++++++++++-
3 files changed, 252 insertions(+), 1 deletion(-)
diff --git a/docs/modules.rst b/docs/modules.rst
index 869c709..9259db8 100644
--- a/docs/modules.rst
+++ b/docs/modules.rst
@@ -17,6 +17,7 @@ the :ref:`writing-modules` section.
Cuckoo <modules/cuckoo>
Magic <modules/magic>
Hash <modules/hash>
+ Math <modules/math>
diff --git a/docs/modules/math.rst b/docs/modules/math.rst
new file mode 100644
index 0000000..e8982dc
--- /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 94a0ea4..42c3884 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
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/forensics/yara.git
More information about the forensics-changes
mailing list