Creating and Managing PhishER Rules

In your PhishER platform, rules are logical expressions that allow you to automatically disposition and tag messages in your PhishER Inbox. The assigned tags trigger PhishER to run actions on the messages. You can create rules from the Rules tab. If you would like to create an action, see our How to Create and Manage PhishER Actions article.

The Rules tab contains two types of rules: custom rules and system rules. Custom rules are rules that you can create by using the Yara Rule Editor. System rules are default rules provided by KnowBe4. The Rules tab also contains global variables, which are variables that you create to use in multiple rules with the same strings. By updating a global variable, you can update all of the rules that contain those strings.

To learn more about how to create and manage PhishER rules, see the subsections below:

Jump to:
Creating Rules

• Creating Rules Using the Basic Editor
• Creating Rules Using the Advanced Editor
• Previewing Rules
• Editing Rules

Using Global Variables
Viewing the Rules List

Creating Rules

You can create custom rules in your PhishER platform to disposition messages that have been forwarded to your PhishER Inbox. To create your rules, you can use either the Basic Editor or the Advanced Editor. All custom rules must follow Yet Another Recursive/Ridiculous Acronym (YARA) logic. YARA is a tool used to identify and classify malware samples.

To create a rule, follow the steps below:

1. Log in to your PhishER platform.
2. From the sidebar on the left side of the page, select the Rules tab to open the Rules List page.
3. Click the New Rule button at the top-right corner of the page to open the Rule Details page.
   
4. In the Name field, enter a unique name for your rule. We recommend that you enter a name that briefly describes the function of the rule. The name cannot start with a numerical value, exceed 128 characters, or include any of the keywords listed in YARA's Writing YARA Rules documentation.
5. (Optional) In the Description field, enter a description of your rule. As a best practice, we recommend that you enter a description of the rule's intended function.
6. In the Edit Tags: section, add a custom tag that you would like to see attached to a message if the message matches this specific rule. To add a tag, click Add new tag and enter a name for your tag. Then, click outside of the Add new tag field to create the tag.
7. From the Choose target: drop-down menu, select the part of the message you would like the rule to be applied to or run on. The targets you can select are Raw, Headers, Body, or Attachments. By default, Raw will be selected.
8. In the Yara Rule Editor section, write your rule using either the Basic Editor or the Advanced Editor. For more information, see the subsections below.

Back to top

Creating Rules Using the Basic Editor

The Basic Editor allows you to create a custom rule without writing all of the YARA rule logic. You can enter values for strings and select conditions for your rule, and the Basic Editor will process your input to create the rule logic for your rule. To learn how to create a rule using the Basic Editor tab, see the screenshot and list below:

1. Basic Editor: Select this tab to display the options you can use to create a rule.
2. Create Strings: Create and define strings to use when creating your conditions. For more information, see our How Do I Create Strings and Conditions in the Basic Editor? article.
3. New String: Click this button to add a string to the rule. You can create up to five strings per rule.
4. Create Conditions: Create conditions by selecting how your defined strings should relate to each other. Conditions allow you to specify what messages you want your rule to affect. For more information, see our How Do I Create Strings and Conditions in the Basic Editor? article. You can select from the following options:
   • Match any of the defined strings: Select this option to detect messages that match any of your defined strings.
   • Match all of the defined strings: Select this option to detect messages that match all of your defined strings.
   • Custom conditions: Select this option to detect messages that match your custom conditions.
5. New Condition Group: If Custom conditions is selected, you can click this button to create custom conditions that messages must meet to be affected by the rule.
6. Save Rule: Click this button to save your rule. Your rule will display on the Rules List page under the Custom Rules subtab. After saving your rule, you can enable your rule by turning on the toggle under the rule's Status column (click to view). Then, click on the Apply Changes button in the top-right corner of the page.
7. Apply Rule to Inbox: Click this button to run your rule against all of the messages in your Inbox. At least one message must match your rule and preview rule criteria for this option to become available.

Back to top

Creating Rules Using the Advanced Editor

The Advanced Editor allows you to write the logic of your YARA Rule without guidance. If you edit a rule in the Advanced Editor, the Basic Editor will be disabled for the rule. To learn about writing rules with YARA rule logic, see our How to Write YARA Rules article. To learn how to create a rule using the Advanced Editor tab, see the screenshot and list below:

