Adding a Custom Rule

Follow these instructions to add a custom rule:

Open Expert Editor and go to the folder activeguard/core/rule_sets/90_local/.
Create a new file within rules via the three dots context menu. Name it <rule_name>.xml (e.g. CUSTOM_spam_keyword_match.xml).
Open the file you just created and paste the content of the custom rule.
Inside params folder, open local.properties.
Add the parameter to activate the rule. Usually the format is <rule_name>_state=ACTIVE (e.g. CUSTOM_spam_keyword_match_state=ACTIVE).
Click Publish. The rule-set changes become active within about one minute.

Adding a custom list

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

Open Expert Editor and go to the folder activeguard/core/rule_sets/90_local/.
Create a new file within lists folder via the three dots context menu. If there is no lists folder inside 90_local, create one manually.
Enter <list_name>.list.info.json as file name. For example, CUSTOM_spam_domains.list.info.json.
Open the file you just created and add:
{"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 view (no.3 on the screenshot below).
Click Publish. The custom list becomes active within about one minute.

Adding a YARA rule

You can block emails using a YARA rule by adding it to a custom rule. This YARA-based rule consists of 3 main elements:

Condition to specify when the YARA rule is applied
Actual YARA rule.
Decision that tags or quarantines the matched email.

We start with this example rule and modify it to contain a YARA rule that finds CVE-2018-0802 exploits in Word and RTF files:

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

Set the name to YARA_cve_2018_0802, set the state property to ACTIVE, and select the email direction it should be applied to in applyTo:
<rule name="YARA_cve_2018_0802" state="ACTIVE" priority="20" applyTo="ALL">
The allowed values for applyTo are: ALL, INCOMING, OUTGOING, INTERNAL.
Priority
The priority values are within the range of 0-2000. 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 1000 to ensure that it does not have precedence over the built-in quarantine rules, i.e., is applied afterward.

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

<if>
  <ForEachFileScanRequest match="ANY">
    <and>
      <or>
        <fileType equals="word"/>
        <fileType equals="rtf"/>
      </or>

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

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

Define the action. Here we just add a Tag that can be later used in a campaign:

  <then>
    <decision decision="UNDECIDED">
      <tag>#cve_2018_0802</tag>
    </decision>
  </then>

The whole rule should look like this:

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

        <yaraMatch>
          <or>
            <yaraRule>rule 1 {
              … }
            </yaraRule>
            <yaraRule>rule 2 {
              … }
            </yaraRule>
          </or>  
        </yaraMatch>

Multi-Tenancy

A rule placed in 90_local as described above is the default for all tenants. To add a rule that applies to a single tenant only, put the rule file in activeguard/core/rule_sets/_tenantX/rules/custom/ instead, and activate it in the params folder of that same tenant. See Manage Tenant Rules for the folder structure and for overriding parameters per tenant.

​Adding a custom list

​Adding a YARA rule

​Multiple YARA rules

​Multi-Tenancy

Adding a custom list

Adding a YARA rule

Multiple YARA rules

Multi-Tenancy