# Yara editor / browser

The Yara editor / browser is accessed using the `F7` shortcut and allows you to work with Yara rules. You can create new rules, edit existing ones using an embedded editor and browse all matching and non-matching rules in a glance.

For more informations on how Malcat supports Yara rules, please refer to Yara signatures.

## Viewing Yara rules

### Yara rules list

The Yara view displays a list of all the matching and non-matching Yara rules found in the directory `data/signatures` (and in the User data directory) for the current analyzed file. Columns can be clicked in order to change the rules sort order. By default, matching rules are displayed first and remaining rules are sorted by number of matching strings.

By clicking on a rule in the list, it will be set as the current rule and the rule code will be displayed in the Yara rule editor below. If you want to view a specific yara rule file, you can toggle the directory lister by clicking on the leftmost button in the middle on the screen, left of the yara rule file name. Clicking on a file in the directory lister will be open it inside the Yara editor.

The yara rule browser / editor

When a rule has been selected in the list, the quick view in the bottom left will also display a summary of the current rule, including comments and metadata, as well as the list of every matching patterns for this rule. Clicking on a pattern brings you to the pattern location inside the Hexadecimal view.

### Current Yara rule

The concept of current rule is pretty important in Malcat. By clicking on a rule or after creating a new one, the current rule marker will be set. In the future, all contextual actions in Malcat that are in need of a Yara rule will use this rule as a target. This includes:

- Adding the current selection as an hexadecimal pattern

- Adding a string as an ascii/wide string pattern

- Adding selected instructions as a pre-commented hexadecimal pattern

The name of the current rule will be repeated inside the context menu RightClick ‣ Add XXX to Yara ‣ Add to yara rule <name of current rule>.

### Filtering rules

The default Yara rule set that comes with Malcat contains already more than 2000 rules. Navigating through this many rules can be sometimes a challenge. By chance, it is really easy to look for a specific rule in Malcat. If you use the search box located on the top right of the view, you may filter displayed rules. Only the rules containing the text you have entered will be displayed. The text is searched in:

- the ID of the rule

- the name of the rule (the metadata “name”)

- the description of the rule (the metadata “description”)

The filtering is done on the fly, no need to hit enter.

Shortcut | Action
--- | ---
``Ctrl`+`F`` | Set focus to the view’s search box

## Adding a rule

In Malcat, you can easily create new Yara rule from within the interface. New user rules should be put inside the `signatures/` subdirectory of your User data directory. You can add a new Yara rule inside the currently open .yar file by clicking on the “+” icon left of the yara rule file name text field. A dialog will be shown where you can enter the details and metadata of the rule. By clicking ok, a rule with an empty condition will be added to the currently open Yara file. The new rule will also be set as the new current rule.

Creating a new Yara rule

The template used for new rules can be found in `data/signatures/new_yara_rule.tpl` and is presented below:

    rule %RULE_NAME% %RULE_TAG%{
        meta:
            name        = "%RULE_NAME%"
            category    = "%RULE_CATEGORY%"
            description = "%RULE_DESCRIPTION%"
            author      = "%RULE_AUTHOR%"
            created     = "%DATE%"
            reliability = %RULE_RELIABILITY%
            tlp         = "TLP:%RULE_TLP%"
            sample      = "%SHA256%"

        condition:
            true
    }

Note that if you don’t like it, you can override this template inside your User data directory like any other data files. In the template, you have access to the following string variables:

Variable | Meaning
--- | ---
%RULE_NAME% | The identifier of the rule
%RULE_TAG% | The tag of the rule, prefixed by “:” if not empty, e.g. “: suspicious” or “: malware”.
%RULE_CATEGORY% | The category of the rule, e.g. “stealer” or “persistence”
%RULE_DESCRIPTION% | A nice description of the rule
%RULE_RELIABILITY% | Reliability of the rule, a number between 0 (least reliable) and 100 (most reliable)
%RULE_AUTHOR% | The author(s) of the rule
%DATE% | Date of rule creation in `YYYY-mm-dd` format (always set to today)
%DATE_YEAR% | Year of rule creation in `YYYY` format
%DATE_MONTH% | Month of rule creation in `mm` format
%DATE_DAY% | Day of rule creation in `dd` format
%RULE_TLP% | TLP of rule, e.g. “white”
%RULE_TLP_UPPER% | TLP of rule in uppercase, e.g. “WHITE”
%SHA256% | sha256 sum of the current sample, lower case
%SHA256_UPPER% | sha256 sum of the current sample, upper case

## Editing a Yara rule

### Using the editor

You can modify any rule using the embedded Yara editor. Once your are done editing your new rule, hit ``Ctrl`+`S`` to save the current Yara file and rescan the analyzed binary. If you made any error, the Yara signatures analysis will fail and an error message will be displayed inside the Script editor.

Shortcut | Action
--- | ---
``Ctrl`+`S`` | Save current rule file

### Using context menus

Malcat makes it easy to add strings and bytes from within the different Views to the Current Yara rule. After selecting an interesting pattern, you can add using the context menu RightClick ‣ Add to Yara rule ‣ …. Currently, you can add:

- selected bytes from the Hexadecimal view or Structure/text view as either a string or hexadecimal pattern

- selected string(s) from the Strings list as either ascii or wide strings

- selected instructions from the Disassembly view as commented hexadecimal patterns

Adding selected code to the current Yara rule

Note that the file won’t be rescanned until you hit ``Ctrl`+`S``. Also for hexadecimal pattern, you can make use of exclusion masks (cf. Excluding bytes from selection). Excluded bytes/nibbles will be replaced by jokers (?) in the added Yara hexadecimal pattern.

Note

If you are not sure if a pattern will create false postives, make use of Malcat’s Searching in other files feature to search the pattern inside a large set of clean files efficiently.

## Reorganizing your rules

The Yara rules list displays the Yara rules found in, or included by, .yar files found in data/signatures and in the `signatures/` subdirectory of your User data directory. If you want to reorganize these .yar files, you may use the file browser control of the Yara editor. It first needs to be toggled on by clicking on the left-most button in the middle toolbar:

You can organize your yara files usin the embedded Yara file browser

Using the Yara files browser and its toolbar, you can perform some basic operations on your Yara files:

- You can open a Yara files inside the editor by double-clicking it

- You can add a new Yara files in the currently selected directory

- You can remove the currently selected Yara file (a confirmation dialog will be shown)

- You can rename the selected Yara file by clicking on its name a second time

- If you want to quickly locate you User data directory inside the files tree, you can click on the user button of the toolbar

For Yara file changes, you will need to reanalyse the file with ``Ctrl`+`R`` to see the changes applied.

Warning

Every *.yar file in the `signatures` directory will be imported separately in its own namespace. So if your yara rules are split into several files and include each other, this may lead to situations where a rule is imported twice or where a rule can’t access another because it lies in another namespace. In this scenario, the correct way to store your rules is:

- create a subdirectory (e.g. `signatures/myrules`) that should contain all the .yar to be included. Subdirectories are not scanned by Malcat, so these .yar won’t be imported.

- put a single *.yar file in the `signatures` directory that will include all your .yar files from `signatures/myrules` (in the correct order)