[Forensics-changes] [yara] 331/368: Update documentation
Hilko Bengen
bengen at moszumanska.debian.org
Sat Jul 1 10:30:54 UTC 2017
This is an automated email from the git hooks/post-receive script.
bengen pushed a commit to annotated tag v3.5.0
in repository yara.
commit 18500039fe2246ddfb62a0533b37e2ad12cad9df
Author: plusvic <plusvic at gmail.com>
Date: Mon Jun 20 10:37:43 2016 +0200
Update documentation
---
docs/capi.rst | 11 +++++----
docs/gettingstarted.rst | 62 +++++++++++++++++++++++++++----------------------
docs/writingrules.rst | 15 ++++++++++++
3 files changed, 55 insertions(+), 33 deletions(-)
diff --git a/docs/capi.rst b/docs/capi.rst
index bffa054..80f039c 100644
--- a/docs/capi.rst
+++ b/docs/capi.rst
@@ -165,8 +165,9 @@ depending if the rule is matching or not. In both cases a pointer to the
``message_data`` argument. You just need to perform a typecast from
``void*`` to ``YR_RULE*`` to access the structure.
-The callback is also called once for each imported module, with the
-``CALLBACK_MSG_IMPORT_MODULE`` message. In this case ``message_data`` points
+This callback is also called with the ``CALLBACK_MSG_IMPORT_MODULE`` message.
+All modules referenced by a ``import`` statement in the rules are imported once
+for every file being scanned. . In this case ``message_data`` points
to a :c:type:`YR_MODULE_IMPORT` structure. This structure contains a
``module_name`` field pointing to a null terminated string with the name of the
module being imported and two other fields ``module_data`` and
@@ -176,10 +177,10 @@ while setting ``module_data_size`` to the size of the data. This way you can
pass additional data to those modules requiring it, like the
:ref:`Cuckoo-module` for example.
-The callback is also called once for each file that is scanned by each module
-that is imported. When this happens ``message_data`` points to a
+Once a module is imported the callback is called again with the
+CALLBACK_MSG_MODULE_IMPORTED. When this happens ``message_data`` points to a
:c:type:`YR_OBJECT_STRUCTURE` structure. This structure contains all the
-information from the module, including any stored data and functions.
+information provided by the module about the currently scanned file.
Lastly, the callback function is also called with the
``CALLBACK_MSG_SCAN_FINISHED`` message when the scan is finished. In this case
diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst
index 63d3f72..90f14a5 100644
--- a/docs/gettingstarted.rst
+++ b/docs/gettingstarted.rst
@@ -3,7 +3,7 @@ Getting started
***************
YARA is a multi-platform program running on Windows, Linux and Mac OS X. You can
-find the latest release at https://github.com/plusvic/yara/releases.
+find the latest release at https://github.com/VirusTotal/yara/releases.
.. _compiling-yara:
@@ -12,24 +12,37 @@ Compiling and installing YARA
Download the source tarball and get prepared for compiling it::
- tar -zxf yara-3.1.0.tar.gz
- cd yara-3.1.0
+ tar -zxf yara-3.5.0.tar.gz
+ cd yara-3.5.0
./bootstrap.sh
-YARA uses GNU autotools, so it's compiled and installed in the standard
-way::
+Make sure you have ``automake``, ``libtool``, ``make`` and ``gcc`` installed
+in your system. Ubuntu and Debian users can use::
+
+ sudo apt-get automake libtool make gcc
+
+If you plan to modify YARA's source code you may also need ``flex`` and
+``bison`` for generating lexers and parsers::
+
+ sudo apt-get flex bison
+
+Compile and install YARA in the standard way::
./configure
make
sudo make install
-Some YARA's features depends on the OpenSSL library. Those features are
-built into YARA only if you have the OpenSSL library installed in your
-system. The ``configure`` script will automatically detect if OpenSSL is
-installed or not. If you want to make sure that YARA is built with
-OpenSSL-dependant features you must pass ``--with-crypto`` to the ``configure``
-script.
+Run the test cases to make sure that everything is fine::
+
+ make check
+Some YARA's features depends on the OpenSSL library. Those features are
+enabled only if you have the OpenSSL library installed in your system. If not,
+YARA is going to work fine but you won't be able to use the disabled features.
+The ``configure`` script will automatically detect if OpenSSL is installed or
+not. If you want to enforce the OpenSSL-dependant features you must pass
+``--with-crypto`` to the ``configure`` script. Ubuntu and Debian users can
+use ``sudo apt-get install libssl-dev`` to install the OpenSSL library.
The following modules are not copiled into YARA by default:
@@ -64,17 +77,6 @@ choose to install you'll need the following libraries:
`here <ftp://ftp.astron.com/pub/file/>`_.
-To build and install the ``yara-python`` extension::
-
- cd yara-python
- python setup.py build
- sudo python setup.py install
-
-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 Windows
---------------------
@@ -87,8 +89,9 @@ 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*.
+If you want to build YARA yourself you can use the *Visual Studio 2010* or
+*Visual Studio 2015* projects found in the source tree under *./windows/vs2010*
+and *./windows/vs2015* respectively.
Installing on Mac OS X with Homebrew
------------------------------------
@@ -97,6 +100,13 @@ To install YARA using `Homebrew <http://brew.sh>`_ simply type
``brew install yara``.
+Installing yara-python
+----------------------
+
+If you plan to use YARA from your Python scripts you need to install the
+``yara-python`` extension. Please refer to https://github.com/VirusTotal/yara-python
+for instructions on how to install it.
+
Running YARA for the first time
===============================
@@ -129,7 +139,3 @@ libraries in this path by default, we must instruct him to do so by adding
sudo echo "/usr/local/lib" >> /etc/ld.so.conf
sudo ldconfig
-
-
-
-
diff --git a/docs/writingrules.rst b/docs/writingrules.rst
index c18fd3d..82a0dd0 100644
--- a/docs/writingrules.rst
+++ b/docs/writingrules.rst
@@ -573,6 +573,21 @@ $a by using @a[i]. The indexes are one-based, so the first occurrence would be
number of occurrences of the string, the result will be a NaN (Not A Number)
value.
+
+Match length
+------------
+
+For many regular expressions and hex strings containing jumps, the length of
+the match is variable. If you have the regular expression /fo*/ the strings
+"fo", "foo" and "fooo" can be matches, all of them with a different length.
+
+You can use the length of the matches as part of your condition by using the
+character ! in front of the string identifier, in a similar way you use the @
+character for the offset. !a[1] is the length for the first match of $a, !a[2]
+is the length for the second match, and so on. !a is a abbreviated form of
+!a[1].
+
+
File size
---------
--
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