[Forensics-changes] [yara] 62/135: Update documentation and remove old one
Hilko Bengen
bengen at moszumanska.debian.org
Sat Jul 1 10:27:32 UTC 2017
This is an automated email from the git hooks/post-receive script.
bengen pushed a commit to annotated tag v3.1.0
in repository yara.
commit 3c577a736bde75ec04e3ae7c6acd7c0efcbde932
Author: Victor M. Alvarez <plusvic at gmail.com>
Date: Tue Jul 15 17:20:20 2014 +0200
Update documentation and remove old one
---
doc/YARA User's Manual.pdf | Bin 266491 -> 0 bytes
docs/commandline.rst | 6 ++++
docs/modules/cuckoo | 19 +++++++-----
docs/modules/pe | 4 +--
docs/writingmodules.rst | 73 ++++++++++++++++++++++++++++++++++++++++++++-
5 files changed, 91 insertions(+), 11 deletions(-)
diff --git a/doc/YARA User's Manual.pdf b/doc/YARA User's Manual.pdf
deleted file mode 100644
index 43a9e13..0000000
Binary files a/doc/YARA User's Manual.pdf and /dev/null differ
diff --git a/docs/commandline.rst b/docs/commandline.rst
index 98676bd..ee79f47 100644
--- a/docs/commandline.rst
+++ b/docs/commandline.rst
@@ -1,3 +1,5 @@
+.. _command-line:
+
********************************
Using YARA from the command-line
********************************
@@ -64,6 +66,10 @@ Available options are:
Define external variable.
+.. option:: -x <module>=<file>
+
+ Pass file's content as extra data to module.
+
.. option:: -r
Recursively search for directories.
diff --git a/docs/modules/cuckoo b/docs/modules/cuckoo
index ffaf5e1..91ad542 100644
--- a/docs/modules/cuckoo
+++ b/docs/modules/cuckoo
@@ -1,9 +1,11 @@
+.. _cuckoo-module:
+
#############
Cuckoo module
#############
The Cuckoo module enables you to create YARA rules based on behavioral
-information generated by a `Cuckoo sanbox <http://www.cuckoosandbox.org//>`_.
+information generated by a `Cuckoo sandbox <http://www.cuckoosandbox.org//>`_.
While scanning a PE file with YARA, you can pass additional information about
its behavior to the ``cuckoo`` module and create rules based not only in what
it *contains*, but also in what it *does*.
@@ -24,13 +26,13 @@ with::
The problem with this rule is that the domain name could be contained in the
file for perfectly valid reasons not related with sending HTTP requests to
-http://someone.doingevil.com. Furthermore, the malicious executable doing the
-HTTP request could contain the domain name ciphered or obfuscated, in which case
-your rule would be completely useless.
+http://someone.doingevil.com. Furthermore, the malicious executable could
+contain the domain name ciphered or obfuscated, in which case your rule
+would be completely useless.
-But now with the ``cuckoo`` module you can take the behavior report generated for
-the executable file by your Cuckoo sandbox, pass it alongside the
-executable file to be scanned to YARA, and write a rule like this::
+But now with the ``cuckoo`` module you can take the behavior report generated
+for the executable file by your Cuckoo sandbox, pass it alongside the
+executable file to YARA, and write a rule like this::
import "cuckoo"
@@ -40,7 +42,8 @@ executable file to be scanned to YARA, and write a rule like this::
cuckoo.network.http_request(/http://someone\.doingevil\.com/)
}
-Of course you can also search for strings inside the file as always::
+Of course you can mix your behavior-related conditions with good old
+string-based conditions::
import "cuckoo"
diff --git a/docs/modules/pe b/docs/modules/pe
index 0b4632b..5dbfc85 100644
--- a/docs/modules/pe
+++ b/docs/modules/pe
@@ -184,13 +184,13 @@ PE module reference
.. c:function:: exports(function_name)
Function returning true if the PE exports *function_name* or
- false if otherwise.
+ false otherwise.
*Example: pe.exports("CPlApplet")*
.. c:function:: imports(dll_name, function_name)
Function returning true if the PE imports *function_name* from *dll_name*,
- or false if otherwise. *dll_name* is case insensitive.
+ or false otherwise. *dll_name* is case insensitive.
*Example: pe.imports("kernel32.dll", "WriteProcessMemory")*
diff --git a/docs/writingmodules.rst b/docs/writingmodules.rst
index a4284d7..a69d822 100644
--- a/docs/writingmodules.rst
+++ b/docs/writingmodules.rst
@@ -90,7 +90,7 @@ Then follows the declaration section:
Here is where the module declares the functions and data structures that will
be available later for YARA your rules. In this case we are declaring just a
string variable named *greeting*. We are going to discuss more in depth about
-the declaration section
+this in :ref:`declaration-section`.
Then comes the ``module_load`` function:
@@ -206,6 +206,7 @@ Now you should be able to create a rule like this::
Any file scanned with this rule will match the ``HelloWord`` because
``demo.greeting == "Hello World!"`` is always true.
+.. _declaration-section:
The declaration section
=======================
@@ -312,6 +313,76 @@ declare arrays of them::
end_declarations;
+Implementing your module's logic
+================================
+
+Every module must implement two functions which are called by YARA during the
+scanning of a file or process memory space: ``module_load`` and ``module_unload``.
+Both functions are called once for each scanned file or process, but only if
+the module was imported by means of the ``import`` directive. If the module is
+not imported by some rule neither ``module_load`` nor ``module_unload``
+will be called.
+
+The ``module_load`` function has the following prototype:
+
+.. code-block:: c
+
+ int module_load(
+ YR_SCAN_CONTEXT* context,
+ YR_OBJECT* module,
+ void* module_data,
+ size_t module_data_size)
+
+The ``context`` argument contains information relative to the current scan,
+including the data being scanned. The ``module`` argument is a pointer to
+a ``YR_OBJECT`` structure associated to the module. Each structure, variable or function declared in a YARA module is represented by a ``YR_OBJECT`` structure. These structures conform a tree whose root is the module's ``YR_OBJECT`` structure. If you have the following declarations in a
+module named
+*mymodule*::
+
+ begin_declarations;
+
+ integer("foo");
+
+ begin_struct("bar");
+
+ string("baz");
+
+ end_struct("bar");
+
+ end_declarations;
+
+Then the tree will look like this::
+
+ YR_OBJECT(type=OBJECT_TYPE_STRUCT, name="mymodule")
+ |
+ |_ YR_OBJECT(type=OBJECT_TYPE_INTEGER, name="foo")
+ |
+ |_ YR_OBJECT(type=OBJECT_TYPE_STRUCT, name="bar")
+ |
+ |_ YR_OBJECT(type=OBJECT_TYPE_STRING, name="baz")
+
+Notice that both *bar* and *mymodule* are of the same type
+``OBJECT_TYPE_STRUCT``, which means that the ``YR_OBJECT`` associated to the
+module is just another structure like *bar*. In fact, when you write in your
+rules something like ``mymodule.foo`` you're performing a field lookup in a
+structure in the same way that ``bar.baz`` does.
+
+In resume, the ``module`` argument allows you to access every variable,
+structure or function declared by the module by providing a pointer to the
+root of the objects tree.
+
+The ``module_data`` argument is a pointer to any additional data passed to the
+module, and ``module_data_size`` is the size of that data. Not all modules
+require additional data, most of them rely on the data being scanned alone, but
+a few of them require more information to work. The :ref:`cuckoo-module` is a
+good example of this, it receives a behavior report associated to PE
+files being scanned, and that behavior report is passed in the ``module_data``
+and ``module_data_size`` arguments.
+
+For more information on how to pass additional data to your module take a look
+at the ``-x`` command-line argument in :ref:`command-line`.
+
+
Functions
=========
--
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