[Forensics-changes] [yara] 132/135: Update the documentation
Hilko Bengen
bengen at moszumanska.debian.org
Sat Jul 1 10:27:40 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 3daf2bdb1995638b873a136b96cd5d25fccabd7d
Author: Victor M. Alvarez <plusvic at gmail.com>
Date: Tue Aug 26 12:41:53 2014 +0200
Update the documentation
---
docs/capi.rst | 12 +++--
docs/gettingstarted.rst | 73 +++++++++++++++++++++++--------
docs/modules.rst | 2 +-
docs/modules/cuckoo | 9 ++--
docs/modules/magic | 56 ++++++++++++++++++++++++
docs/writingmodules.rst | 114 +++++++++++++++++++++++++++++++++++++-----------
6 files changed, 215 insertions(+), 51 deletions(-)
diff --git a/docs/capi.rst b/docs/capi.rst
index 24a195a..9bc0279 100644
--- a/docs/capi.rst
+++ b/docs/capi.rst
@@ -256,15 +256,19 @@ Data structures
Functions
---------
-.. c:function:: void yr_initialize(void)
+.. c:function:: int yr_initialize(void)
Initalize the library. Must be called by the main thread before using any
- other function.
+ other function. Return :c:macro:`ERROR_SUCCESS` on success another error
+ code in case of error. The list of possible return codes vary according
+ to the modules compiled into YARA.
-.. c:function:: void yr_finalize(void)
+.. c:function:: int yr_finalize(void)
Finalize the library. Must be called by the main free to release any
- resource allocated by the library.
+ resource allocated by the library. Return :c:macro:`ERROR_SUCCESS` on
+ success another error code in case of error. The list of possible return
+ codes vary according to the modules compiled into YARA.
.. c:function:: void yr_finalize_thread(void)
diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst
index 13894cf..ca1903c 100644
--- a/docs/gettingstarted.rst
+++ b/docs/gettingstarted.rst
@@ -12,8 +12,8 @@ Compiling and installing YARA
Download the source tarball and get prepared for compiling it::
- tar -zxf yara-3.0.0.tar.gz
- cd yara-3.0.0
+ tar -zxf yara-3.1.0.tar.gz
+ cd yara-3.1.0
./bootstrap.sh
YARA uses GNU autotools, so it's compiled and installed in the standard
@@ -23,15 +23,39 @@ way::
make
sudo make install
+The following modules are not copiled into YARA by default:
+
+* cuckoo
+* magic
+
+If you plan to use them must pass the corresponding ``--enable-<module name>``
+arguments to the ``configure`` script.
+
+For example::
+
+ ./configure --enable-cuckoo
+ ./configure --enable-magic
+ ./configure --enable-cuckoo --enable-magic
+
+
+Modules usually depends on external libraries, depending on the modules you
+choose to install you'll need the following libraries:
+
+* cuckoo:
+ Depends on `Jansson <http://www.digip.org/jansson/>`_ for parsing JSON.
+ Some Ubuntu and Debian versions already include a package named
+ ``libjansson-dev``, if ``sudo apt-get install libjansson-dev`` doesn't
+ work for you then get the source code from
+ `its repository <https://github.com/akheron/jansson>`_.
+
+
+* magic:
+ Depends on *libmagic*, a library used by the Unix standard program
+ `file <http://en.wikipedia.org/wiki/File_(command)>`_.
+ Ubuntu, Debian and CentOS include a package
+ ``libmagic-dev``. The source code can be found
+ `here <ftp://ftp.astron.com/pub/file/>`_.
-The Cuckoo module is not compiled into YARA by default, if you plan to
-use the Cuckoo module you must pass the ``--enable-cuckoo`` argument to the
-``configure`` script. The Cuckoo module depends on the
-`Jansson library <http://www.digip.org/jansson///>`_, you'll need to install it
-beforehand. Some Debian and Ubuntu versions already include a package named
-``libjansson-dev``, if ``sudo apt-get install libjansson-dev`` doesn't work for
-you then get the source code from
-`its repository <https://github.com/akheron/jansson>`_.
To build and install the ``yara-python`` extension::
@@ -39,19 +63,34 @@ To build and install the ``yara-python`` extension::
python setup.py build
sudo setup.py install
-.. note:: You may need to install the Python development package (usually
- ``python-dev``) before compiling ``yara-python``. Additionally,
- ``yara-python`` depends on the ``libyara`` library which gets installed
- with YARA, so don't proceed to build ``yara-python`` without previously
- installing YARA as described above.
+You may need to install the Python development package (usually ``python-dev``)
+before compiling ``yara-python``. Additionally, ``yara-python`` depends on the
+``libyara`` library which gets installed with YARA, so don't proceed to build
+``yara-python`` without previously installing YARA as described above.
-Installing on OSX with Homebrew
-===============================
+Installing on Windows
+---------------------
+
+Compiled binaries for Windows in both 32 and 64 bits flavors can be found
+in the link below. Just download the version of you want, unzip the archive,
+and put the ``yara.exe`` and ``yarac.exe`` binaries anywhere in your disk.
+
+To install the ``yara-python`` extension download an execute the installer
+corresponding to the version of Python you're using.
+
+`Download Windows binaries <https://b161268c3bf5a87bc67309e7c870820f5f39f672.googledrive.com/host/0BznOMqZ9f3VUek8yN3VvSGdhRFU/>`_
+
+If you want to build YARA yourself you can use the *Visual Studio 2010* project
+found in the source tree under *./windows/yara*.
+
+Installing on Mac OS X with Homebrew
+------------------------------------
To install YARA using `Homebrew <http://brew.sh>`_ simply type
``brew install yara``.
+
Running YARA for the first time
===============================
diff --git a/docs/modules.rst b/docs/modules.rst
index 9a43fa4..17b4f92 100644
--- a/docs/modules.rst
+++ b/docs/modules.rst
@@ -10,7 +10,7 @@ the :ref:`writing-modules` section.
.. include:: modules/pe
.. include:: modules/cuckoo
-
+.. include:: modules/magic
diff --git a/docs/modules/cuckoo b/docs/modules/cuckoo
index 6855563..1cb5423 100644
--- a/docs/modules/cuckoo
+++ b/docs/modules/cuckoo
@@ -10,6 +10,11 @@ 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*.
+.. important::
+ This module is not built into YARA by default, to learn how to include it
+ refer to :ref:`compiling-yara`. Good news for Windows users: this module
+ is already included in the official Windows binaries.
+
Suppose that you're interested in executable files sending a HTTP request to
http://someone.doingevil.com. In previous versions of YARA you had to settle
with::
@@ -79,10 +84,6 @@ If you are using ``yara-python`` then you must pass the behavior report in the
rules.match(pe_file, modules_data={'cuckoo': bytes(report_data)})
-.. important::
- The ``cuckoo`` module is not built into YARA by default, to learn how to
- build YARA with Cuckoo support refer to :ref:`compiling-yara`.
-
Cuckoo module reference
-----------------------
diff --git a/docs/modules/magic b/docs/modules/magic
new file mode 100644
index 0000000..5f4b152
--- /dev/null
+++ b/docs/modules/magic
@@ -0,0 +1,56 @@
+
+.. _magic-module:
+
+############
+Magic module
+############
+
+The Magic module allows you to identify the type of the file based on the
+output of `file <http://en.wikipedia.org/wiki/File_(command)>`_, the standard
+Unix command.
+
+.. important::
+ This module is not built into YARA by default, to learn how to include it
+ refer to :ref:`compiling-yara`. Bad news for Windows users: **this module is
+ not supported on Windows**.
+
+There are two functions in this module: :c:func:`type` and :c:func:`mime_type`.
+The first one returns the descriptive string returned by *file*, for example,
+if you run *file* against some PDF document you'll get something like this::
+
+ $file some.pdf
+ some.pdf: PDF document, version 1.5
+
+The :c:func:`type` function would return *"PDF document, version 1.5"* in this
+case. Using the :c:func:`mime_type` function is similar to passing the
+``--mime`` argument to *file*.::
+
+ $file --mime some.pdf
+ some.pdf: application/pdf; charset=binary
+
+
+:c:func:`mime_type` would return *"application/pdf"*, without the charset part.
+
+By experimenting a little with the *file* command you can learn which output to
+expect for different file types. These are a few examples:
+
+ * JPEG image data, JFIF standard 1.01
+ * PE32 executable for MS Windows (GUI) Intel 80386 32-bit
+ * PNG image data, 1240 x 1753, 8-bit/color RGBA, non-interlaced
+ * ASCII text, with no line terminators
+ * Zip archive data, at least v2.0 to extract
+
+
+
+.. c:function:: type()
+
+ Function returning a string with the type of the file.
+
+ *Example: magic.type() contains "PDF"*
+
+
+.. c:function:: mime_type()
+
+ Function returning a string with the MIME type of the file.
+
+ *Example: magic.mime_type() == "application/pdf"*
diff --git a/docs/writingmodules.rst b/docs/writingmodules.rst
index 5e09aa7..29289d3 100644
--- a/docs/writingmodules.rst
+++ b/docs/writingmodules.rst
@@ -43,9 +43,21 @@ as our starting point. The file looks like this:
end_declarations;
+ int module_initialize(
+ YR_MODULE* module)
+ {
+ return ERROR_SUCCESS;
+ }
+
+ int module_finalize(
+ YR_MODULE* module)
+ {
+ return ERROR_SUCCESS;
+ }
+
int module_load(
YR_SCAN_CONTEXT* context,
- YR_OBJECT* module,
+ YR_OBJECT* module_object,
void* module_data,
size_t module_data_size)
{
@@ -54,7 +66,7 @@ as our starting point. The file looks like this:
}
int module_unload(
- YR_OBJECT* module)
+ YR_OBJECT* module_object)
{
return ERROR_SUCCESS;
}
@@ -69,7 +81,8 @@ first line in the code is:
#include <yara/modules.h>
The *modules.h* header file is where the definitions for YARA's module API
-reside, therefore this include directive is required in all your modules. The second line is:
+reside, therefore this include directive is required in all your modules. The
+second line is:
.. code-block:: c
@@ -94,17 +107,38 @@ be available for your YARA rules. In this case we are declaring just a
string variable named *greeting*. We are going to discuss these concepts more
in greater detail in the :ref:`declaration-section`.
+After the declaration section you'll find a pair of functions:
+
+.. code-block:: c
+
+ int module_initialize(
+ YR_MODULE* module)
+ {
+ return ERROR_SUCCESS;
+ }
+
+ int module_finalize(
+ YR_MODULE* module)
+ {
+ return ERROR_SUCCESS;
+ }
+
+The ``module_initialize`` function is called during YARA's initializtion while
+its counterpart ``module_finalize`` is called while finalizing YARA. These
+functions allows you initialize and finalize any global data structure you may
+need to use in your module.
+
Then comes the ``module_load`` function:
.. code-block:: c
int module_load(
YR_SCAN_CONTEXT* context,
- YR_OBJECT* module,
+ YR_OBJECT* module_object,
void* module_data,
size_t module_data_size)
{
- set_string("Hello World!", module, "greeting");
+ set_string("Hello World!", module_object, "greeting");
return ERROR_SUCCESS;
}
@@ -124,7 +158,7 @@ And finally, we have the ``module_unload`` function:
.. code-block:: c
int module_unload(
- YR_OBJECT* module)
+ YR_OBJECT* module_object)
{
return ERROR_SUCCESS;
}
@@ -388,10 +422,41 @@ the declaration section, like this::
We are going to discuss function implementation more in depth in the
:ref:`implementing-functions` section.
+Initialization and finalization
+===============================
+
+Every module must implement two functions for initialization and finalization:
+``module_initialize`` and ``module_finalize``. The former is called during
+YARA's initialization by :c:func:`yr_initialize` while the latter is called
+during finalization by :c:func:`yr_finalize`. Both functions are invoked
+whether or not the module is being imported by some rule.
+
+These functions give your module an opportunity to initialize any global data
+structure it may need, but most of the times they are just empty functions:
+
+.. code-block:: c
+
+ int module_initialize(
+ YR_MODULE* module)
+ {
+ return ERROR_SUCCESS;
+ }
+
+ int module_finalize(
+ YR_MODULE* module)
+ {
+ return ERROR_SUCCESS;
+ }
+
+Any returned value different from ``ERROR_SUCCESS`` will abort YARA's execution.
+
+
+
Implementing the module's logic
===============================
-Every module must implement two functions which are called by YARA during the
+Besides ``module_initialize`` and ``module_finalize`` Every module must
+implement two other 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``
@@ -404,12 +469,12 @@ The ``module_load`` function has the following prototype:
int module_load(
YR_SCAN_CONTEXT* context,
- YR_OBJECT* module,
+ YR_OBJECT* module_object,
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
+including the data being scanned. The ``module_object`` 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``
@@ -443,7 +508,7 @@ 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,
+In resume, the ``module_object`` 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.
@@ -473,7 +538,7 @@ blocks by using the ``foreach_memory_block`` macro:
int module_load(
YR_SCAN_CONTEXT* context,
- YR_OBJECT* module,
+ YR_OBJECT* module_object,
void* module_data,
size_t module_data_size)
{
@@ -524,7 +589,7 @@ checks in your code nevertheless). In those cases you can use the
int module_load(
YR_SCAN_CONTEXT* context,
- YR_OBJECT* module,
+ YR_OBJECT* module_object,
void* module_data,
size_t module_data_size)
{
@@ -594,16 +659,15 @@ And the value for ``qux`` like this:
set_integer(<value>, object, "baz.qux");
-Do you remember that the ``module`` argument for ``module_load`` was a pointer
-to a ``YR_OBJECT``? Do you remember that this ``YR_OBJECT`` is an structure just
-like ``bar`` is? Well, you could also set the values for ``bar`` and
-``qux`` like this:
+Do you remember that the ``module_object`` argument for ``module_load`` was a
+pointer to a ``YR_OBJECT``? Do you remember that this ``YR_OBJECT`` is an
+structure just like ``bar`` is? Well, you could also set the values for ``bar``
+and ``qux`` like this:
.. code-block:: c
- set_string(<value>, module, "foo.bar");
- set_integer(<value>, module, "foo.baz.qux");
-
+ set_string(<value>, module_object, "foo.bar");
+ set_integer(<value>, module_object, "foo.baz.qux");
But what happens with arrays? How can I set the value for array items? If
you have the following declarations::
@@ -665,8 +729,8 @@ Are the following two lines equivalent? Why?
.. code-block:: c
- set_integer(1, get_object(module, "foo.bar"), NULL);
- set_integer(1, module, "foo.bar");
+ set_integer(1, get_object(module_object, "foo.bar"), NULL);
+ set_integer(1, module_object, "foo.bar");
.. _storing-data-for-later-use:
@@ -700,12 +764,12 @@ following example:
int module_load(
YR_SCAN_CONTEXT* context,
- YR_OBJECT* module,
+ YR_OBJECT* module_object,
void* module_data,
size_t module_data_size)
{
module->data = yr_malloc(sizeof(MY_DATA));
- ((MY_DATA*) module->data)->some_integer = 0;
+ ((MY_DATA*) module_object->data)->some_integer = 0;
return ERROR_SUCCESS;
}
@@ -715,9 +779,9 @@ Don't forget to release the allocated memory in the ``module_unload`` function:
.. code-block:: cpp
int module_unload(
- YR_OBJECT* module)
+ YR_OBJECT* module_object)
{
- yr_free(module->data);
+ yr_free(module_object->data);
return ERROR_SUCCESS;
}
--
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