1. Advanced Editor: Select this tab to display the code block section where you can write a rule with YARA rule logic.
2. Save Rule: Click this button to save your rule. Your rule will appear on the Rules List page under the Custom Rules subtab. After saving your rule, you can enable your rule by turning on the toggle under the rule's Status column (click to view). Then, click on the Apply Changes button in the top-right corner of the page.
3. Apply Rule to Inbox: Click this button to run your rule against all of the messages in the Inbox. At least one message must match your rule and preview rule criteria for this option to become available.

Back to top

Previewing Rules

Before you save a new rule, we recommend previewing how the rule will affect your PhishER messages. To preview a rule, follow the steps below:

1. Log in to your PhishER platform.
2. From the sidebar on the left side of the page, select the Rules tab to open the Rules List page.
3. Click the New Rule button in the top-right corner of the page or select a rule on the Rules List page. When you click the New Rule button, the Rule Details page will open.
4. Write or modify your YARA rule using the YARA Rule Editor section.
5. Before saving your rule, click the Run Preview button. A list will display of all the messages in your Inbox that match your rule.
6. You can update the preview list by modifying the following criteria options:
   • Saved Query (Optional): Choose a custom Saved Query to see how the rule affects messages in that query.
   • Last 7 days: Select a date range for the messages you would like to preview. The options are Last 24 hours, Last 7 days, and Last 30 days: By default, Last 7 days will be selected.
   • Matched Messages: If you preview a rule, additional options will display to filter the messages in the preview list.
   • Matched Messages(default): Select this option to only display messages in your PhishER Inbox that match the condition of the rule.
   • Unmatched Messages: Select this option to only display messages in your PhishER Inbox that do not match the condition of the rule.
   • All Messages: Select this option to display all messages in your PhishER Inbox. The Matched column will indicate if the message matched (true) or did not match (false) the rule (click to view).

7. (Optional) If you would like to run this rule against all of the messages in the preview list, click the Apply Rule to Current Matches button (click to view).

Back to top

Editing Rules

To edit a custom rule, click on the Name or Description of the rule from the Rules List page to open the Rule Details page. If you would like to edit a system rule, create a new custom rule. Then, copy and paste the logic of the system rule into the Yara Rule Editor of the custom rule.

Back to top

Using Global Variables

From the Global Variables subtab of the Rules List page, you can create global variables or view the global variables you've created. If you use multiple rules with the same strings, you can use global variables to update all of these strings at once.

You can include global variables in rules by using the Basic Editor or the Advanced Editor to create strings containing global variables. If you edit a global variable, the rule will be automatically updated in all the rules that include the global variable.

To create a global variable, follow the steps below:

1. Log in to your PhishER platform.
2. From the sidebar on the left side of the page, select the Rules tab to open the Rules List page.
3. Navigate to the Global Variables subtab.
   
4. Click the New Variable button at the top-right corner of the page. When you click this button, the Create Global Variable page will open.
5. In the Name field, enter a name for the global variable.
   
6. In the Value field, enter a value for the global variable.
   
   Note: Global variables must meet the same requirements that apply to other variables and strings. The value cannot start with a numerical value, exceed 255 characters, or be one of the keywords listed in YARA's Writing YARA Rules documentation.
7. Click Save to save your global variable. The global variable will appear on the Rules List page under the Global Variables subtab.

On the Rules List page, you can view information about the global variable, such as when the global variable was created and last updated. You can also edit a global variable’s value by clicking on the variable’s name to open the Edit Global Variable screen. The name of an existing global variable can’t be changed. If you would like to delete a global variable, click the trashcan icon.

To learn how to create a rule using global variables, see our How Do I Create Strings and Conditions in the YARA Rule Basic Editor? article.

Back to top

Viewing the Rules List

The Rules List displays all of your rules and global variables. To learn more about the Rules List page, see the screenshot and list below.

1. Name: This column displays the name assigned to the rule.
2. Description: This column displays a description of the rule.
3. Rule Target: This column displays the part of a message the rule is run against. For example, the rule target could be the email header.
4. Status: This column displays the current state of the rule. A rule can be enabled or disabled. To change the status of a rule, click the toggle.
   Note: For a rule to run against messages in your PhishER Inbox, the rule must be enabled.
5. Updated At: This column displays the date and time when the rule was last updated.
6. Matched Count: This column displays the number of times the rule matched a message in your PhishER Inbox.
7. Tags: This column displays all of the tags attached to a message. Tags will only be attached to a message if the message matches the rule.
8. Filter by Status: Click this drop-down menu to select a filtered view of your enabled or disabled rules.

Back to top