# Welcome to YARA's documentation!

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:

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

Contents:

- Getting started
  - Compiling and installing YARA
    - Installing with vcpkg
    - Installing on Windows
    - Installing on Mac OS X with Homebrew
    - Installing `yara-python`
  - Running YARA for the first time
- Writing YARA rules
  - Comments
  - Strings
    - Hexadecimal strings
    - Text strings
    - Regular expressions
    - Private strings
    - Unreferenced strings
    - String Modifier Summary
  - Conditions
    - Counting strings
    - String offsets or virtual addresses
    - Match length
    - File size
    - Executable entry point
    - Accessing data at a given position
    - Sets of strings
    - Applying the same condition to many strings
    - Using anonymous strings with `of` and `for..of`
    - Iterating over string occurrences
    - Iterators
    - Referencing other rules
  - More about rules
    - Global rules
    - Private rules
    - Rule tags
    - Metadata
  - Using modules
  - Undefined values
  - External variables
  - Including files
- Modules
  - PE
    - Reference
  - ELF
    - Reference
  - Cuckoo
    - Reference
  - Magic
  - Hash
  - Math
  - Dotnet
    - Reference
  - Time
  - Console
  - String
- Writing your own modules
  - The "Hello World!" module
    - Building our "Hello World!"
  - The declaration section
    - Basic types
    - Structures
    - Arrays
    - Dictionaries
    - Functions
  - Initialization and finalization
  - Implementing the module's logic
    - Accessing the scanned data
    - Setting variable's values
    - Storing data for later use
  - More about functions
    - Function arguments
    - Return values
    - Accessing objects
    - Scan context
- Running YARA from the command-line
- Using YARA from Python
  - Reference
    - `yara.compile()`
    - `yara.load()`
    - `yara.set_config()`
    - `Rules`
    - `Match`
    - `StringMatch`
    - `StringMatchInstance`
- The C API
  - Initializing and finalizing libyara
  - Compiling rules
  - Defining external variables
  - Saving and retrieving compiled rules
  - Scanning data
    - Using a scanner
  - API reference
    - Data structures
    - Functions
    - Error codes