[Forensics-changes] [yara] 105/192: Minor spelling/grammar fixups. (#609)
Hilko Bengen
bengen at moszumanska.debian.org
Sat Jul 1 10:31:53 UTC 2017
This is an automated email from the git hooks/post-receive script.
bengen pushed a commit to annotated tag v3.6.0
in repository yara.
commit fea921c0691c4bcbf5ef70e09fadeb2cde599fc1
Author: nugxperience <nugxperience at gmail.com>
Date: Thu Feb 16 01:01:33 2017 +1100
Minor spelling/grammar fixups. (#609)
---
docs/capi.rst | 45 ++++++++++++-----------
docs/commandline.rst | 10 +++---
docs/gettingstarted.rst | 24 ++++++-------
docs/modules.rst | 10 +++---
docs/modules/cuckoo.rst | 6 ++--
docs/modules/dotnet.rst | 19 +++++-----
docs/modules/elf.rst | 18 +++++-----
docs/modules/hash.rst | 4 +--
docs/modules/pe.rst | 28 +++++++--------
docs/writingmodules.rst | 77 +++++++++++++++++++--------------------
docs/writingrules.rst | 95 ++++++++++++++++++++++++-------------------------
docs/yarapython.rst | 35 +++++++++---------
12 files changed, 185 insertions(+), 186 deletions(-)
diff --git a/docs/capi.rst b/docs/capi.rst
index 25ddda1..7b25b09 100644
--- a/docs/capi.rst
+++ b/docs/capi.rst
@@ -7,7 +7,7 @@ You can integrate YARA into your C/C++ project by using the API provided by the
same API used by the command-line tools ``yara`` and ``yarac``.
Initializing and finalizing *libyara*
-====================================
+=====================================
The first thing your program must do when using *libyara* is initializing the
library. This is done by calling the :c:func:`yr_initialize()` function. This
@@ -31,7 +31,7 @@ with :c:func:`yr_compiler_destroy`.
You can use :c:func:`yr_compiler_add_file`, :c:func:`yr_compiler_add_fd`, or
:c:func:`yr_compiler_add_string` to add one or more input sources to be
compiled. Both of these functions receive an optional namespace. Rules added
-under the same namespace behaves as if they were contained within the same
+under the same namespace behave as if they were contained within the same
source file or string, so, rule identifiers must be unique among all the sources
sharing a namespace. If the namespace argument is ``NULL`` the rules are put
in the *default* namespace.
@@ -59,9 +59,9 @@ Possible values for ``error_level`` are ``YARA_ERROR_LEVEL_ERROR`` and
``YARA_ERROR_LEVEL_WARNING``. The arguments ``file_name`` and ``line_number``
contains the file name and line number where the error or warning occurs.
``file_name`` is the one passed to :c:func:`yr_compiler_add_file` or
-:c:func:`yr_compiler_add_fd`. It can be ``NULL`` if you passed ``NULL`` or
- if you're using :c:func:`yr_compiler_add_string`. The ``user_data`` pointer
-is the same you passed to :c:func:`yr_compiler_set_callback`.
+:c:func:`yr_compiler_add_fd`. It can be ``NULL`` if you passed ``NULL`` or if
+you're using :c:func:`yr_compiler_add_string`. The ``user_data`` pointer is the
+same you passed to :c:func:`yr_compiler_set_callback`.
After you successfully added some sources you can get the compiled rules
using the :c:func:`yr_compiler_get_rules()` function. You'll get a pointer to
@@ -81,9 +81,9 @@ Saving and retrieving compiled rules
Compiled rules can be saved to a file and retrieved later by using
:c:func:`yr_rules_save` and :c:func:`yr_rules_load`. Rules compiled and saved
in one machine can be loaded in another machine as long as they have the same
-endianness, no matter the operating system or if they are 32-bits or 64-bits
+endianness, no matter the operating system or if they are 32-bit or 64-bit
systems. However files saved with older versions of YARA may not work with
-newer version due to changes in the file layout.
+newer versions due to changes in the file layout.
You can also save and retrieve your rules to and from generic data streams by
using functions :c:func:`yr_rules_save_stream` and
@@ -141,7 +141,7 @@ Scanning data
Once you have an instance of :c:type:`YR_RULES` you can use it with either
:c:func:`yr_rules_scan_file`, :c:func:`yr_rules_scan_fd` or
-:c:func:`yr_rules_scan_mem`. The results from the scan are notified to your
+:c:func:`yr_rules_scan_mem`. The results from the scan are returned to your
program via a callback function. The callback has the following prototype:
.. code-block:: c
@@ -162,21 +162,20 @@ Possible values for ``message`` are::
Your callback function will be called once for each rule with either
a ``CALLBACK_MSG_RULE_MATCHING`` or ``CALLBACK_MSG_RULE_NOT_MATCHING`` message,
depending if the rule is matching or not. In both cases a pointer to the
-:c:type:`YR_RULE` structure associated to the rule is passed in the
+:c:type:`YR_RULE` structure associated with the rule is passed in the
``message_data`` argument. You just need to perform a typecast from
``void*`` to ``YR_RULE*`` to access the structure.
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
-``module_data_size``. These fields are initially set to ``NULL`` and ``0`` ,
-but your program can assign a pointer to some arbitrary data to ``module_data``
-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.
+All modules referenced by an ``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 ``module_data_size``. These
+fields are initially set to ``NULL`` and ``0``, but your program can assign a
+pointer to some arbitrary data to ``module_data`` 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.
Once a module is imported the callback is called again with the
CALLBACK_MSG_MODULE_IMPORTED. When this happens ``message_data`` points to a
@@ -283,7 +282,7 @@ Data structures
.. c:member:: void* module_data
Pointer to additional data passed to the module. Initially set to
- ``NULL``, your program is responsible of setting this pointer while
+ ``NULL``, your program is responsible for setting this pointer while
handling the CALLBACK_MSG_IMPORT_MODULE message.
.. c:member:: size_t module_data_size
@@ -574,7 +573,7 @@ Functions
.. c:function:: yr_rule_metas_foreach(rule, meta)
- Iterate over the :c:type:`YR_META` structures associated to a given rule
+ Iterate over the :c:type:`YR_META` structures associated with a given rule
running the block of code that follows each time with a different value for
*meta*. Example:
@@ -591,7 +590,7 @@ Functions
.. c:function:: yr_rule_strings_foreach(rule, string)
- Iterate over the :c:type:`YR_STRING` structures associated to a given rule
+ Iterate over the :c:type:`YR_STRING` structures associated with a given rule
running the block of code that follows each time with a different value for
*string*. Example:
@@ -608,7 +607,7 @@ Functions
.. c:function:: yr_string_matches_foreach(string, match)
- Iterate over the :c:type:`YR_MATCH` structures associated to a given string
+ Iterate over the :c:type:`YR_MATCH` structures associated with a given string
running the block of code that follows each time with a different value for
*match*. Example:
diff --git a/docs/commandline.rst b/docs/commandline.rst
index c7f6c18..d626bbe 100644
--- a/docs/commandline.rst
+++ b/docs/commandline.rst
@@ -14,7 +14,7 @@ The target can be a file, a folder, or a process. ::
Rule files can be passed directly in source code form, or can be previously
compiled with the ``yarac`` tool. You may prefer to use your rules in compiled
form if you are going to invoke YARA multiple times with the same rules. This
-way you’ll save time, because for YARA is faster to load compiled rules than
+way you’ll save time, because for YARA it is faster to load compiled rules than
compiling the same rules over and over again.
The rules will be applied to the target specified as the last argument to YARA,
@@ -111,12 +111,12 @@ Available options are:
Here you have some examples:
-* Apply rules on */foo/bar/rules1* and */foo/bar/rules2* to all files on current
- directory. Subdirectories are not scanned::
+* Apply rules in */foo/bar/rules1* and */foo/bar/rules2* to all files in the
+ current directory. Subdirectories are not scanned::
yara /foo/bar/rules1 /foo/bar/rules2 .
-* Apply rules on */foo/bar/rules* to *bazfile*. Only reports rules tagged as
+* Apply rules in */foo/bar/rules* to *bazfile*. Only reports rules tagged as
*Packer* or *Compiler*::
yara -t Packer -t Compiler /foo/bar/rules bazfile
@@ -129,7 +129,7 @@ Here you have some examples:
yara -d mybool=true -d myint=5 -d mystring="my string" /foo/bar/rules bazfile
-* Apply rules on */foo/bar/rules* to *bazfile* while passing the content of
+* Apply rules in */foo/bar/rules* to *bazfile* while passing the content of
*cuckoo_json_report* to the cuckoo module::
yara -x cuckoo=cuckoo_json_report /foo/bar/rules bazfile
diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst
index 4c84b11..c6f6c4c 100644
--- a/docs/gettingstarted.rst
+++ b/docs/gettingstarted.rst
@@ -36,21 +36,21 @@ 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
+Some of YARA's features depend 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.
+not. If you want to enforce the OpenSSL-dependent 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 compiled into YARA by default:
* cuckoo
* magic
-If you plan to use them must pass the corresponding ``--enable-<module name>``
-arguments to the ``configure`` script.
+If you plan to use them you must pass the corresponding ``--enable-<module
+name>`` arguments to the ``configure`` script.
For example::
@@ -58,7 +58,7 @@ For example::
./configure --enable-magic
./configure --enable-cuckoo --enable-magic
-Modules usually depends on external libraries, depending on the modules you
+Modules usually depend on external libraries, depending on the modules you
choose to install you'll need the following libraries:
* cuckoo:
@@ -80,11 +80,11 @@ choose to install you'll need the following libraries:
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.
+Compiled binaries for Windows in both 32 and 64 bit flavors can be found in the
+link below. Just download the version 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
+To install the ``yara-python`` extension download and execute the installer
corresponding to the version of Python you're using.
`Download Windows binaries <https://b161268c3bf5a87bc67309e7c870820f5f39f672.googledrive.com/host/0BznOMqZ9f3VUek8yN3VvSGdhRFU/>`_
@@ -134,7 +134,7 @@ If you get an error like this::
It means that the loader is not finding the ``libyara`` library which is
located in ``/usr/local/lib``. In some Linux flavors the loader doesn't look for
-libraries in this path by default, we must instruct him to do so by adding
+libraries in this path by default, we must instruct it to do so by adding
``/usr/local/lib`` to the loader configuration file ``/etc/ld.so.conf``::
sudo echo "/usr/local/lib" >> /etc/ld.so.conf
diff --git a/docs/modules.rst b/docs/modules.rst
index 4113c89..d8f800e 100644
--- a/docs/modules.rst
+++ b/docs/modules.rst
@@ -2,11 +2,11 @@
Modules
*******
-Modules are the way YARA provides for extending its features. They allow to
-define data structures and functions which can be used in your rules to express
-more complex conditions. Here you'll find described some modules officially
-distributed with YARA, but you can also learn how to write your own modules in
-the :ref:`writing-modules` section.
+Modules are the method YARA provides for extending its features. They allow you
+to define data structures and functions which can be used in your rules to
+express more complex conditions. Here you'll find described some modules
+officially distributed with YARA, but you can also learn how to write your own
+modules in the :ref:`writing-modules` section.
.. toctree::
diff --git a/docs/modules/cuckoo.rst b/docs/modules/cuckoo.rst
index fd4c62d..8ecc35a 100644
--- a/docs/modules/cuckoo.rst
+++ b/docs/modules/cuckoo.rst
@@ -7,8 +7,8 @@ Cuckoo module
The Cuckoo module enables you to create YARA rules based on behavioral
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*.
+its behavior to the ``cuckoo`` module and create rules based not only on what
+it *contains*, but also on what it *does*.
.. important::
This module is not built into YARA by default, to learn how to include it
@@ -137,7 +137,7 @@ Reference
.. function:: mutex(regexp)
- Function returning true if the program opens or create a mutex matching
+ Function returning true if the program opens or creates a mutex matching
the provided regular expression.
*Example: cuckoo.sync.mutex(/EvilMutexName/)*
diff --git a/docs/modules/dotnet.rst b/docs/modules/dotnet.rst
index d66b858..a525e02 100644
--- a/docs/modules/dotnet.rst
+++ b/docs/modules/dotnet.rst
@@ -1,9 +1,9 @@
.. _dotnet-module:
-#########
+#############
dotnet module
-#########
+#############
The dotnet module allows you to create more fine-grained rules for .NET files by
using attributes and features of the .NET file format. Let's see some examples::
@@ -46,7 +46,7 @@ Reference
.. c:type:: streams
- An zero-based array of steram objects, one for each stream contained in the
+ A zero-based array of stream objects, one for each stream contained in the
file. Individual streams can be accessed by using the [] operator. Each
stream object has the following attributes:
@@ -70,7 +70,7 @@ Reference
.. c:type:: guids
- An zero-based array of strings, one for each GUID. Individual guids can be
+ A zero-based array of strings, one for each GUID. Individual guids can be
accessed by using the [] operator.
*Example: pe.guids[0].name == "99c08ffd-f378-a891-10ab-c02fe11be6ef"*
@@ -82,8 +82,8 @@ Reference
.. 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
+ A zero-based array of resource objects, one for each resource the .NET file
+ has. Individual resources can be accessed by using the [] operator. Each
resource object has the following attributes:
.. c:member:: offset
@@ -131,10 +131,11 @@ Reference
The number of module references in the .NET file.
-.. c:type:: resources
+.. c:type:: modulerefs
- An zero-based array of strings, one for each module reference the PE has.
- Individual module references can be accessed by using the [] operator.
+ A zero-based array of strings, one for each module reference the .NET file
+ has. Individual module references can be accessed by using the []
+ operator.
*Example: dotnet.modulerefs[0] == "kernel32"*
diff --git a/docs/modules/elf.rst b/docs/modules/elf.rst
index 54577c6..2dd37c9 100644
--- a/docs/modules/elf.rst
+++ b/docs/modules/elf.rst
@@ -8,7 +8,7 @@ ELF module
.. versionadded:: 3.2.0
The ELF module is very similar to the :ref:`pe-module`, but for ELF files. This
-module exposes most of the fields present in a ELF header. Let's see some
+module exposes most of the fields present in an ELF header. Let's see some
examples::
import "elf"
@@ -76,9 +76,9 @@ Reference
.. c:type:: entry_point
- Entry point raw offset or virtual address depending if YARA is scanning a
- file or process memory respectively. This is equivalent to the deprecated
- ``entrypoint`` keyword.
+ Entry point raw offset or virtual address depending on whether YARA is
+ scanning a file or process memory respectively. This is equivalent to the
+ deprecated ``entrypoint`` keyword.
.. c:type:: number_of_sections
@@ -112,7 +112,7 @@ Reference
.. c:member:: type
- Integer with one of the following value:
+ Integer with one of the following values:
.. c:type:: SHT_NULL
@@ -127,7 +127,7 @@ Reference
.. c:type:: SHT_SYMTAB
- The section hold a symbol table.
+ The section holds a symbol table.
.. c:type:: SHT_STRTAB
@@ -168,7 +168,7 @@ Reference
.. c:member:: flags
- Integer with sections's flags as defined below:
+ Integer with section's flags as defined below:
.. c:type:: SHF_WRITE
@@ -196,7 +196,7 @@ Reference
.. versionadded:: 3.4.0
- A zero-based array of segments objects, one for each segment the ELF has.
+ A zero-based array of segment objects, one for each segment the ELF has.
Individual segments can be accessed by using the [] operator. Each segment
object has the following attributes:
@@ -226,7 +226,7 @@ Reference
.. c:member:: memory_size
- On-memory segment size.
+ In-memory segment size.
.. c:member:: offset
diff --git a/docs/modules/hash.rst b/docs/modules/hash.rst
index 96890c4..2a4da4b 100644
--- a/docs/modules/hash.rst
+++ b/docs/modules/hash.rst
@@ -56,11 +56,11 @@ of your file and create signatures based on those hashes.
.. c:function:: checksum32(offset, size)
- Returns a 32-bits checksum for the *size* bytes starting at *offset*. The
+ Returns a 32-bit checksum for the *size* bytes starting at *offset*. The
checksum is just the sum of all the bytes (unsigned).
.. c:function:: checksum32(string)
- Returns a 32-bits checksum for the given string. The checksum is just the
+ Returns a 32-bit checksum for the given string. The checksum is just the
sum of all the bytes in the string (unsigned).
diff --git a/docs/modules/pe.rst b/docs/modules/pe.rst
index bf8a747..bd1fcd0 100644
--- a/docs/modules/pe.rst
+++ b/docs/modules/pe.rst
@@ -98,9 +98,9 @@ Reference
.. c:type:: entry_point
- Entry point raw offset or virtual address depending if YARA is scanning a
- file or process memory respectively. This is equivalent to the deprecated
- ``entrypoint`` keyword.
+ Entry point raw offset or virtual address depending on whether YARA is
+ scanning a file or process memory respectively. This is equivalent to the
+ deprecated ``entrypoint`` keyword.
.. c:type:: image_base
@@ -189,7 +189,7 @@ Reference
.. versionadded:: 3.3.0
- An zero-based array of section objects, one for each section the PE has.
+ A zero-based array of section objects, one for each section the PE has.
Individual sections can be accessed by using the [] operator. Each section
object has the following attributes:
@@ -278,7 +278,7 @@ Reference
.. versionchanged:: 3.3.0
- An zero-based array of resource objects, one for each resource the PE has.
+ A 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:
@@ -314,8 +314,8 @@ Reference
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.
+ All resources must have a type, id (name), and language specified. They can
+ be either an integer or string, but never both, for any given level.
*Example: pe.resources[0].type == pe.RESOURCE_TYPE_RCDATA*
@@ -353,7 +353,7 @@ Reference
.. versionadded:: 3.2.0
- Dictionary containing PE's version information. Typical keys are:
+ Dictionary containing the PE's version information. Typical keys are:
``Comments``
``CompanyName``
@@ -378,7 +378,7 @@ Reference
.. c:type:: signatures
- An zero-based array of signature objects, one for each authenticode
+ A zero-based array of signature objects, one for each authenticode
signature in the PE file. Usually PE files have a single signature.
.. c:member:: issuer
@@ -412,15 +412,15 @@ Reference
.. c:member:: not_before
- Unix timestamp on which validity period for this signature begins.
+ Unix timestamp on which the validity period for this signature begins.
.. c:member:: not_after
- Unix timestamp on which validity period for this signature ends.
+ Unix timestamp on which the validity period for this signature ends.
.. c:member:: valid_on(timestamp)
- Function returning true if the signature was valid the on date
+ Function returning true if the signature was valid on the date
indicated by *timestamp*. The following sentence::
pe.signatures[n].valid_on(timestamp)
@@ -431,8 +431,8 @@ Reference
.. c:type:: rich_signature
- Structure containing information about PE's rich signature as documented
- `here <http://www.ntcore.com/files/richsign.htm>`_.
+ Structure containing information about the PE's rich signature as
+ documented `here <http://www.ntcore.com/files/richsign.htm>`_.
.. c:member:: offset
diff --git a/docs/writingmodules.rst b/docs/writingmodules.rst
index 29ff70d..a99da8d 100644
--- a/docs/writingmodules.rst
+++ b/docs/writingmodules.rst
@@ -104,8 +104,8 @@ Then follows the declaration section:
Here is where the module declares the functions and data structures that will
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`.
+string variable named *greeting*. We are going to discuss these concepts in
+greater detail in the :ref:`declaration-section`.
After the declaration section you'll find a pair of functions:
@@ -125,8 +125,8 @@ After the declaration section you'll find a pair of functions:
The ``module_initialize`` function is called during YARA's initialization 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.
+functions allow you to initialize and finalize any global data structure you
+may need to use in your module.
Then comes the ``module_load`` function:
@@ -146,7 +146,7 @@ Then comes the ``module_load`` function:
This function is invoked once for each scanned file, but only if the module is
imported by some rule with the ``import`` directive. The ``module_load``
function is where your module has the opportunity to inspect the file being
-scanned, parse or analyze it in the way prefered, and then populate the
+scanned, parse or analyze it in the way preferred, and then populate the
data structures defined in the declarations section.
In this example the ``module_load`` function doesn't inspect the file content
@@ -418,7 +418,7 @@ the function.
*<argument types>* is a string containing one character per
function argument, where the character indicates the type of the argument.
Functions can receive four different types of arguments: string, integer, float
-and regular expression, denoted by characters: **s**, **i**, **r** and **f**
+and regular expression, denoted by characters: **s**, **i**, **f** and **r**
respectively. If your function receives two integers *<argument types>* must be
*"ii"*, if it receives an integer as the first argument and a string as the
second one *<argument types>* must be *"is"*, if it receives three strings and
@@ -490,7 +490,7 @@ 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:
+structure it may need, but most of the time they are just empty functions:
.. code-block:: c
@@ -511,7 +511,7 @@ Any returned value different from ``ERROR_SUCCESS`` will abort YARA's execution.
Implementing the module's logic
===============================
-Besides ``module_initialize`` and ``module_finalize`` Every module must
+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
@@ -530,11 +530,12 @@ The ``module_load`` function has the following prototype:
size_t module_data_size)
The ``context`` argument contains information relative to the current scan,
-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``
-structure. If you have the following declarations in a module named *mymodule*::
+including the data being scanned. The ``module_object`` argument is a pointer
+to a ``YR_OBJECT`` structure associated with the module. Each structure,
+variable or function declared in a YARA module is represented by a
+``YR_OBJECT`` structure. These structures form a tree whose root is the
+module's ``YR_OBJECT`` structure. If you have the following declarations in a
+module named *mymodule*::
begin_declarations;
@@ -559,12 +560,12 @@ Then the tree will look like this::
|_ 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
+``OBJECT_TYPE_STRUCT``, which means that the ``YR_OBJECT`` associated with 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_object`` argument allows you to access every variable,
+In summary, 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.
@@ -572,9 +573,9 @@ 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 as input. The :ref:`cuckoo-module` is a
-good example of this, it receives a behavior report associated to PE
-files being scanned which is passed in the ``module_data`` and
-``module_data_size`` arguments.
+good example of this, it receives a behavior report associated with PE files
+being scanned which 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`` argument in :ref:`command-line`.
@@ -584,7 +585,7 @@ at the ``-x`` argument in :ref:`command-line`.
Accessing the scanned data
--------------------------
-Most YARA modules needs to access the file or process memory being scanned to
+Most YARA modules need to access the file or process memory being scanned to
extract information from it. The data being scanned is sent to the module in the
``YR_SCAN_CONTEXT`` structure passed to the ``module_load`` function. The data
is sometimes sliced in blocks, therefore your module needs to iterate over the
@@ -667,9 +668,9 @@ a pointer to the same block (as a ``self`` or ``this`` pointer) and returns a
pointer to the block's data. Your module doesn't own the memory pointed to by
this pointer, freeing that memory is not your responsibility. However keep in
mind that the pointer is valid only until you ask for the next memory block. As
-long you use the pointer within the scope of a ``foreach_memory_block`` you are
-on the safe side. Also take into account that ``fetch_data`` can return a NULL
-pointer, your code must be prepared for that case.
+long as you use the pointer within the scope of a ``foreach_memory_block`` you
+are on the safe side. Also take into account that ``fetch_data`` can return a
+NULL pointer, your code must be prepared for that case.
.. code-block:: c
@@ -733,7 +734,7 @@ descendant of ``object``. For example, consider the following declarations::
end_declarations;
-If ``object`` points to the ``YR_OBJECT`` associated to the ``foo`` structure
+If ``object`` points to the ``YR_OBJECT`` associated with the ``foo`` structure
you can set the value for the ``bar`` string like this:
.. code-block:: c
@@ -748,7 +749,7 @@ And the value for ``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
+pointer to a ``YR_OBJECT``? Do you remember that this ``YR_OBJECT`` is a
structure just like ``bar`` is? Well, you could also set the values for ``bar``
and ``qux`` like this:
@@ -785,11 +786,11 @@ Then the following statements are all valid:
set_string(<value>, module, "bar[%i].qux[%i]", 100, 200);
Those ``%i`` in the field descriptor are replaced by the additional
-integer arguments passed to the function. This work in the same way than
+integer arguments passed to the function. This works in the same way as
``printf`` in C programs, but the only format specifiers accepted are ``%i``
and ``%s``, for integer and string arguments respectively.
-The ``%s`` format specifiers is used for assigning values to a certain key
+The ``%s`` format specifier is used for assigning values to a certain key
in a dictionary:
.. code-block:: c
@@ -799,12 +800,12 @@ in a dictionary:
set_string(<value>, module, "bar[%s].baz", "another_key");
If you don't explicitly assign a value to a declared variable, array or
-dictionary item it will remain in undefined state. That's not a problem at all,
-and is even useful in many cases. For example, if your module parses files from
-certain format and it receives one from a different format, you can safely leave
-all your variables undefined instead of assigning them bogus values that doesn't
-make sense. YARA will handle undefined values in rule conditions as described in
-:ref:`using-modules`.
+dictionary item it will remain in an undefined state. That's not a problem at
+all, and is even useful in many cases. For example, if your module parses files
+from a certain format and it receives one from a different format, you can
+safely leave all your variables undefined instead of assigning them bogus
+values that don't make sense. YARA will handle undefined values in rule
+conditions as described in :ref:`using-modules`.
In addition to ``set_integer`` and ``set_string`` functions you have their
``get_integer`` and ``get_string`` counterparts. As the names suggest they
@@ -817,11 +818,11 @@ implementation of your functions to retrieve values previously stored by
.. c:function:: char* get_string(YR_OBJECT* object, const char* field, ...)
-There's also a function to the get any ``YR_OBJECT`` in the objects tree:
+There's also a function to get any ``YR_OBJECT`` in the objects tree:
.. c:function:: YR_OBJECT* get_object(YR_OBJECT* object, const char* field, ...)
-Here goes a little exam...
+Here is a little exam...
Are the following two lines equivalent? Why?
@@ -837,13 +838,13 @@ Storing data for later use
Sometimes the information stored directly in your variables by means of
``set_integer`` and ``set_string`` is not enough. You may need to store more
-complex data structures or information that don't need to be exposed to YARA
+complex data structures or information that doesn't need to be exposed to YARA
rules.
Storing information is essential when your module exports functions
to be used in YARA rules. The implementation of these functions usually require
to access information generated by ``module_load`` which must kept somewhere.
-You may be tempted to define global variables where to put the required
+You may be tempted to define global variables to store the required
information, but this would make your code non-thread-safe. The correct
approach is using the ``data`` field of the ``YR_OBJECT`` structures.
@@ -921,7 +922,7 @@ Here you have some examples:
The C type for integer arguments is ``int64_t``, for float arguments is
``double``, for regular expressions is ``RE_CODE``, for NULL-terminated strings
-is ``char*`` and for string possibly containing NULL characters is
+is ``char*`` and for strings possibly containing NULL characters is
``SIZED_STRING*``. ``SIZED_STRING`` structures have the
following attributes:
@@ -960,7 +961,7 @@ Accessing objects
-----------------
While writing a function we sometimes need to access values previously assigned
-to module's variables, or additional data stored in the ``data`` field of
+to the module's variables, or additional data stored in the ``data`` field of
``YR_OBJECT`` structures as discussed earlier in
:ref:`storing-data-for-later-use`. But for that we need a way to get access to
the corresponding ``YR_OBJECT`` first. There are two functions to do that:
diff --git a/docs/writingrules.rst b/docs/writingrules.rst
index 2e7f7cd..1b2c8c8 100644
--- a/docs/writingrules.rst
+++ b/docs/writingrules.rst
@@ -85,7 +85,7 @@ in text or hexadecimal form, as shown in the following example::
$my_text_string or $my_hex_string
}
-Text strings are enclosed on double quotes just like in the C language. Hex
+Text strings are enclosed in double quotes just like in the C language. Hex
strings are enclosed by curly brackets, and they are composed by a sequence of
hexadecimal numbers that can appear contiguously or separated by spaces. Decimal
numbers are not allowed in hex strings.
@@ -110,7 +110,7 @@ single-line and multi-line C-style comments are supported. ::
rule CommentExample // ... and this is single-line comment
{
condition:
- false // just an dummy rule, don't do this
+ false // just a dummy rule, don't do this
}
Strings
@@ -167,9 +167,9 @@ following strings will match the pattern::
F4 23 00 00 00 00 00 62 B4
F4 23 15 82 A3 04 45 22 62 B4
-Any jump [X-Y] must met the condition 0 <= X <= Y. In previous versions of YARA
-both X and Y must be lower than 256, but starting with YARA 2.0 there is no
-limit for X and Y.
+Any jump [X-Y] must meet the condition 0 <= X <= Y. In previous versions of
+YARA both X and Y must be lower than 256, but starting with YARA 2.0 there is
+no limit for X and Y.
These are valid jumps::
@@ -320,7 +320,7 @@ with ``wide`` , no matter the order in which they appear. ::
$wide_and_ascii_string
}
-The ``ascii`` modifier can appear along, without an accompanying ``wide``
+The ``ascii`` modifier can appear alone, without an accompanying ``wide``
modifier, but it's not necessary to write it because in absence of ``wide`` the
string is assumed to be ASCII by default.
@@ -343,7 +343,7 @@ of double-quotes, like in the Perl programming language. ::
rule RegExpExample1
{
strings:
- $re1 = /md5: [0-9a-zA-Z]{32}/
+ $re1 = /md5: [0-9a-fA-F]{32}/
$re2 = /state: (on|off)/
condition:
@@ -430,8 +430,6 @@ The following escape sequences are recognised:
- New line (LF, NL)
* - ``\r``
- Return (CR)
- * - ``\n``
- - New line (LF, NL)
* - ``\f``
- Form feed (FF)
* - ``\a``
@@ -459,7 +457,7 @@ These are the recognised character classes:
- Match a non-digit character
-Starting with version 3.3.0 these zero-with assertions are also recognized:
+Starting with version 3.3.0 these zero-width assertions are also recognized:
.. list-table::
:widths: 3 10
@@ -516,7 +514,7 @@ For example::
}
-This rules matches any file or process containing the string $a exactly six times,
+This rule matches any file or process containing the string $a exactly six times,
and more than ten occurrences of string $b.
.. _string-offsets:
@@ -594,7 +592,7 @@ File size
String identifiers are not the only variables that can appear in a condition
(in fact, rules can be defined without any string definition as will be shown
below), there are other special variables that can be used as well. One of
-these especial variables is ``filesize``, which holds, as its name indicates,
+these special variables is ``filesize``, which holds, as its name indicates,
the size of the file being scanned. The size is expressed in bytes. ::
rule FileSizeExample
@@ -603,23 +601,23 @@ the size of the file being scanned. The size is expressed in bytes. ::
filesize > 200KB
}
-The previous example also demonstrate the use of the ``KB`` postfix. This
+The previous example also demonstrates the use of the ``KB`` postfix. This
postfix, when attached to a numerical constant, automatically multiplies the
value of the constant by 1024. The ``MB`` postfix can be used to multiply the
value by 2^20. Both postfixes can be used only with decimal constants.
The use of ``filesize`` only makes sense when the rule is applied to a file, if
-the rule is applied to a running process won’t never match because ``filesize``
+the rule is applied to a running process it won’t ever match because ``filesize``
doesn’t make sense in this context.
Executable entry point
----------------------
-Another special variable than can be used on a rule is ``entrypoint``. If file
-is a Portable Executable (PE) or Executable and Linkable Format (ELF), this
-variable holds the raw offset of the executable’s entry point in case we are
-scanning a file. If we are scanning a running process, the entrypoint will hold
-the virtual address of the main executable’s entry point. A typical use of
+Another special variable than can be used in a rule is ``entrypoint``. If the
+file is a Portable Executable (PE) or Executable and Linkable Format (ELF),
+this variable holds the raw offset of the executable’s entry point in case we
+are scanning a file. If we are scanning a running process, the entrypoint will
+hold the virtual address of the main executable’s entry point. A typical use of
this variable is to look for some pattern at the entry point to detect packers
or simple file infectors. ::
@@ -654,10 +652,10 @@ this variable evaluates to false.
Accessing data at a given position
----------------------------------
-There are many situations in which you may want to write conditions that
-depends on data stored at a certain file offset or memory virtual address,
-depending if we are scanning a file or a running process. In those situations
-you can use one of the following functions to read data from the file at the given offset::
+There are many situations in which you may want to write conditions that depend
+on data stored at a certain file offset or memory virtual address, depending if
+we are scanning a file or a running process. In those situations you can use
+one of the following functions to read data from the file at the given offset::
int8(<offset or virtual address>)
int16(<offset or virtual address>)
@@ -677,7 +675,7 @@ you can use one of the following functions to read data from the file at the giv
The ``intXX`` functions read 8, 16, and 32 bits signed integers from
<offset or virtual address>, while functions ``uintXX`` read unsigned integers.
-Both 16 and 32 bits integer are considered to be little-endian. If you
+Both 16 and 32 bit integers are considered to be little-endian. If you
want to read a big-endian integer use the corresponding function ending
in ``be``. The <offset or virtual address> parameter can be any expression returning
an unsigned integer, including the return value of one the ``uintXX`` functions
@@ -699,7 +697,7 @@ Sets of strings
There are circumstances in which it is necessary to express that the file should
contain a certain number strings from a given set. None of the strings in the
set are required to be present, but at least some of them should be. In these
-situations the operator of come into help. ::
+situations the operator ``of`` comes in to help. ::
rule OfExample1
{
@@ -713,7 +711,7 @@ situations the operator of come into help. ::
}
What this rule says is that at least two of the strings in the set ($a,$b,$c)
-must be present on the file, no matter which. Of course, when using this
+must be present in the file, no matter which. Of course, when using this
operator, the number before the ``of`` keyword must be equal to or less than
the number of strings in the set.
@@ -760,7 +758,7 @@ equivalent keyword ``them`` for more legibility. ::
In all the above examples the number of strings have been specified by a
numeric constant, but any expression returning a numeric value can be used.
-The keywords any and all can be used as well. ::
+The keywords any and all can be used as well. ::
all of them // all strings in the rule
any of them // any string in the rule
@@ -780,12 +778,13 @@ And its meaning is: from those strings in ``string_set`` at least ``expression``
of them must satisfy ``boolean_expression``.
In other words: ``boolean_expression`` is evaluated for every string in
-``string_set`` and must be at least ``expression`` of them returning True.
+``string_set`` and there must be at least ``expression`` of them returning
+True.
Of course, ``boolean_expression`` can be any boolean expression accepted in
the condition section of a rule, except for one important detail: here you
can (and should) use a dollar sign ($) as a place-holder for the string being
-evaluated. Take a look to the following expression::
+evaluated. Take a look at the following expression::
for any of ($a,$b,$c) : ( $ at entrypoint )
@@ -812,7 +811,7 @@ When using the ``of`` and ``for..of`` operators followed by ``them``, the
identifier assigned to each string of the rule is usually superfluous. As
we are not referencing any string individually we do not need to provide
a unique identifier for each of them. In those situations you can declare
-anonymous strings with identifiers consisting only in the $ character, as in
+anonymous strings with identifiers consisting only of the $ character, as in
the following example::
rule AnonymousStrings
@@ -861,7 +860,7 @@ boundaries, we can use expressions as well like in the following example::
for all i in (1..#a) : ( @a[i] < 100 )
In this case we’re iterating over every occurrence of $a (remember that #a
-represents the number of occurrences of $a). This rule is telling that every
+represents the number of occurrences of $a). This rule is specifying that every
occurrence of $a should be within the first 100 bytes of the file.
In case you want to express that only some occurrences of the string
@@ -871,7 +870,7 @@ applies here::
for any i in (1..#a) : ( @a[i] < 100 )
for 2 i in (1..#a) : ( @a[i] < 100 )
-In resume, the syntax of this operator is::
+In summary, the syntax of this operator is::
for expression identifier in indexes : ( boolean_expression )
@@ -883,7 +882,7 @@ Referencing other rules
When writing the condition for a rule you can also make reference to a
previously defined rule in a manner that resembles a function invocation of
traditional programming languages. In this way you can create rules that
-depends on others. Let's see an example::
+depend on others. Let's see an example::
rule Rule1
{
@@ -904,13 +903,13 @@ depends on others. Let's see an example::
}
As can be seen in the example, a file will satisfy Rule2 only if it contains
-the string "dummy2" and satisfy Rule1. Note that is strictly necessary to
+the string "dummy2" and satisfies Rule1. Note that it is strictly necessary to
define the rule being invoked before the one that will make the invocation.
More about rules
================
-There are some aspects of YARA rules that has not been covered yet, but still
+There are some aspects of YARA rules that have not been covered yet, but still
are very important. They are: global rules, private rules, tags and metadata.
Global rules
@@ -918,7 +917,7 @@ Global rules
Global rules give you the possibility of imposing restrictions in all your
rules at once. For example, suppose that you want all your rules ignoring
-those files that exceed certain size limit, you could go rule by rule doing
+those files that exceed a certain size limit, you could go rule by rule doing
the required modifications to their conditions, or just write a global rule
like this one::
@@ -929,7 +928,7 @@ like this one::
}
You can define as many global rules as you want, they will be evaluated
-before the rest of the rules, which in turn will be evaluated only of all
+before the rest of the rules, which in turn will be evaluated only if all
global rules are satisfied.
Private rules
@@ -949,15 +948,15 @@ just add the keyword ``private`` before the rule declaration. ::
...
}
-You can apply both ``private`` and ``global`` modifiers to a rule, resulting a
-global rule that does not get reported by YARA but must be satisfied.
+You can apply both ``private`` and ``global`` modifiers to a rule, resulting in
+a global rule that does not get reported by YARA but must be satisfied.
Rule tags
---------
Another useful feature of YARA is the possibility of adding tags to rules.
Those tags can be used later to filter YARA's output and show only the rules
-that you are interesting in. You can add as many tags as you want to a rule,
+that you are interested in. You can add as many tags as you want to a rule,
they are declared after the rule identifier as shown below::
rule TagsExample1 : Foo Bar Baz
@@ -1014,12 +1013,12 @@ about the rule.
Using modules
=============
-Modules are extensions to YARA's core functionality. Some modules like the
+Modules are extensions to YARA's core functionality. Some modules like
the :ref:`PE module <pe-module>` and the :ref:`Cuckoo module <cuckoo-module>`
are officially distributed with YARA and some of them can be created by
third-parties or even by yourself as described in :ref:`writing-modules`.
-The first step to use a module is importing it with the ``import`` statement.
+The first step to using a module is importing it with the ``import`` statement.
These statements must be placed outside any rule definition and followed by
the module name enclosed in double-quotes. Like this::
@@ -1034,10 +1033,10 @@ module. For example::
pe.entry_point == 0x1000
cuckoo.http_request(/someregexp/)
-Modules often leave variables in undefined state, for example when the variable
-doesn't make sense in the current context (think of ``pe.entry_point`` while
-scanning a non-PE file). YARA handles undefined values in way that allows the
-rule to keep its meaningfulness. Take a look at this rule::
+Modules often leave variables in an undefined state, for example when the
+variable doesn't make sense in the current context (think of ``pe.entry_point``
+while scanning a non-PE file). YARA handles undefined values in way that allows
+the rule to keep its meaningfulness. Take a look at this rule::
import "pe"
@@ -1090,8 +1089,8 @@ For example::
bool_ext_var or filesize < int_ext_var
}
-External variables of type string can be used with operators contains and
-matches. The ``contains`` operator returns true if the string contains the
+External variables of type string can be used with operators ``contains`` and
+``matches``. The ``contains`` operator returns true if the string contains the
specified substring. The operator ``matches`` returns true if the string
matches the given regular expression. ::
diff --git a/docs/yarapython.rst b/docs/yarapython.rst
index c59da42..81b57aa 100644
--- a/docs/yarapython.rst
+++ b/docs/yarapython.rst
@@ -41,7 +41,7 @@ Or you can compile them directly from a Python string:
rules = yara.compile(source='rule dummy { condition: true }')
If you want to compile a group of files or strings at the same time you can do
-it by using the filepaths or sources named arguments:
+it by using the ``filepaths`` or ``sources`` named arguments:
.. code-block:: python
@@ -62,7 +62,7 @@ of string type. The dictionary keys are used as a namespace identifier, allowing
to differentiate between rules with the same name in different sources, as
occurs in the second example with the *dummy* name.
-The ``compile`` method also have an optional boolean parameter named
+The ``compile`` method also has an optional boolean parameter named
``includes`` which allows you to control whether or not the include directive
should be accepted in the source files, for example:
@@ -75,10 +75,9 @@ If the source file contains include directives the previous line would raise
an exception.
If you are using external variables in your rules you must define those
-externals variables either while compiling the rules, or while applying
-the rules to some file. To define your variables at the moment of
-compilation you should pass the ``externals`` parameter to the ``compile``
-method. For example:
+external variables either while compiling the rules, or while applying the
+rules to some file. To define your variables at the moment of compilation you
+should pass the ``externals`` parameter to the ``compile`` method. For example:
.. code-block:: python
@@ -96,7 +95,7 @@ The default value for the ``error_on_warning`` argument is False.
In all cases ``compile`` returns an instance of the class :py:class:`yara.Rules`
-Rules. This class have a ``save`` method that can be used to save the compiled
+Rules. This class has a ``save`` method that can be used to save the compiled
rules to a file:
.. code-block:: python
@@ -128,8 +127,8 @@ The saved rules can be loaded from the memory buffer:
The result of ``load`` is also an instance of the class :py:class:`yara.Rules`.
-Instances of ``Rules`` also have a ``match`` method, which allows to apply the
-rules to a file:
+Instances of ``Rules`` also have a ``match`` method, which allows you to apply
+the rules to a file:
.. code-block:: python
@@ -149,14 +148,14 @@ Or to a running process:
matches = rules.match(pid=1234)
As in the case of ``compile``, the ``match`` method can receive definitions for
-externals variables in the ``externals`` argument.
+external variables in the ``externals`` argument.
.. code-block:: python
matches = rules.match('/foo/bar/my_file',
externals= {'var1': 'some other string', 'var2': 100})
-Externals variables defined during compile-time don’t need to be defined again
+External variables defined during compile-time don’t need to be defined again
in subsequent calls to the ``match`` method. However you can redefine
any variable as needed, or provide additional definitions that weren’t provided
during compilation.
@@ -172,7 +171,7 @@ find useful the ``timeout`` argument:
If the ``match`` function does not finish before the specified number of
seconds elapsed, a ``TimeoutError`` exception is raised.
-You can also specify a callback function when invoking ``match`` method. The
+You can also specify a callback function when invoking the ``match`` method. The
provided function will be called for every rule, no matter if matching or not.
Your callback function should expect a single parameter of dictionary type,
and should return ``CALLBACK_CONTINUE`` to proceed to the next rule or
@@ -203,7 +202,7 @@ The passed dictionary will be something like this:
'strings': [(81L, '$a', 'abc'), (141L, '$b', 'def')]
}
-The *matches* field indicates if the rules matches the data or not. The
+The *matches* field indicates if the rule matches the data or not. The
*strings* fields is a list of matching strings, with vectors of the form::
(<offset>, <string identifier>, <string data>)
@@ -213,11 +212,11 @@ Instances of this class have the same attributes as the dictionary passed to the
callback function.
-You can also specify a module callback function when invoking ``match`` method.
-The provided function will be called for every imported module that scanned a
-file. Your callback function should expect a single parameter of dictionary
-type, and should return ``CALLBACK_CONTINUE`` to proceed to the next rule or
-``CALLBACK_ABORT`` to stop applying rules to your data.
+You can also specify a module callback function when invoking the ``match``
+method. The provided function will be called for every imported module that
+scanned a file. Your callback function should expect a single parameter of
+dictionary type, and should return ``CALLBACK_CONTINUE`` to proceed to the next
+rule or ``CALLBACK_ABORT`` to stop applying rules to your data.
Here is an example:
--
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