> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.

# Adding a Custom Rule

Although you can’t create a custom rule yourself yet—we do that for you—you can add it when it’s ready. All you need is [Expert Editor](https://docs.xorlab.com/9.0/expert-editor.md) and the config files located in the `activeguard/core/rule_sets/90_local/` folder:

1. Open Expert Editor.

2. In the folder view in the left pane, expand `activeguard`, then `core`, `rule_sets`, and finally `90_local`. You will see three folders: `params`, `rules`, and `templates`:

   ![Folders containing rules](https://mintcdn.com/xorlab/O_O2TUa6eRBR54aI/9.0/assets/rules-folders.png?fit=max\&auto=format\&n=O_O2TUa6eRBR54aI\&q=85\&s=ca00a8ff8d893241c4a20c8c3baf519c)

3. Use the context menu for the `rules` folder to create a new file:

   ![Hamburger icon for the context menu](https://mintcdn.com/xorlab/O_O2TUa6eRBR54aI/9.0/assets/hamburger-icon.png?fit=max\&auto=format\&n=O_O2TUa6eRBR54aI\&q=85\&s=50eddc9e6d710feced76e3d062ee352e)

4. Enter `<rule_name>.xml`—for example, `CUSTOM_spam_keyword_match.xml`—as the name for the file in the dialog box that appears, and click **Create**. The rule can also be put into arbitrary subfolders of the `rules` folder.

5. Click the file you have just created in the left pane and paste the content of the custom rule we provided to you into the right pane.

6. Now, expand the `params` folder in the left pane and click the `local.properties` file. In the right pane, add the state parameter to activate the rule. The parameter should consist of the name of the rule XML file you created in the step #4 with the `_state` suffix and the `ACTIVE` keyword, e.g., `CUSTOM_spam_keyword_match_state=ACTIVE`. Click **Publish**.

## Custom rule with a reference to a new custom list

In case your custom rule references to a new custom list, you will also need to add this new custom list.

> [!NOTE]
>
> **Creating the `lists` folder**
>
> If there is no `lists` folder inside `90_local`, hover the mouse cursor over the folder icon next to `90_local`. The icon will change to a vertical ellipsis (`…`) or a hamburger (see step #3 in the previous section). Click it to display the context menu, select **New Folder**, enter `lists` as the name of the folder in the dialog box that appears, and click **Create**.

1. Use the context menu for the `lists` folder to create a new file inside of it (see step #5 in the previous section).

2. Enter `<list_name>.list.info.json`—for example, `CUSTOM_spam_domains.list.info.json`—as the name for the file in the dialog box that appears and click **Create**.

3. Click the file you have just created in the left pane and add the following content to this file in the right pane (the values in the `key:values` pairs here are just examples):

   ```json theme={null}
   {"displayName":"Incoming subject rewrite recipients","category":"custom","description":"Internal recipients for which incoming emails will be subject prefixed."}
   ```

   where

   * `displayName` is the title/name of the list (*no.1 on the screenshot below*)

   * `category` is the name of the category the list belongs to (existing or a new one; *no.2 on the screenshot below*)

   * `description` is the description of the list displayed in the right pane after selecting a list in the left pane of the [Lists](https://docs.xorlab.com/9.0/lists.md) view (*no.3 on the screenshot below*).

   ![List elements in the Lists view](https://mintcdn.com/xorlab/O_O2TUa6eRBR54aI/9.0/assets/list-elements.png?fit=max\&auto=format\&n=O_O2TUa6eRBR54aI\&q=85\&s=d9dee745962a6aa0c52a553fa7728fc6)

4. Click **Publish** to apply changes. Will be automatically active after one minute. The new list should be visible on the **Lists** page.

## Adding a YARA rule

You can block emails using a [YARA](https://virustotal.github.io/yara/) rule by adding it to a custom rule. This YARA-based rule consists of 3 main elements:

1. Condition that applies the rule to specified objects.
2. Actual YARA rule.
3. Decision which tags or quarantines the matched email.

In the `activeguard/core/rule_sets/90_local/rules/examples` folder, you will find an example empty rule:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Change DISABLED to ACTIVE to activate the rule. -->
<rule name="example_rule" state="DISABLED" priority="390" applyTo="INCOMING">
  <pipeline>Emails</pipeline>
  <if>
    <and>
      <!-- Add conditions for decision here -->
      <hasTag name="#trusted"/>
    </and>
    <then>
      <decision decision="UNDECIDED">
        <tag>#mytag</tag>
      </decision>
    </then>
  </if>
</rule>
```

Let’s modify this example to create a YARA rule. We’re going to implement a YARA rule which finds a [CVE-2018-0802](https://nvd.nist.gov/vuln/detail/CVE-2018-0802) exploit of a vulnerability in Word, so it needs to be applied to Word and RTF files.

1. Start with giving a `name` to your rule, e.g., `YARA_cve_2018_0802`, activating the rule in the `state` property, and selecting the email flow it should be applied to in `applyTo`:

   ```xml theme={null}
   <rule name="YARA_cve_2018_0802" state="ACTIVE" priority="20" applyTo="ALL">
   ```

   The allowed values for `applyTo` are: `ALL`, `INCOMING`, `OUTGOING`, `INTERNAL`.

   The `priority` values are within the range of 0-1000. We recommend setting the priority to at least above 20 to ensure the built-in tag rules still apply. Then, either set it between 300 and 400 to ensure the rule has precedence over the built-in quarantine rules, or set it above 700 to ensure that it does not have precedence over the built-in quarantine rules, i.e., is applied afterward.

2. Write a condition that would match all Word and RTF attachments during the file scan:

   ```xml theme={null}
   <if>
     <ForEachFileScanRequest match="ANY">
       <and>
         <or>
           <fileType equals="word"/>
           <fileType equals="rtf"/>
         </or>
   ```

3. Now, add the actual YARA rule and close the condition block:

   ```xml theme={null}
         <yaraMatch>
           <yaraRule>rule rtf_CVE_2018_0802 { strings: $header_rtf = "\\rt" ascii nocase $equation = { 45 71 75 61 74 69 6F 6E 2E 33 }
             $header_and_shellcode = /03010[0-1]([0-9a-fA-F]){4}([0-9a-fA-F]+08)([0-9a-fA-F]{4})([0-9a-fA-F]{296})2500/ ascii nocase condition:
             uint32be(0) == 0x7B5C7274 and all of them }
           </yaraRule>
         </yaraMatch>
       </and>
     </ForEachFileScanRequest>
   ```

4. It’s time to decide what to do when an attachment matches your YARA rule. The simplest approach is to tag the message (here we used the exploit name as a tag), and then create a [campaign](https://docs.xorlab.com/9.0/query-based-classifiers.md) that will, for example, quarantine the emails with this tag:

   ```xml theme={null}
     <then>
       <decision decision="UNDECIDED">
         <tag>#cve_2018_0802</tag>
       </decision>
     </then>
   ```

5. Finish your custom rule by closing the condition:

   ```xml theme={null}
       </if>
   </rule>
   ```

The whole rule should look like this:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rule name="YARA_cve_2018_0802" state="ACTIVE" priority="20" applyTo="ALL">

  <if>
    <ForEachFileScanRequest match="ANY">
      <and>
        <or>
          <fileType equals="word"/>
          <fileType equals="rtf"/>
        </or>
        <yaraMatch>
          <yaraRule>rule rtf_CVE_2018_0802 { strings: $header_rtf = "\\rt" ascii nocase $equation = { 45 71 75 61 74 69 6F 6E 2E 33 }
            $header_and_shellcode = /03010[0-1]([0-9a-fA-F]){4}([0-9a-fA-F]+08)([0-9a-fA-F]{4})([0-9a-fA-F]{296})2500/ ascii nocase condition:
            uint32be(0) == 0x7B5C7274 and all of them }
          </yaraRule>
        </yaraMatch>
      </and>
    </ForEachFileScanRequest>
    <then>
      <decision decision="UNDECIDED">
        <tag>#cve_2018_0802</tag>
      </decision>
    </then>
  </if>
</rule>
```

### Multiple YARA rules

It is possible to use multiple YARA rules in one custom rule. All you have to do is to put them in the `<or>…</or>` block, just like you did with the `fileType` selector:

```xml theme={null}
        <yaraMatch>
          <or>
            <yaraRule>rule 1 {
              … }
            </yaraRule>
            <yaraRule>rule 2 {
              … }
            </yaraRule>
          </or>  
        </yaraMatch>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.