## File: README.md

[](https://gitter.im/VirusTotal/yara?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://ci.appveyor.com/project/plusvic/yara)
[](https://scan.coverity.com/projects/plusvic-yara)

> [!IMPORTANT]
> This project is in maintenance mode. More info: https://virustotal.github.io/yara-x/blog/yara-x-is-stable/


## YARA in a nutshell

YARA is a tool aimed at (but not limited to) helping malware researchers to
identify and classify malware samples. With YARA you can create descriptions of
malware families (or whatever you want to describe) based on textual or binary
patterns. Each description, a.k.a. rule, consists of a set of strings and a
boolean expression which determine its logic. Let's see an example:

```yara
rule silent_banker : banker
{
    meta:
        description = "This is just an example"
        threat_level = 3
        in_the_wild = true

    strings:
        $a = {6A 40 68 00 30 00 00 6A 14 8D 91}
        $b = {8D 4D B0 2B C1 83 C0 27 99 6A 4E 59 F7 F9}
        $c = "UVODFRYSIHLNWPEJXQZAKCBGMT"

    condition:
        $a or $b or $c
}
```

The above rule is telling YARA that any file containing one of the three strings
must be reported as *silent_banker*. This is just a simple example, more
complex and powerful rules can be created by using wild-cards, case-insensitive
strings, regular expressions, special operators and many other features that
you'll find explained in [YARA's documentation](https://yara.readthedocs.org/).

YARA is multi-platform, running on Windows, Linux and Mac OS X, and can be used
through its command-line interface or from your own Python scripts with the
yara-python extension.

## Additional resources

Do you use GitHub for storing your YARA rules? [YARA-CI](https://yara-ci.cloud.virustotal.com)
may be a useful addition to your toolbelt. This is GitHub application that provides
continuous testing for your rules, helping you to identify common mistakes and
false positives.

If you plan to use YARA to scan compressed files (.zip, .tar, etc) you should
take a look at [yextend](https://github.com/BayshoreNetworks/yextend), a very
helpful extension to YARA developed and open-sourced by Bayshore Networks.

Additionally, the guys from [InQuest](https://inquest.net/) have curated an
awesome list of [YARA-related stuff](https://github.com/InQuest/awesome-yara).

## Who's using YARA

* [0x101 Cyber Security](https://0x101-cyber-security.de)
* [Adlice](https://www.adlice.com/)
* [AlienVault](https://otx.alienvault.com/)
* [Avast](https://www.avast.com/)
* [BAE Systems](https://www.baesystems.com/home?r=ai)
* [Bayshore Networks, Inc.](https://www.bayshorenetworks.com)
* [Binalyze](https://www.binalyze.com/)
* [BinaryAlert](https://github.com/airbnb/binaryalert)
* [Blueliv](https://www.blueliv.com)
* [Cado Security](https://docs.cadosecurity.com/cado-response/investigate/detections#setting-up-detections)
* [Cisco Talos Intelligence Group](https://talosintelligence.com/)
* [Cloudina Security](https://cloudina.co.uk)
* [Cofense](https://cofense.com)
* [Conix](https://www.conix.fr)
* [Corelight](https://corelight.com/products/yara)
* [CounterCraft](https://www.countercraft.eu)
* [Cuckoo Sandbox](https://github.com/cuckoosandbox/cuckoo)
* [Cyber Triage](https://www.cybertriage.com)
* [Cybereason](https://www.cybereason.com)
* [Digita Security](https://digitasecurity.com/product/uxprotect)
* [Dragos Platform](https://dragos.com/platform/)
* [Dtex Systems](https://dtexsystems.com)
* [ESET](https://www.eset.com)
* [ESTsecurity](https://www.estsecurity.com)
* [Elastic Security](https://github.com/elastic/protections-artifacts)
* [FactorX.ai](https://factorx.ai)
* [Fidelis XPS](https://www.fidelissecurity.com/network-security-appliance/Fidelis-XPS)
* [FireEye, Inc.](https://www.fireeye.com)
* [Forcepoint](https://www.forcepoint.com)
* [Fox-IT](https://www.fox-it.com)
* [FSF](https://github.com/EmersonElectricCo/fsf)
* [Guidance Software](https://www.guidancesoftware.com/endpointsecurity)
* [Heroku](https://heroku.com)
* [Hornetsecurity](https://www.hornetsecurity.com/en/)
* [ICS Defense](https://icsdefense.net/)
* [InQuest](https://www.inquest.net/)
* [IntelOwl](https://github.com/intelowlproject/IntelOwl)
* [Joe Security](https://www.joesecurity.org)
* [Kaspersky Lab](https://www.kaspersky.com)
* [KnowBe4](https://www.knowbe4.com)
* [Koodous](https://koodous.com/)
* [Laika BOSS](https://github.com/lmco/laikaboss)
* [Lastline, Inc.](https://www.lastline.com)
* [libguestfs](https://www.libguestfs.org/)
* [LimaCharlie](https://limacharlie.io/)
* [Malpedia](https://malpedia.caad.fkie.fraunhofer.de/)
* [Malwation](https://malwation.com/)
* [McAfee Advanced Threat Defense](https://mcafee.com/atd)
* [Metaflows](https://www.metaflows.com)
* [NBS System](https://www.nbs-system.com/)
* [ndaal](https://ndaal.eu)
* [NetLock](https://netlockendpoint.com)
* [Nextron Systems](https://www.nextron-systems.com)
* [Nozomi Networks](https://www.nozominetworks.com)
* [osquery](https://www.osquery.io)
* [Payload Security](https://www.payload-security.com)
* [PhishMe](https://phishme.com/)
* [Picus Security](https://www.picussecurity.com/)
* [Radare2](https://rada.re)
* [RedSocks Security](https://redsocks.eu/)
* [ReversingLabs](https://reversinglabs.com)
* [Scanii](https://scanii.com)
* [SecondWrite](https://www.secondwrite.com)
* [SonicWall](https://www.sonicwall.com/)
* [SpamStopsHere](https://www.spamstopshere.com)
* [Spyre](https://github.com/spyre-project/spyre)
* [stoQ](https://stoq.punchcyber.com)
* [Sublime Security](https://sublime.security)
* [SumoLogic](https://sumologic.com)
* [Tanium](https://www.tanium.com/)
* [Tenable Network Security](https://www.tenable.com/)
* [Tenzir](https://tenzir.com)
* [The DigiTrust Group](https://www.digitrustgroup.com/)
* [ThreatConnect](https://www.threatconnect.com/)
* [ThreatStream, Inc.](https://www.threatstream.com)
* [Thug](https://github.com/buffer/thug)
* [Threat.Zone](https://threat.zone)
* [TouchWeb](https://www.touchweb.fr)
* [Trend Micro](https://www.trendmicro.com)
* [UnpacMe](https://www.unpac.me)
* [UpSight Security Inc.](https://upsight.ai/)
* [Uptycs Inc](https://www.uptycs.com/)
* [Veeam](https://www.veeam.com/)
* [Verisys Antivirus API](https://www.ionxsolutions.com/products/verisys-virus-api)
* [VirusTotal Intelligence](https://www.virustotal.com/intelligence/)
* [VMRay](https://www.vmray.com/)
* [Volexity](https://www.volexity.com/products-overview/volcano/)
* [We Watch Your Website](https://www.wewatchyourwebsite.com/)
* [x64dbg](https://x64dbg.com)
* [YALIH](https://github.com/Masood-M/YALIH)

Are you using it? Want to see your site listed here?

---

## File: docs/modules/console.rst

.. _console-module:

##############
Console module
##############

.. versionadded:: 4.2.0

The Console module allows you to log information during condition execution. By
default, the log messages are sent to stdout but can be handled differently by
using the C api (:ref:`scanning-data`).

Every function in the console module returns true for the purposes of condition
evaluation. This means you must logically and your statements together to get
the proper output. For example:

.. code-block:: yara

    import "console"

    rule example
    {
        condition:
            console.log("Hello") and console.log("World!")
    }

.. c:function:: log(string)

    Function which sends the string to the main callback.

    *Example: console.log(pe.imphash())*

.. c:function:: log(message, string)

    Function which sends the message and string to the main callback.

    *Example: console.log("The imphash is: ", pe.imphash())*

.. c:function:: log(integer)

    Function which sends the integer to the main callback.

    *Example: console.log(uint32(0))*

.. c:function:: log(message, integer)

    Function which sends the message and integer to the main callback.

    *Example: console.log("32bits at 0: ", uint32(0))*

.. c:function:: log(float)

    Function which sends the floating point value to the main callback.

    *Example: console.log(math.entropy(0, filesize))*

.. c:function:: log(message, float)

    Function which sends the message and the floating point value to the main
    callback.

    *Example: console.log("Entropy: ", math.entropy(0, filesize))*

.. c:function:: hex(integer)

    Function which sends the integer to the main callback, formatted as a hex
    string.

    *Example: console.hex(uint32(0))*

.. c:function:: hex(message, integer)

    Function which sends the integer to the main callback, formatted as a hex
    string.

    *Example: console.hex("Hex at 0: ", uint32(0))*

---

## File: docs/modules/cuckoo.rst

.. _cuckoo-module:

#############
Cuckoo module
#############

The Cuckoo module enables you to create YARA rules based on behavioral
information generated by `Cuckoo sandbox <https://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 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
    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:

.. code-block:: yara

    rule evil_doer
    {
        strings:
            $evil_domain = "http://someone.doingevil.com"

        condition:
            $evil_domain
    }


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 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 YARA, and write a rule like this:

.. code-block:: yara

    import "cuckoo"

    rule evil_doer
    {
        condition:
            cuckoo.network.http_request(/http:\/\/someone\.doingevil\.com/)
    }

Of course you can mix your behavior-related conditions with good old
string-based conditions:

.. code-block:: yara

    import "cuckoo"

    rule evil_doer
    {
        strings:
            $some_string = { 01 02 03 04 05 06 }

        condition:
            $some_string and
            cuckoo.network.http_request(/http:\/\/someone\.doingevil\.com/)
    }


But how do we pass the behavior information to the ``cuckoo`` module? Well, in
the case of the command-line tool you must use the ``-x`` option in this way::

    $yara -x cuckoo=behavior_report_file rules_file pe_file


``behavior_report_file`` is the path to a file containing the behavior file
generated by the Cuckoo sandbox in JSON format.

If you are using ``yara-python`` then you must pass the behavior report in the
``modules_data`` argument for the ``match`` method:

.. code-block:: python

    import yara
    rules = yara.compile('./rules_file')
    report_file = open('./behavior_report_file')
    report_data = report_file.read()
    rules.match(pe_file, modules_data={'cuckoo': bytes(report_data)})


Reference
---------

.. default-domain:: c

.. type:: network

    .. function:: http_request(regexp)

        Function returning true if the program sent a HTTP request to a URL
        matching the provided regular expression.

        *Example: cuckoo.network.http_request(/evil\\.com/)*

    .. function:: http_get(regexp)

        Similar to :func:`http_request`, but only takes into account GET
        requests.

    .. function:: http_post(regexp)

        Similar to :func:`http_request`, but only takes into account POST
        requests.
       
    .. function:: http_user_agent(regexp)

        Function returning true if the program sent a HTTP request with a
        user agent matching the provided regular expression.

        *Example: cuckoo.network.http_user_agent(/MSIE 6\\.0/)*   

    .. function:: dns_lookup(regexp)

        Function returning true if the program sent a domain name resolution
        request for a domain matching the provided regular expression.

        *Example: cuckoo.network.dns_lookup(/evil\\.com/)*
        
    .. function:: host(regexp)

        Function returning true if the program contacted an IP address
        matching the provided regular expression.

        *Example: cuckoo.network.host(/192\\.168\\.1\\.1/)*  

      .. function:: tcp(regexp, port)

        Function returning true if the program contacted an IP address
        matching the provided regular expression, over TCP on the provided
        port number.

        *Example: cuckoo.network.tcp(/192\\.168\\.1\\.1/, 443)*  

      .. function:: udp(regexp, port)

        Function returning true if the program contacted an IP address
        matching the provided regular expression, over UDP on the provided
        port number.

        *Example: cuckoo.network.udp(/192\\.168\\.1\\.1/, 53)*  

.. type:: registry

    .. function:: key_access(regexp)

        Function returning true if the program accessed a registry entry
        matching the provided regular expression.

        *Example: cuckoo.registry.key_access(/\\\\Software\\\\Microsoft\\\\Windows\\\\CurrentVersion\\\\Run/)*

.. type:: filesystem

    .. function:: file_access(regexp)

        Function returning true if the program accessed a file matching the
        provided regular expression.

        *Example: cuckoo.filesystem.file_access(/autoexec\\.bat/)*

.. type:: sync

    .. function:: mutex(regexp)

        Function returning true if the program opens or creates a mutex matching
        the provided regular expression.

        *Example: cuckoo.sync.mutex(/EvilMutexName/)*

---

## File: docs/modules/dotnet.rst

.. _dotnet-module:

#############
dotnet module
#############

.. versionadded:: 3.6.0

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:

.. code-block:: yara

    import "dotnet"

    rule not_exactly_five_streams
    {
        condition:
            dotnet.number_of_streams != 5
    }

    rule blop_stream
    {
        condition:
            for any i in (0..dotnet.number_of_streams - 1):
                (dotnet.streams[i].name == "#Blop")
    }

Reference
---------

.. c:type:: version

    The version string contained in the metadata root.

    *Example: dotnet.version == "v2.0.50727"*

.. c:type:: module_name

    The name of the module.

    *Example: dotnet.module_name == "axs"*

.. c:type:: number_of_streams

    The number of streams in the file.

.. c:type:: streams

    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:

    .. c:member:: name

        Stream name.

    .. c:member:: offset

        Stream offset.

    .. c:member:: size

        Stream size.

    *Example: dotnet.streams[0].name == "#~"*

.. c:type:: number_of_guids

    The number of GUIDs in the guids array.

.. c:type:: guids

    A zero-based array of strings, one for each GUID. Individual guids can be
    accessed by using the [] operator.

    *Example: dotnet.guids[0] == "99c08ffd-f378-a891-10ab-c02fe11be6ef"*

.. c:type:: number_of_classes
    The number of classes in the file.

.. c:type:: classes
    An array of .NET classes stored in the metadata. Individual classes can be accessed
    using the [] operator. Each class object contains the following attributes:

    .. c:member:: fullname
        Class full name.

    .. c:member:: name
        Class name.

    .. c:member:: namespace
        Class namespace.

    .. c:member:: visibility
        Class visibility specifier, options are:

        ``private``
        ``public``
        ``protected``
        ``internal``
        ``private protected``
        ``protected internal``

    .. c:member:: type
        Type of the object, options are:

        ``class``
        ``interface``

    .. c:member:: abstract
        Boolean representing if class is abstract.

    .. c:member:: sealed
        Boolean representing if class is sealed.

    .. c:member:: number_of_generic_parameters
        Number of generic parameters.

    .. c:member:: generic_parameters
        A zero-based array of generic parameters name. Individual parameters can be accessed using the [] operator.

    .. c:member:: number_of_base_types
        Number of the base types.

    .. c:member:: base_types
        A zero-based array of base types name. Individual base types can be accessed using the [] operator.

    .. c:member:: number_of_methods
        Number of the methods.

    .. c:member:: methods
        A zero-based array of method objects. Individual methods can be accessed by
        using the [] operator. Each object contains following attributes:

        .. c:member:: name
            Method name.

        .. c:member:: visibility
            Method visibility specifier, options are:

            ``private``
            ``public``
            ``protected``
            ``internal``
            ``private protected``
            ``protected internal``

        .. c:member:: static
            Boolean representing if method is static.

        .. c:member:: virtual
            Boolean representing if method is virtual. 

        .. c:member:: final
            Boolean representing if method is final. 

        .. c:member:: abstract
            Boolean representing if method is abstract. 

        .. c:member:: return_type
            Method return type name.

        .. c:member:: number_of_parameters
            Number of the method parameters.

        .. c:member:: parameters
            A zero-based array of method parameters. Individual parameters can be accessed by using the [] operator.

            .. c:member:: name
                Parameter name.

            .. c:member:: type
                Parameter type.

        .. c:member:: number_of_generic_parameters
            Number of the method generic parameters.

        .. c:member:: generic_parameters
            A zero-based array of method generic parameters. Individual parameters can be accessed by using the [] operator.

    *Example: dotnet.classes[0].fullname == "Launcher.Program"*

.. c:type:: number_of_resources

    The number of resources in the .NET file. These are different from normal PE
    resources.

.. c:type:: resources

    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

        Offset for the resource data.

    .. c:member:: length

        Length of the resource data.

    .. c:member:: name

        Name of the resource (string).

    *Example: uint16be(dotnet.resources[0].offset) == 0x4d5a*

.. c:type:: assembly

    Object for .NET assembly information.

    .. c:member:: version

        An object with integer values representing version information for this
        assembly. Attributes are:

        ``major``
        ``minor``
        ``build_number``
        ``revision_number``

    .. c:member:: name

        String containing the assembly name.

    .. c:member:: culture

        String containing the culture (language/country/region) for this
        assembly.

    *Example: dotnet.assembly.name == "Keylogger"*

    *Example: dotnet.assembly.version.major == 7 and dotnet.assembly.version.minor == 0*

.. c:type:: number_of_modulerefs

    The number of module references in the .NET file.

.. c:type:: modulerefs

    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"*

.. c:type:: typelib

    The typelib of the file.

.. c:type:: number_of_constants

    The number of constants in the .NET file.

.. c:type:: constants

    A zero-based array of strings, one for each constant the .NET file has. 
    Individual constants can be accessed by using the [] operator.

.. c:type:: number_of_assembly_refs

    The number of objects for .NET assembly reference information.

.. c:type:: assembly_refs

    Object for .NET assembly reference information.

    .. c:member:: version

        An object with integer values representing version information for this
        assembly. Attributes are:

        ``major``
        ``minor``
        ``build_number``
        ``revision_number``

    .. c:member:: name

        String containing the assembly name.

    .. c:member:: public_key_or_token

        String containing the public key or token which identifies the author of
        this assembly.

.. c:type:: number_of_user_strings

    The number of user strings in the file.

.. c:type:: user_strings

    An zero-based array of user strings, one for each stream contained in the
    file. Individual strings can be accessed by using the [] operator.

.. c:type:: number_of_field_offsets

    The number of fields in the field_offsets array.

.. c:type:: field_offsets

    A zero-based array of integers, one for each field. Individual field offsets
    can be accessed by using the [] operator.

    *Example: dotnet.field_offsets[0] == 8675309*

.. c:type:: is_dotnet

    .. versionadded:: 4.2.0

    Function returning true if the PE is indeed .NET.

    *Example: dotnet.is_dotnet*

---

## File: docs/modules/elf.rst

.. _elf-module:

##########
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 an ELF header. Let's see some
examples:

.. code-block:: yara

    import "elf"

    rule single_section
    {
        condition:
            elf.number_of_sections == 1
    }

    rule elf_64
    {
        condition:
            elf.machine == elf.EM_X86_64
    }

Reference
---------

.. c:type:: type

    Integer with one of the following values:

    .. c:type:: ET_NONE

        No file type.

    .. c:type:: ET_REL

        Relocatable file.

    .. c:type:: ET_EXEC

        Executable file.

    .. c:type:: ET_DYN

        Shared object file.

    .. c:type:: ET_CORE

        Core file.

    *Example: elf.type == elf.ET_EXEC*

.. c:type:: machine

    Integer with one of the following values:

    .. c:type:: EM_NONE
    .. c:type:: EM_M32
    .. c:type:: EM_SPARC
    .. c:type:: EM_386
    .. c:type:: EM_68K
    .. c:type:: EM_88K
    .. c:type:: EM_860
    .. c:type:: EM_MIPS
    .. c:type:: EM_MIPS_RS3_LE
    .. c:type:: EM_PPC
    .. c:type:: EM_PPC64
    .. c:type:: EM_ARM
    .. c:type:: EM_X86_64
    .. c:type:: EM_AARCH64

    *Example: elf.machine == elf.EM_X86_64*

.. c:type:: entry_point

    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

    Number of sections in the ELF file.

.. c:type:: sections

    A zero-based array of section objects, one for each section the ELF has.
    Individual sections can be accessed by using the [] operator. Each section
    object has the following attributes:

    .. c:member:: name

        Section's name.

        *Example: elf.sections[3].name == ".bss"*

    .. c:member:: size

        Section's size in bytes. Unless the section type is SHT_NOBITS, the
        section occupies sh_size bytes in the file. A section of
        :c:type:`SHT_NOBITS` may have a non-zero size, but it occupies no space
        in the file.

    .. c:member:: offset

        Offset from the beginning of the file to the first byte in the section.
        One section type, :c:type:`SHT_NOBITS` described below, occupies no
        space in the file, and its :c:member:`offset` member locates the
        conceptual placement in the file.

    .. c:member:: type

        Integer with one of the following values:

        .. c:type:: SHT_NULL

            This value marks the section as inactive; it does not have
            an associated section. Other members of the section header have
            undefined values.

        .. c:type:: SHT_PROGBITS

            The section holds information defined by the program, whose format
            and meaning are determined solely by the program.

        .. c:type:: SHT_SYMTAB

            The section holds a symbol table.

        .. c:type:: SHT_STRTAB

            The section holds a string table. An object file may have multiple
            string table sections.

        .. c:type:: SHT_RELA

            The section holds relocation entries.

        .. c:type:: SHT_HASH

            The section holds a symbol hash table.

        .. c:type:: SHT_DYNAMIC

            The section holds information for dynamic linking.

        .. c:type:: SHT_NOTE

            The section holds information that marks the file in some way.

        .. c:type:: SHT_NOBITS

            A section of this type occupies no space in the file but otherwise resembles :c:type:`SHT_PROGBITS`.

        .. c:type:: SHT_REL

            The section holds relocation entries.

        .. c:type:: SHT_SHLIB

            This section type is reserved but has unspecified semantics.

        .. c:type:: SHT_DYNSYM

            This section holds dynamic linking symbols.

    .. c:member:: flags

        Integer with section's flags as defined below:

        .. c:type:: SHF_WRITE

            The section contains data that should be writable during process
            execution.

        .. c:type:: SHF_ALLOC

            The section occupies memory during process execution. Some control sections do not reside in the memory image of an object file; this attribute is off for those sections.

        .. c:type:: SHF_EXECINSTR

            The section contains executable machine instructions.

        *Example: elf.sections[2].flags & elf.SHF_WRITE*

    .. c:member:: address

        .. versionadded:: 3.6.0

        The virtual address the section starts at.


.. c:type:: number_of_segments

    .. versionadded:: 3.4.0

    Number of segments in the ELF file.

.. c:type:: segments

    .. versionadded:: 3.4.0

    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:

    .. c:member:: alignment

        Value to which the segments are aligned in memory and in the file.

    .. c:member:: file_size

        Number of bytes in the file image of the segment.  It may be zero.

    .. c:member:: flags

        A combination of the following segment flags:

        .. c:type:: PF_R

            The segment is readable.

        .. c:type:: PF_W

            The segment is writable.

        .. c:type:: PF_X

            The segment is executable.

    .. c:member:: memory_size

        In-memory segment size.

    .. c:member:: offset

        Offset from the beginning of the file where the segment resides.

    .. c:member:: physical_address

        On systems for which physical addressing is relevant, contains the
        segment's physical address.

    .. c:member:: type

        Type of segment indicated by one of the following values:

        .. c:type:: PT_NULL
        .. c:type:: PT_LOAD
        .. c:type:: PT_DYNAMIC
        .. c:type:: PT_INTERP
        .. c:type:: PT_NOTE
        .. c:type:: PT_SHLIB
        .. c:type:: PT_PHDR
        .. c:type:: PT_LOPROC
        .. c:type:: PT_HIPROC
        .. c:type:: PT_GNU_STACK

    .. c:member:: virtual_address

        Virtual address at which the segment resides in memory.

.. c:type:: dynamic_section_entries

    .. versionadded:: 3.6.0

    Number of entries in the dynamic section in the ELF file.

.. c:type:: dynamic

    .. versionadded:: 3.6.0

    A zero-based array of dynamic objects, one for each entry in found in the
    ELF's dynamic section. Individual dynamic objects can be accessed by using
    the [] operator. Each dynamic object has the following attributes:

    .. c:member:: type

        Value that describes the type of dynamic section. Builtin values are:

        .. c:type:: DT_NULL
        .. c:type:: DT_NEEDED
        .. c:type:: DT_PLTRELSZ
        .. c:type:: DT_PLTGOT
        .. c:type:: DT_HASH
        .. c:type:: DT_STRTAB
        .. c:type:: DT_SYMTAB
        .. c:type:: DT_RELA
        .. c:type:: DT_RELASZ
        .. c:type:: DT_RELAENT
        .. c:type:: DT_STRSZ
        .. c:type:: DT_SYMENT
        .. c:type:: DT_INIT
        .. c:type:: DT_FINI
        .. c:type:: DT_SONAME
        .. c:type:: DT_RPATH
        .. c:type:: DT_SYMBOLIC
        .. c:type:: DT_REL
        .. c:type:: DT_RELSZ
        .. c:type:: DT_RELENT
        .. c:type:: DT_PLTREL
        .. c:type:: DT_DEBUG
        .. c:type:: DT_TEXTREL
        .. c:type:: DT_JMPREL
        .. c:type:: DT_BIND_NOW
        .. c:type:: DT_INIT_ARRAY
        .. c:type:: DT_FINI_ARRAY
        .. c:type:: DT_INIT_ARRAYSZ
        .. c:type:: DT_FINI_ARRAYSZ
        .. c:type:: DT_RUNPATH
        .. c:type:: DT_FLAGS
        .. c:type:: DT_ENCODING

    .. c:member:: value

        A value associated with the given type. The type of value (address,
        size, etc.) is dependant on the type of dynamic entry.

.. c:type:: symtab_entries

    .. versionadded:: 3.6.0

    Number of entries in the symbol table found in the ELF file.

.. c:type:: symtab

    .. versionadded:: 3.6.0

    A zero-based array of symbol objects, one for each entry in found in the
    ELF's SYMBTAB. Individual symbol objects can be accessed by using the []
    operator. Each symbol object has the following attributes:

    .. c:member:: name

        The symbol's name.

    .. c:member:: value

        A value associated with the symbol. Generally a virtual address.

    .. c:member:: size

        The symbol's size.

    .. c:member:: type

        The type of symbol. Built values are:

        .. c:type:: STT_NOTYPE
        .. c:type:: STT_OBJECT
        .. c:type:: STT_FUNC
        .. c:type:: STT_SECTION
        .. c:type:: STT_FILE
        .. c:type:: STT_COMMON
        .. c:type:: STT_TLS

    .. c:member:: bind

        The binding of the symbol. Builtin values are:

        .. c:type:: STB_LOCAL
        .. c:type:: STB_GLOBAL
        .. c:type:: STB_WEAK

    .. c:member:: shndx

        The section index which the symbol is associated with.

.. c:function:: telfhash()

    Function returning Telfhash - TLSH hash of the ELF export and import symbols.

     *Example: elf.telfhash() == "t166a00284751084526486df8b5df5b2fccb3f511dbc188c37156f5e714a11bc5d71014d"*

.. c:function:: import_md5()

    Function returning Import Hash - MD5 hash of the ELF imported symbols.

     *Example: elf.import_md5() == "c3eca50cbb03400a6e91b9fe48da0c0c"*

---

## File: docs/modules/hash.rst

.. _hash-module:

###########
Hash module
###########

.. versionadded:: 3.2.0

The Hash module allows you to calculate hashes (MD5, SHA1, SHA256) from portions
of your file and create signatures based on those hashes.

.. important::
    This module depends on the OpenSSL library. Please refer to
    :ref:`compiling-yara` for information about how to build OpenSSL-dependant
    features into YARA.

    Good news for Windows users: this module is already included in the official
    Windows binaries.

.. warning::
    The returned hash string is always in lowercase. This means that rule condition matching on hashes 
    ``hash.md5(0, filesize) == "feba6c919e3797e7778e8f2e85fa033d"`` 
    requires the hash string to be given in lowercase, otherwise the match condition 
    will not work. (see https://github.com/VirusTotal/yara/issues/1004)

.. c:function:: md5(offset, size)

    Returns the MD5 hash 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 string is always in lowercase.

    *Example: hash.md5(0, filesize) == "feba6c919e3797e7778e8f2e85fa033d"*

.. c:function:: md5(string)

    Returns the MD5 hash for the given string.

    *Example: hash.md5("dummy") == "275876e34cf609db118f3d84b799a790"*

.. c:function:: sha1(offset, size)

    Returns the SHA1 hash 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 string is always in
    lowercase.

.. c:function:: sha1(string)

    Returns the SHA1 hash for the given string.

.. c:function:: sha256(offset, size)

    Returns the SHA256 hash 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 string is always in
    lowercase.

.. c:function:: sha256(string)

    Returns the SHA256 hash for the given string.

.. c:function:: checksum32(offset, size)

    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-bit checksum for the given string. The checksum is just the
    sum of all the bytes in the string (unsigned).

.. c:function:: crc32(offset, size)

    Returns a crc32 checksum for the *size* bytes starting at *offset*.

.. c:function:: crc32(string)

    Returns a crc32 checksum for the given string.

---

## File: docs/modules/magic.rst

.. _magic-module:

############
Magic module
############

.. versionadded:: 3.1.0

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

libmagic will try and read its compiled file type database from /etc/magic.mgc
by default. If this file doesn't exist, you can set the environment variable
MAGIC to point to a magic.mgc file and libmagic will attempt to load from there
as an alternative.

.. 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"*

---

## File: docs/modules/math.rst

.. _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 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)*

.. c:function:: max(int, int)

    .. versionadded:: 3.8.0

    Returns the maximum of two unsigned integer values.

.. c:function:: min(int, int)

    .. versionadded:: 3.8.0

    Returns the minimum of two unsigned integer values.

.. c:function:: to_number(bool)

    .. versionadded:: 4.1.0

    Returns 0 or 1, it's useful when writing a score based rule.

    *Example: math.to_number(SubRule1) \* 60 + math.to_number(SubRule2) \* 20 + math.to_number(SubRule3) \* 70 > 80*

.. c:function:: abs(int)

    .. versionadded:: 4.2.0

    Returns the absolute value of the signed integer.

    *Example: math.abs(@a - @b) == 1*

.. c:function:: count(byte, offset, size)

    .. versionadded:: 4.2.0

    Returns how often a specific byte occurs, starting at *offset*
    and looking at the next *size* bytes. When scanning a
    running process the *offset* argument should be a virtual address within
    the process address space.
    *offset* and *size* are optional; if left empty, the complete file is searched.

    *Example: math.count(0x4A) >= 10*

    *Example: math.count(0x00, 0, 4) < 2*

.. c:function:: percentage(byte, offset, size)

    .. versionadded:: 4.2.0

    Returns the occurrence rate of a specific byte, starting at *offset*
    and looking at the next *size* bytes. 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 and 1.
    *offset* and *size* are optional; if left empty, the complete file is searched.


    *Example: math.percentage(0xFF, filesize-1024, filesize) >= 0.9*

    *Example: math.percentage(0x4A) >= 0.4*

.. c:function:: mode(offset, size)

    .. versionadded:: 4.2.0

    Returns the most common byte, starting at *offset* and looking at the next
    *size* bytes. When scanning a
    running process the *offset* argument should be a virtual address within
    the process address space. The returned value is a float.
    *offset* and *size* are optional; if left empty, the complete file is searched.

    *Example: math.mode(0, filesize) == 0xFF*

    *Example: math.mode() == 0x00*

.. c:function:: to_string(int)

    .. versionadded:: 4.3.0

    Convert the given integer to a string. Note: integers in YARA are signed.

    *Example: math.to_string(10) == "10"*
    *Example: math.to_string(-1) == "-1"*

.. c:function:: to_string(int, base)

    .. versionadded:: 4.3.0

    Convert the given integer to a string in the given base. Supported bases are
    10, 8 and 16. Note: integers in YARA are signed.

    *Example: math.to_string(32, 16) == "20"*
    *Example: math.to_string(-1, 16) == "ffffffffffffffff"*

---

## File: docs/modules/pe.rst

.. _pe-module:

#########
PE module
#########

The PE module allows you to create more fine-grained rules for PE files by
using attributes and features of the PE file format. This module exposes most of
the fields present in a PE header and provides functions which can be used to
write more expressive and targeted rules. Let's see some examples:

.. code-block:: yara

    import "pe"

    rule single_section
    {
        condition:
            pe.number_of_sections == 1
    }

    rule control_panel_applet
    {
        condition:
            pe.exports("CPlApplet")
    }

    rule is_dll
    {
        condition:
            pe.characteristics & pe.DLL
    }

    rule is_pe
    {
        condition:
            pe.is_pe
    }

Reference
---------

.. c:type:: machine

    .. versionchanged:: 3.3.0

    Integer with one of the following values:

    .. 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
    .. c:type:: MACHINE_TARGET_HOST
    .. c:type:: MACHINE_R3000
    .. c:type:: MACHINE_R10000
    .. c:type:: MACHINE_ALPHA
    .. c:type:: MACHINE_SH3E
    .. c:type:: MACHINE_ALPHA64
    .. c:type:: MACHINE_AXP64
    .. c:type:: MACHINE_TRICORE
    .. c:type:: MACHINE_CEF
    .. c:type:: MACHINE_CEE

    *Example: pe.machine == pe.MACHINE_AMD64*

.. c:type:: checksum

    .. versionadded:: 3.6.0

    Integer with the "PE checksum" as stored in the OptionalHeader

.. c:type:: calculate_checksum

    .. versionadded:: 3.6.0

    Function that calculates the "PE checksum"

    *Example: pe.checksum == pe.calculate_checksum()*

.. c:type:: subsystem

    Integer with one of the following values:

    .. c:type:: SUBSYSTEM_UNKNOWN
    .. c:type:: SUBSYSTEM_NATIVE
    .. c:type:: SUBSYSTEM_WINDOWS_GUI
    .. c:type:: SUBSYSTEM_WINDOWS_CUI
    .. c:type:: SUBSYSTEM_OS2_CUI
    .. c:type:: SUBSYSTEM_POSIX_CUI
    .. c:type:: SUBSYSTEM_NATIVE_WINDOWS
    .. c:type:: SUBSYSTEM_WINDOWS_CE_GUI
    .. c:type:: SUBSYSTEM_EFI_APPLICATION
    .. c:type:: SUBSYSTEM_EFI_BOOT_SERVICE_DRIVER
    .. c:type:: SUBSYSTEM_EFI_RUNTIME_DRIVER
    .. c:type:: SUBSYSTEM_EFI_ROM_IMAGE
    .. c:type:: SUBSYSTEM_XBOX
    .. c:type:: SUBSYSTEM_WINDOWS_BOOT_APPLICATION

    *Example: pe.subsystem == pe.SUBSYSTEM_NATIVE*

.. c:type:: timestamp

    PE timestamp, as an epoch integer.

    *Example: pe.timestamp >= 1424563200*

.. c:type:: pointer_to_symbol_table

    .. versionadded:: 3.8.0

    Value of IMAGE_FILE_HEADER::PointerToSymbolTable. Used when the PE image has
    COFF debug info.

.. c:type:: number_of_symbols

    .. versionadded:: 3.8.0

    Value of IMAGE_FILE_HEADER::NumberOfSymbols. Used when the PE image has COFF
    debug info.

.. c:type:: size_of_optional_header

    .. versionadded:: 3.8.0

    Value of IMAGE_FILE_HEADER::SizeOfOptionalHeader. This is real size of the
    optional header and reflects differences between 32-bit and 64-bit optional
    header and number of data directories.

.. c:type:: opthdr_magic

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::Magic.

    Integer with one of the following values:

        .. c:type:: IMAGE_NT_OPTIONAL_HDR32_MAGIC
        .. c:type:: IMAGE_NT_OPTIONAL_HDR64_MAGIC
        .. c:type:: IMAGE_ROM_OPTIONAL_HDR_MAGIC


.. c:type:: size_of_code

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::SizeOfCode. This is the sum of raw data
    sizes in code sections.

.. c:type:: size_of_initialized_data

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::SizeOfInitializedData.

.. c:type:: size_of_uninitialized_data

    Value of IMAGE_OPTIONAL_HEADER::SizeOfUninitializedData.

.. c:type:: entry_point

    Entry point file 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:: entry_point_raw

    Entry point raw value from the optional header of the PE. This value is not
    converted to a file offset or an RVA.

    .. versionadded:: 4.1.0

.. c:type:: base_of_code

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::BaseOfCode.

.. c:type:: base_of_data

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::BaseOfData. This field only exists in 32-bit
    PE files.

.. c:type:: image_base

    Image base relative virtual address.

.. c:type:: section_alignment

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::SectionAlignment. When Windows maps a PE
    image to memory, all raw sizes (including size of header) are aligned up to
    this value.

.. c:type:: file_alignment

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::FileAlignment. All raw data sizes of sections
    in the PE image are aligned to this value.

.. c:type:: win32_version_value

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::Win32VersionValue.

.. c:type:: size_of_image

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::SizeOfImage. This is the total virtual size
    of header and all sections.

.. c:type:: size_of_headers

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::SizeOfHeaders. This is the raw data size of
    the PE headers including DOS header, file header, optional header and all
    section headers. When PE is mapped to memory, this value is subject to
    aligning up to SectionAlignment.

.. c:type:: characteristics

    Bitmap with PE FileHeader characteristics. Individual characteristics
    can be inspected by performing a bitwise AND operation with the
    following constants:

    .. c:type:: RELOCS_STRIPPED

        Relocation info stripped from file.

    .. c:type:: EXECUTABLE_IMAGE

        File is executable  (i.e. no unresolved external references).

    .. c:type:: LINE_NUMS_STRIPPED

        Line numbers stripped from file.

    .. c:type:: LOCAL_SYMS_STRIPPED

        Local symbols stripped from file.

    .. c:type:: AGGRESIVE_WS_TRIM

        Aggressively trim working set

    .. c:type:: LARGE_ADDRESS_AWARE

        App can handle >2gb addresses

    .. c:type:: BYTES_REVERSED_LO

        Bytes of machine word are reversed.

    .. c:type:: MACHINE_32BIT

        32 bit word machine.

    .. c:type:: DEBUG_STRIPPED

        Debugging info stripped from file in .DBG file

    .. c:type:: REMOVABLE_RUN_FROM_SWAP

        If Image is on removable media, copy and run from the swap file.

    .. c:type:: NET_RUN_FROM_SWAP

        If Image is on Net, copy and run from the swap file.

    .. c:type:: SYSTEM

        System File.

    .. c:type:: DLL

        File is a DLL.

    .. c:type:: UP_SYSTEM_ONLY

        File should only be run on a UP machine

    .. c:type:: BYTES_REVERSED_HI

        Bytes of machine word are reversed.

    *Example:  pe.characteristics & pe.DLL*

.. c:type:: linker_version

    An object with two integer attributes, one for each major and minor linker
    version.

    .. c:member:: major

        Major linker version.

    .. c:member:: minor

        Minor linker version.

.. c:type:: os_version

    An object with two integer attributes, one for each major and minor OS
    version.

    .. c:member:: major

        Major OS version.

    .. c:member:: minor

        Minor OS version.

.. c:type:: image_version

    An object with two integer attributes, one for each major and minor image
    version.

    .. c:member:: major

        Major image version.

    .. c:member:: minor

        Minor image version.

.. c:type:: subsystem_version

    An object with two integer attributes, one for each major and minor subsystem
    version.

    .. c:member:: major

        Major subsystem version.

    .. c:member:: minor

        Minor subsystem version.

.. c:type:: dll_characteristics

    Bitmap with PE OptionalHeader DllCharacteristics.  Do not confuse these
    flags with the PE FileHeader Characteristics. Individual
    characteristics can be inspected by performing a bitwise AND
    operation with the following constants:

    .. c:type:: HIGH_ENTROPY_VA

        ASLR with 64 bit address space.

    .. c:type:: DYNAMIC_BASE

        File can be relocated - also marks the file as ASLR compatible

    .. c:type:: FORCE_INTEGRITY
    .. c:type:: NX_COMPAT

        Marks the file as DEP compatible

    .. c:type:: NO_ISOLATION
    .. c:type:: NO_SEH

        The file does not contain structured exception handlers, this must be
        set to use SafeSEH

    .. c:type:: NO_BIND
    .. c:type:: APPCONTAINER

        Image should execute in an AppContainer

    .. c:type:: WDM_DRIVER

        Marks the file as a Windows Driver Model (WDM) device driver.

    .. c:type:: GUARD_CF

        Image supports Control Flow Guard.

    .. c:type:: TERMINAL_SERVER_AWARE

        Marks the file as terminal server compatible

.. c:type:: size_of_stack_reserve

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::SizeOfStackReserve. This is the default
    amount of virtual memory that will be reserved for stack.

.. c:type:: size_of_stack_commit

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::SizeOfStackCommit. This is the default
    amount of virtual memory that will be allocated for stack.

.. c:type:: size_of_heap_reserve

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::SizeOfHeapReserve. This is the default
    amount of virtual memory that will be reserved for main process heap.

.. c:type:: size_of_heap_commit

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::SizeOfHeapCommit. This is the default
    amount of virtual memory that will be allocated for main process heap.

.. c:type:: loader_flags

    .. versionadded:: 3.8.0

    Value of IMAGE_OPTIONAL_HEADER::LoaderFlags.

.. c:type:: number_of_rva_and_sizes

    Value of IMAGE_OPTIONAL_HEADER::NumberOfRvaAndSizes. This is the number of
    items in the IMAGE_OPTIONAL_HEADER::DataDirectory array.

.. c:type:: data_directories

    .. versionadded:: 3.8.0

    A zero-based array of data directories. Each data directory contains virtual
    address and length of the appropriate data directory. Each data directory
    has the following entries:

    .. c:member:: virtual_address

        Relative virtual address (RVA) of the PE data directory. If this is zero,
        then the data directory is missing.
        Note that for digital signature, this is the file offset, not RVA.

    .. c:member:: size

        Size of the PE data directory, in bytes.

        The index for the data directory entry can be one of the following values:

    .. c:type:: IMAGE_DIRECTORY_ENTRY_EXPORT

        Data directory for exported functions.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_IMPORT

        Data directory for import directory.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_RESOURCE

        Data directory for resource section.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_EXCEPTION

        Data directory for exception information.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_SECURITY

        This is the raw file offset and length of the image digital signature.
        If the image has no embedded digital signature, this directory will contain zeros.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_BASERELOC

        Data directory for image relocation table.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_DEBUG

        Data directory for debug information.

        IMAGE_DEBUG_DIRECTORY::Type values:

            .. c:type:: IMAGE_DEBUG_TYPE_UNKNOWN
            .. c:type:: IMAGE_DEBUG_TYPE_COFF
            .. c:type:: IMAGE_DEBUG_TYPE_CODEVIEW
            .. c:type:: IMAGE_DEBUG_TYPE_FPO
            .. c:type:: IMAGE_DEBUG_TYPE_MISC
            .. c:type:: IMAGE_DEBUG_TYPE_EXCEPTION
            .. c:type:: IMAGE_DEBUG_TYPE_FIXUP
            .. c:type:: IMAGE_DEBUG_TYPE_OMAP_TO_SRC
            .. c:type:: IMAGE_DEBUG_TYPE_OMAP_FROM_SRC
            .. c:type:: IMAGE_DEBUG_TYPE_BORLAND
            .. c:type:: IMAGE_DEBUG_TYPE_RESERVED10
            .. c:type:: IMAGE_DEBUG_TYPE_CLSID
            .. c:type:: IMAGE_DEBUG_TYPE_VC_FEATURE
            .. c:type:: IMAGE_DEBUG_TYPE_POGO
            .. c:type:: IMAGE_DEBUG_TYPE_ILTCG
            .. c:type:: IMAGE_DEBUG_TYPE_MPX
            .. c:type:: IMAGE_DEBUG_TYPE_REPRO

    .. c:type:: IMAGE_DIRECTORY_ENTRY_ARCHITECTURE
    .. c:type:: IMAGE_DIRECTORY_ENTRY_COPYRIGHT
    .. c:type:: IMAGE_DIRECTORY_ENTRY_TLS

        Data directory for image thread local storage.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG

        Data directory for image load configuration.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_BOUND_IMPORT

        Data directory for image bound import table.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_IAT

        Data directory for image Import Address Table.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_DELAY_IMPORT

        Data directory for Delayed Import Table. Structure of the delayed import table
        is linker-dependent. Microsoft version of delayed imports is described
        in the sources "delayimp.h" and "delayimp.cpp", which can be found
        in MS Visual Studio 2008 CRT sources.

    .. c:type:: IMAGE_DIRECTORY_ENTRY_COM_DESCRIPTOR

        Data directory for .NET headers.

    *Example:  pe.data_directories[pe.IMAGE_DIRECTORY_ENTRY_EXPORT].virtual_address != 0*

.. c:type:: number_of_sections

    Number of sections in the PE.

.. c:type:: sections

    .. versionadded:: 3.3.0

    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:

    .. c:member:: name

        Section name.

    .. c:member:: full_name

        If the name in the section table contains a slash (/) followed by
        a representation of the decimal number in ASCII format, then this field
        contains a string from the specified offset in the string table.
        Otherwise, this field contains the same value as a name field.

        Even though it's not a standard, MinGW and Cygwin compilers use this
        feature to store section names which are longer than 8 characters.

    .. c:member:: characteristics

        Section characteristics.

    .. c:member:: virtual_address

        Section virtual address.

    .. c:member:: virtual_size

        Section virtual size.

    .. c:member:: raw_data_offset

        Section raw offset.

    .. c:member:: raw_data_size

        Section raw size.

    .. c:member:: pointer_to_relocations

        .. versionadded:: 3.8.0

        Value of IMAGE_SECTION_HEADER::PointerToRelocations.

    .. c:member:: pointer_to_line_numbers

        .. versionadded:: 3.8.0

        Value of IMAGE_SECTION_HEADER::PointerToLinenumbers.

    .. c:member:: number_of_relocations

        .. versionadded:: 3.8.0

        Value of IMAGE_SECTION_HEADER::NumberOfRelocations.

    .. c:member:: number_of_line_numbers

        .. versionadded:: 3.8.0

        Value of IMAGE_SECTION_HEADER::NumberOfLineNumbers.

    *Example:  pe.sections[0].name == ".text"*

    Individual section characteristics can be inspected using a bitwise AND
    operation with the following constants:

    .. c:type:: SECTION_NO_PAD
    .. c:type:: SECTION_CNT_CODE
    .. c:type:: SECTION_CNT_INITIALIZED_DATA
    .. c:type:: SECTION_CNT_UNINITIALIZED_DATA
    .. c:type:: SECTION_LNK_OTHER
    .. c:type:: SECTION_LNK_INFO
    .. c:type:: SECTION_LNK_REMOVE
    .. c:type:: SECTION_LNK_COMDAT
    .. c:type:: SECTION_NO_DEFER_SPEC_EXC
    .. c:type:: SECTION_GPREL
    .. c:type:: SECTION_MEM_FARDATA
    .. c:type:: SECTION_MEM_PURGEABLE
    .. c:type:: SECTION_MEM_16BIT
    .. c:type:: SECTION_LNK_NRELOC_OVFL
    .. c:type:: SECTION_MEM_LOCKED
    .. c:type:: SECTION_MEM_PRELOAD
    .. c:type:: SECTION_ALIGN_1BYTES
    .. c:type:: SECTION_ALIGN_2BYTES
    .. c:type:: SECTION_ALIGN_4BYTES
    .. c:type:: SECTION_ALIGN_8BYTES
    .. c:type:: SECTION_ALIGN_16BYTES
    .. c:type:: SECTION_ALIGN_32BYTES
    .. c:type:: SECTION_ALIGN_64BYTES
    .. c:type:: SECTION_ALIGN_128BYTES
    .. c:type:: SECTION_ALIGN_256BYTES
    .. c:type:: SECTION_ALIGN_512BYTES
    .. c:type:: SECTION_ALIGN_1024BYTES
    .. c:type:: SECTION_ALIGN_2048BYTES
    .. c:type:: SECTION_ALIGN_4096BYTES
    .. c:type:: SECTION_ALIGN_8192BYTES
    .. c:type:: SECTION_ALIGN_MASK
    .. 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
    .. c:type:: SECTION_SCALE_INDEX

    *Example: pe.sections[1].characteristics & pe.SECTION_CNT_CODE*

.. c:type:: overlay

    .. versionadded:: 3.6.0

    A structure containing the following integer members:

    .. c:member:: offset

        Overlay section offset. This is 0 for PE files that don't have overlaid
        data and undefined for non-PE files.

    .. c:member:: size

        Overlay section size. This is 0 for PE files that don't have overlaid
        data and undefined for non-PE files.

    *Example: uint8(pe.overlay.offset) == 0x0d and pe.overlay.size > 1024*

.. 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

    .. versionchanged:: 3.3.0

    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:

    .. c:member:: rva

        The RVA of the resource data.

    .. c:member:: offset

        Offset for the resource data. This can be undefined if the RVA is
        invalid.

    .. 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 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*

    *Example: pe.resources[0].name_string == "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

.. c:type:: version_info

    .. versionadded:: 3.2.0

    Dictionary containing the PE's version information. Typical keys are:

        ``Comments``
        ``CompanyName``
        ``FileDescription``
        ``FileVersion``
        ``InternalName``
        ``LegalCopyright``
        ``LegalTrademarks``
        ``OriginalFilename``
        ``ProductName``
        ``ProductVersion``

    For more information refer to:

    http://msdn.microsoft.com/en-us/library/windows/desktop/ms646987(v=vs.85).aspx

    *Example:  pe.version_info["CompanyName"] contains "Microsoft"*

.. c:type:: version_info_list

    Array of structures containing information about the PE's version information.

    .. c:member:: key

        Key of version information.

    .. c:member:: value

        Value of version information.

    *Example:  pe.version_info_list[0].value contains "Microsoft"*

.. c:type:: number_of_signatures

    Number of authenticode signatures in the PE.

.. c:type:: is_signed

    True if any of the PE signatures is verified. Verified here means, that the signature is formally correct: digests match,
    signer public key correctly verifies the encrypted digest, etc. But this doesn't mean that the signer (and thus the signature)
    can be trusted as there are no trust anchors involved in the verification.

.. c:type:: signatures

    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:: thumbprint

        .. versionadded:: 3.8.0

        A string containing the thumbprint of the signature.

    .. c:member:: issuer

        A string containing information about the issuer. These are some
        examples::

            "/C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Code Signing PCA"

            "/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at https://www.verisign.com/rpa (c)10/CN=VeriSign Class 3 Code Signing 2010 CA"

            "/C=GB/ST=Greater Manchester/L=Salford/O=COMODO CA Limited/CN=COMODO Code Signing CA 2"

    .. c:member:: subject

        A string containing information about the subject.

    .. c:member:: version

        Version number.

    .. c:member:: algorithm

        String representation of the algorithm used for this
    signature. Usually "sha1WithRSAEncryption". It depends on the
    X.509 and PKCS#7 implementations and possibly their versions,
    consider using algorithm_oid instead.

    .. c:member:: algorithm_oid

        Object ID of the algorithm used for this signature, expressed
        in numeric ASN.1 dot notation. The name contained in
        algorithm is derived from this value. The object id is
        expected to be stable across X.509 and PKCS#7 implementations
        and their versions.

    For example, when using the current OpenSSL-based implementation::

        algorithm_oid == "1.2.840.113549.1.1.11"

    is functionally equivalent to::

            algorithm == "sha1WithRSAEncryption"

    .. c:member:: serial

        A string containing the serial number. This is an example::

        "52:00:e5:aa:25:56:fc:1a:86:ed:96:c9:d4:4b:33:c7"

    .. c:member:: not_before

        Unix timestamp on which the validity period for this signature begins.

    .. c:member:: not_after

        Unix timestamp on which the validity period for this signature ends.

    .. c:member:: valid_on(timestamp)

        Function returning true if the signature was valid on the date
        indicated by *timestamp*. The following sentence::

            pe.signatures[n].valid_on(timestamp)

        Is equivalent to::

            timestamp >= pe.signatures[n].not_before and timestamp <= pe.signatures[n].not_after

   .. c:member:: verified

        Boolean, true if signature was sucessfully verified. More details about what the `verified` means is mentioned
        under the attribute `pe.is_signed`.

    .. c:member:: digest_alg

        Name of the algorithm used for file digest. Usually "sha1" or "sha256"

    .. c:member:: digest

        Digest of the file signed in the signature.

    .. c:member:: file_digest

        Calculated digest using digest_alg of the analysed file.

    .. c:member:: number_of_certificates

        Number of the certificates stored in the signature, including the ones in countersignatures.

    .. c:type:: certificates

        A zero-based array of certificates stored in the signature, including the ones in countersignatures.
        The members of the certificates are identical to those already explained before, with the same name.

        .. c:member:: thumbprint
        .. c:member:: issuer
        .. c:member:: subject
        .. c:member:: version
        .. c:member:: algorithm
        .. c:member:: serial
        .. c:member:: not_before
        .. c:member:: not_after
    
    .. c:type:: signer_info

        Information about the signature signer.

        .. c:member:: program_name

            Optional program name stored in the signature.

        .. c:member:: digest

            Signed digest of the signature.

        .. c:member:: digest_alg

            Algorithm used for the digest of the signature. Usually "sha1" or "sha256"

        .. c:member:: length_of_chain

            Number of certificates in the signers chain.

        .. c:type:: chain

        A zero-based array of certificates in the signers chain. The members of the certificates are
        identical to those already explained before, with the same name.

            .. c:member:: thumbprint
            .. c:member:: issuer
            .. c:member:: subject
            .. c:member:: version
            .. c:member:: algorithm
            .. c:member:: serial
            .. c:member:: not_before
            .. c:member:: not_after

    .. c:member:: number_of_countersignatures

        Number of the countersignatures of the signature.

    .. c:type:: countersignatures

        A zero-based array of the countersignatures of the signature.
        Almost always it's just single timestamp one.

        .. c:member:: verified

            Boolean, true if countersignature was sucessfully verified. More details about what the `verified` means is mentioned
            under the attribute `pe.is_signed`.

        .. c:member:: sign_time

            Integer - unix time of the timestamp signing time.

        .. c:member:: digest

            Signed digest of the countersignature.

        .. c:member:: digest_alg

            Algorithm used for the digest of the countersignature. Usually "sha1" or "sha256"

        .. c:member:: length_of_chain

            Number of certificates in the countersigners chain.

        .. c:type:: chain

        A zero-based array of certificates in the countersigners chain. The members of the certificates are
        identical to those already explained before, with the same name.

            .. c:member:: thumbprint
            .. c:member:: issuer
            .. c:member:: subject
            .. c:member:: version
            .. c:member:: algorithm
            .. c:member:: serial
            .. c:member:: not_before
            .. c:member:: not_after

.. c:type:: rich_signature

    Structure containing information about the PE's rich signature as
    documented `here <http://www.ntcore.com/files/richsign.htm>`_.

    .. c:member:: offset

        Offset where the rich signature starts. It will be undefined if the
        file doesn't have a rich signature.

    .. c:member:: length

        Length of the rich signature, not including the final "Rich" marker.

    .. c:member:: key

        Key used to encrypt the data with XOR.

    .. c:member:: raw_data

        Raw data as it appears in the file.

    .. c:member:: clear_data

        Data after being decrypted by XORing it with the key.

    .. c:member:: version_data

        .. versionadded:: 4.3.0

        Version fields after being decrypted by XORing it with the key.

    .. c:function:: version(version, [toolid])

        .. versionadded:: 3.5.0

        Function returning a sum of count values of all matching *version*
        records. Provide the optional *toolid* argument to only match when both
        match for one entry. More information can be found here:

        http://www.ntcore.com/files/richsign.htm

        Note: Prior to version *3.11.0*, this function returns only a boolean
        value (0 or 1) if the given *version* and optional *toolid* is present
        in an entry.

        *Example: pe.rich_signature.version(24215, 261) == 61*

    .. c:function:: toolid(toolid, [version])

        .. versionadded:: 3.5.0

        Function returning a sum of count values of all matching *toolid*
        records. Provide the optional *version* argument to only match when
        both match for one entry. More information can be found here:

        http://www.ntcore.com/files/richsign.htm

        Note: Prior to version *3.11.0*, this function returns only a boolean
        value (0 or 1) if the given *toolid* and optional *version* is present
        in an entry.

        *Example: pe.rich_signature.toolid(170, 40219) >= 99*

.. c:type:: pdb_path

    .. versionadded:: 4.0.0

    Path of the PDB file for this PE if present.

    *Example: pe.pdb_path == "D:\\workspace\\2018_R9_RelBld\\target\\checkout\\custprof\\Release\\custprof.pdb"*

.. c:function:: exports(function_name)

    Function returning true if the PE exports *function_name* or
    false otherwise.

    *Example:  pe.exports("CPlApplet")*

.. c:function:: exports(ordinal)

    .. versionadded:: 3.6.0

    Function returning true if the PE exports *ordinal* or
    false otherwise.

    *Example:  pe.exports(72)*

.. c:function:: exports(/regular_expression/)

    .. versionadded:: 3.7.1

    Function returning true if the PE exports *regular_expression* or
    false otherwise.

    *Example:  pe.exports(/^AXS@@/)*

.. c:function:: exports_index(function_name)

    .. versionadded:: 4.0.0

    Function returning the index into the export_details array where the named
    function is, undefined otherwise.

    *Example:  pe.exports_index("CPlApplet")*

.. c:function:: exports_index(ordinal)

    .. versionadded:: 4.0.0

    Function returning the index into the export_details array where the
    exported ordinal is, undefined otherwise.

    *Example:  pe.exports_index(72)*

.. c:function:: exports_index(/regular_expression/)

    .. versionadded:: 4.0.0

    Function returning the first index into the export_details array where the
    regular expression matches the exported name, undefined otherwise.

    *Example:  pe.exports_index(/^ERS@@/)*

.. c:type:: number_of_exports

    .. versionadded:: 3.6.0

    Number of exports in the PE.

.. c:type:: export_details

    .. versionadded:: 4.0.0

    Array of structures containing information about the PE's exports.

    .. c:member:: offset

        Offset where the exported function starts.

    .. c:member:: name

        Name of the exported function. It will be undefined if the function has
        no name.

    .. c:member:: forward_name

        The name of the function where this export forwards to. It will be
        undefined if the export is not a forwarding export.

    .. c:member:: ordinal

        The ordinal of the exported function, after the ordinal base has been
        applied to it.

.. c:type:: dll_name

    .. versionadded:: 4.0.0

    The name of the DLL, if it exists in the export directory.

.. c:type:: export_timestamp

    .. versionadded:: 4.0.0

    The timestamp the export data was created..

.. c:type:: number_of_imports

    .. versionadded:: 3.6.0

    Number of imported DLLs in the PE.

.. c:type:: number_of_imported_functions

    .. versionadded:: 4.1.0

    Number of imported functions in the PE.

.. c:type:: number_of_delayed_imports

    .. versionadded:: 4.2.0

    Number of delayed imported DLLs in the PE. (Number of IMAGE_DELAYLOAD_DESCRIPTOR parsed from file)

.. c:type:: number_of_delay_imported_functions

    .. versionadded:: 4.2.0

    Number of delayed imported functions in the PE.

.. c:function:: imports(dll_name, function_name)

    Function returning true if the PE imports *function_name* from *dll_name*,
    or false otherwise. *dll_name* is case insensitive.

    *Example:  pe.imports("kernel32.dll", "WriteProcessMemory")*

.. c:function:: imports(dll_name)

    .. versionadded:: 3.5.0
    .. versionchanged:: 4.0.0

    Function returning the number of functions from the *dll_name*, in the PE
    imports. *dll_name* is case insensitive.

    Note: Prior to version 4.0.0, this function returned only a boolean value
    indicating if the given DLL name was found in the PE imports. This change
    is backward compatible, as any number larger than 0 also evaluates as
    true.

    *Examples:  pe.imports("kernel32.dll"), pe.imports("kernel32.dll") == 10*

.. c:function:: imports(dll_name, ordinal)

    .. versionadded:: 3.5.0

    Function returning true if the PE imports *ordinal* from *dll_name*,
    or false otherwise. *dll_name* is case insensitive.

    *Example:  pe.imports("WS2_32.DLL", 3)*

.. c:function:: imports(dll_regexp, function_regexp)

    .. versionadded:: 3.8.0
    .. versionchanged:: 4.0.0

    Function returning the number of functions from the PE imports where a
    function name matches *function_regexp* and a DLL name matches
    *dll_regexp*. Both *dll_regexp* and *function_regexp* are case sensitive
    unless you use the "/i" modifier in the regexp, as shown in the example
    below.

    Note: Prior to version 4.0.0, this function returned only a boolean value
    indicating if matching import was found or not. This change is backward
    compatible, as any number larger than 0 also evaluates as true.

    *Example:  pe.imports(/kernel32\.dll/i, /(Read|Write)ProcessMemory/) == 2*


.. c:function:: imports(import_flag, dll_name, function_name)

    .. versionadded:: 4.2.0

    Function returning true if the PE imports *function_name* from *dll_name*,
    or false otherwise. *dll_name* is case insensitive.

    *import_flag* is flag which specify type of import which should YARA search for.
    This value can be composed by bitwise OR these values:

        .. c:member:: pe.IMPORT_STANDARD

            Search in standard imports

        .. c:member:: pe.IMPORT_DELAYED

            Search in delayed imports

        .. c:member:: pe.IMPORT_ANY

            Search in all imports

    *Example:  pe.imports(pe.IMPORT_DELAYED | pe.IMPORT_STANDARD, "kernel32.dll", "WriteProcessMemory")*

.. c:function:: imports(import_flag, dll_name)

    .. versionadded:: 4.2.0

    Function returning the number of functions from the *dll_name*, in the PE
    imports. *dll_name* is case insensitive.

    *Examples:  pe.imports(pe.IMPORT_DELAYED, "kernel32.dll"), pe.imports("kernel32.dll") == 10*

.. c:function:: imports(import_flag, dll_name, ordinal)

    .. versionadded:: 4.2.0

    Function returning true if the PE imports *ordinal* from *dll_name*,
    or false otherwise. *dll_name* is case insensitive.

    *Example:  pe.imports(pe.IMPORT_DELAYED, "WS2_32.DLL", 3)*

.. c:function:: imports(import_flag, dll_regexp, function_regexp)

    .. versionadded:: 4.2.0

    Function returning the number of functions from the PE imports where a
    function name matches *function_regexp* and a DLL name matches
    *dll_regexp*. Both *dll_regexp* and *function_regexp* are case sensitive
    unless you use the "/i" modifier in the regexp, as shown in the example
    below.

    *Example:  pe.imports(pe.IMPORT_DELAYED, /kernel32\.dll/i, /(Read|Write)ProcessMemory/) == 2*

.. c:type:: import_details

    .. versionadded:: 4.2.0

    Array of structures containing information about the PE's imports libraries.

    .. c:member:: library_name

        Library name.

    .. c:member:: number_of_functions

        Number of imported function.

    .. c:member:: functions

        Array of structures containing information about the PE's imports functions.

        .. c:member:: name

            Name of imported function

        .. c:member:: ordinal

            Ordinal of imported function. If ordinal does not exist this value is YR_UNDEFINED

        .. c:member:: rva

            .. versionadded:: 4.3.0

            Relative virtual address (RVA) of imported function. If rva not found then this value is YR_UNDEFINED

    *Example: pe.import_details[1].library_name == "library_name"

.. c:type:: delayed_import_details

    .. versionadded:: 4.2.0

    Array of structures containing information about the PE's delayed imports libraries.

    .. c:member:: library_name

        Library name.

    .. c:member:: number_of_functions

        Number of imported function.

    .. c:member:: functions

        Array of structures containing information about the PE's imports functions.

        .. c:member:: name

            Name of imported function

        .. c:member:: ordinal

            Ordinal of imported function. If ordinal does not exist this value is YR_UNDEFINED

        .. c:member:: rva

            .. versionadded:: 4.3.0
            
            Relative virtual address (RVA) of imported function. If rva not found then this value is YR_UNDEFINED

    *Example: pe.delayed_import_details[1].name == "library_name"

.. c:function:: import_rva(dll, function)

    .. versionadded:: 4.3.0

    Function returning the RVA of an import that matches the DLL name and
    function name.

    *Example: pe.import_rva("PtImageRW.dll", "ord4") == 254924

.. c:function:: import_rva(dll, ordinal)

    .. versionadded:: 4.3.0

    Function returning the RVA of an import that matches the DLL name and
    ordinal number.

    *Example: pe.import_rva("PtPDF417Decode.dll", 4) == 254924

.. c:function:: delayed_import_rva(dll, function)

    .. versionadded:: 4.3.0

    Function returning the RVA of a delayed import that matches the DLL name and
    function name.

    *Example: pe.delayed_import_rva("QDB.dll", "ord116") == 6110705

.. c:function:: delayed_import_rva(dll, ordinal)

    .. versionadded:: 4.3.0

    Function returning the RVA of a delayed import that matches the DLL name and
    ordinal number.

    *Example: pe.delayed_import_rva("QDB.dll", 116) == 6110705

.. c:function:: locale(locale_identifier)

    .. versionadded:: 3.2.0

    Function returning true if the PE has a resource with the specified locale
    identifier. Locale identifiers are 16-bit integers and can be found here:

    http://msdn.microsoft.com/en-us/library/windows/desktop/dd318693(v=vs.85).aspx

    *Example: pe.locale(0x0419) // Russian (RU)*

.. c:function:: language(language_identifier)

    .. versionadded:: 3.2.0

    Function returning true if the PE has a resource with the specified language
    identifier. Language identifiers are 8-bit integers and can be found here:

    http://msdn.microsoft.com/en-us/library/windows/desktop/dd318693(v=vs.85).aspx

    *Example: pe.language(0x0A) // Spanish*

.. c:function:: imphash()

    .. versionadded:: 3.2.0

    Function returning the import hash or imphash for the PE. The imphash is
    an MD5 hash of the PE's import table after some normalization. The imphash
    for a PE can be also computed with `pefile <http://code.google.com/p/pefile/>`_
    and you can find more information in `Mandiant's blog
    <https://www.mandiant.com/resources/blog/tracking-malware-import-hashing/>`_. The returned
    hash string is always in lowercase.

    *Example: pe.imphash() == "b8bb385806b89680e13fc0cf24f4431e"*

.. 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)

    .. versionadded:: 3.3.0

    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)*

.. c:type:: is_pe

    .. versionadded:: 3.8.0

    Return true if the file is a PE.

    *Example: pe.is_pe*

.. c:function:: is_dll()

    .. versionadded:: 3.5.0

    Function returning true if the PE is a DLL.

    *Example: pe.is_dll()*

.. c:function:: is_32bit()

    .. versionadded:: 3.5.0

    Function returning true if the PE is 32bits.

    *Example: pe.is_32bit()*

.. c:function:: is_64bit()

    .. versionadded:: 3.5.0

    Function returning true if the PE is 64bits.

    *Example: pe.is_64bit()*

.. c:function:: rva_to_offset(addr)

    .. versionadded:: 3.6.0

    Function returning the file offset for RVA *addr*. Be careful to pass
    relative addresses here and not absolute addresses, like `pe.entry_point`
    when scanning a process.

    *Example: pe.rva_to_offset(pe.sections[0].virtual_address) == pe.sections[0].raw_data_offset*

    This example will make sure the offset for the virtual address in the first
    section equals the file offset for that section.

---

## File: docs/modules/string.rst

.. _string-module:

###########
String module
###########

.. versionadded:: 4.3.0

The String module provides functions for manipulating strings as returned by
modules. The strings referenced here are not YARA strings as defined in the
strings section of your rule.

.. c:function:: to_int(string)

    .. versionadded:: 4.3.0

    Convert the given string to a signed integer. If the string starts with "0x"
    it is treated as base 16. If the string starts with "0" it is treated base
    8. Leading '+' or '-' is also supported.

    *Example: string.to_int("1234") == 1234*
    *Example: string.to_int("-10") == -10*
    *Example: string.to_int("-010") == -8*

.. c:function:: to_int(string, base)

    .. versionadded:: 4.3.0

    Convert the given string, interpreted with the given base, to a signed
    integer. Base must be 0 or between 2 and 36 inclusive. If it is zero then
    the string will be intrepreted as base 16 if it starts with "0x" or as base
    8 if it starts with "0". Leading '+' or '-' is also supported.

    *Example: string.to_int("011", 8) == 9*
    *Example: string.to_int("-011", 0) == -9*

.. c:function:: length(string)

    .. versionadded:: 4.3.0

    Return the length of the string, which can be any sequence of bytes. NULL
    bytes included.

    *Example: string.length("AXS\x00ERS") == 7*