Fortinet black logo

Administration Guide

Creating a custom event handler

Creating a custom event handler

You can create a custom event handler from scratch or clone a predefined event handler and customize its settings. See Cloning event handlers.

Configuring an event handler includes defining the following main sections in the GUI:

Option

Description

Event handler attributes

The status, name, description, MITRE techniques, data selector, and automation stitch for the event handler.

Rules

The rules for event generation.

  1. Choose Your Logs: Start by selecting the device and log type that you want to monitor for events. Choose log fields to categorize logs into smaller groups.

  2. Refine Your Logs: Once logs are grouped, you can refine the data within each group by applying filters with other log fields. Logs that match the filters will be retained within each group.

  3. Define Event Conditions: Once you've organized and filtered the logs, set up criteria that enables the system to automatically initiate events when log records reoccur within each group.

Handler Settings

The notification profile for the event handler.

Screenshot of the creation of Event Handlers

To create a new event handler:
  1. Go to Incidents & Events > Handlers > Basic Handlers.
  2. In the toolbar, click Create New.

    The Add New Basic Event Handler pane displays.

  3. Configure the following options, and click OK to save the event handler.

    Option

    Description

    Status

    Enable or disable the event handler.

    Enabled event handlers show a icon in the Status column. Disabled event handlers show a icon in the Status column.

    Name

    Enter a name for the event handler.

    Description

    (Optional) Enter a description for the event handler.

    MITRE Domain

    If applicable, select the MITRE ATT&CK domain that the event handler will help to cover. For more information, see MITRE ATT&CK®.

    MITRE Tech ID

    Select the MITRE ATT&CK technique ID(s) that the event handler provides coverage for.

    Data Selector

    Select a data selector for the event handler.

    This selects devices, subnets, and filters used for the event handler. See Creating data selectors.

    Automation Stitch

    Enable or disable automation stitch.

    When enabled, FortiAnalyzer sends a notification to FortiGate when events are generated by the event handler. The events are available in the FortiAnalyzer GUI as well. For more information, see Using the Automation Stitch for event handlers.

    Rules

    Add New Rule

    Click to add a rule. The Add New Rule pane displays. Configure the options below, and then click OK to save the rule.

    You can add multiple rules to the event handler. Each rule has an OR relationship with other rules enabled in the event handler.

    Status

    Enable or disable the rule. If the rule is disabled, it will not be used to generate events.

    Name

    Enter a name for the rule.

    Event Severity

    Select the severity from the dropdown list: Critical, High, Medium, or Low.

    Choose Your Logs

    Log Device Type

    If you are in a Security Fabric ADOM, select the log device type from the dropdown list. If you are not in a Security Fabric ADOM, you cannot change the Log Device Type.

    The Fabric log device type can be used to generate alerts from SIEM logs when SIEM logs are available.

    Log Type

    Select the log type from the dropdown list.

    When Devices is set to Local Device, you cannot change the Log Type or Log Subtype.

    Log Subtype

    Select the category of event that this event handler monitors. The available options depend on the platform type.

    This option is only available when the Log Type has a subtype. For example, Event Log and Traffic Log have log subtypes which can be selected from the dropdown.

    Log Field

    Select the log fields for the system to categorize logs into smaller groups.

    For example, consider the scenario where the Log Field is set using Source IP (srcip). When log entries are recorded with source IPs such as 192.168.1.1, 192.168.1.2, and 192.168.1.3, the system will categorize these logs into distinct groups:

    • Group 1: Logs with the source IP 192.168.1.1

    • Group 2: Logs with the source IP 192.168.1.2

    • Group 3: Logs with the source IP 192.168.1.3

    This grouping mechanism allows analysis of log data based on the specified source IP addresses.

    Refine Your Logs

    Log Filters

    Select All Filters or Any One of the Filters.

    Configure the filter(s):

    • Log Field: Select a log field from the dropdown.
      After the log device and log type are selected, the Log Field dropdown list will only include log fields that belong to the specified log type. For example, the Botnet IP log field is available when the Log Type is DNS, but not available when the Log Type is Event Log.

    • Match Criteria: Select an operator from the dropdown. The available options depends on the selected log field.
      Some log fields, such as Source Port, will provide a variety of operators in the dropdown list, such as Equal To, Not Equal To, Greater Than or Equal To, Less Than or Equal To, Greater Than, and Less Than.
      Other log fields, such as Log Description, will be limited to Equal To and Not Equal To.

    • Value: Select a value from the dropdown list or enter a value in the text box. The available options depends on the selected log field.
      If there is no dropdown list provided by FortiAnalyzer, you must manually enter a value to find in the raw log.
      If a dropdown list is provided, you can select a value from the list. For some log fields, such as Level, the dropdown list also allows you to enter a custom value. If there is no textbox to enter a custom value in the dropdown list, you must use the Generic Text Filter instead.

    In the Action column, click plus (+) to insert a new filter below. You can insert multiple filters. To delete a filter, click the x next to the filter.

    Log Filter by Text

    Enter a generic text filter. See Using the Generic Text Filter.

    For information on text format, hover the cursor over the help icon. The operator ~ means contains and !~ means does not contain.

    Define Event Conditions

    Trigger an event when:

    Select the radio button for one of the following options and configure the criteria:

    • A group contains <integer> or more log occurences

    • Within a group, the log field <log field> has <integer> or more unique values

      • Click the toggle icon to change to "[...] has fewer than <integer> unique values"

    • The sum of <measure> is greater than or equal to <integer>

    Note

    The "sum" option is used for data exfiltration detection. This option is only supported in Fabric ADOMs.

    Additionally, configure the following in relation to your selection:

    • All logs were generated within <integer> minutes

    Advanced Settings

    Event Type Override

    Specify a custom event type, or leave this field blank to use the default value.

    Event Message

    (Optional) Enter a custom event message.

    By default, Group by key-value pair(s) will be displayed as the event message in Event Monitor.

    Examples:

    • Virus:JS/Runfile.B!tr

    • Endpoint:172.17.58.118 Virus:BlackMoon

    You can customize event messages by using Group By variables: $groupby1 and $groupby2

    Examples:

    • Virus $groupby1 found in traffic

    • Endpoint $groupby1 infected with virus $groupby2

    Event Status

    Select Allow FortiAnalyzer to choose or select a status from the dropdown list: Unhandled, Mitigated, Contained, (Blank). You can use a custom event status by clicking the plus (+) that appears in the Event Status dropdown.

    Event statuses, including custom statuses, are displayed in the Event Status column in the Event Monitor.

    Tags

    (Optional) Enter custom tags.

    Tags can be used as a filter when using default or custom views.

    Indicators

    (Optional) Add indicators by clicking the plus (+). You can configure the Log Field, Indicator Type, and Count for each indicator created in an event handler. Use the buttons in the Action column to add (+) or remove (x) indicators. Up to five indicators can be created.

    When Indicators is selected in Event Monitor > Display Options, the Indicators column displays indicator types for detected events. You can see additional details when clicking on an indicator. See Event Monitor

    If an incident is raised from an event that includes indicators, they can be viewed in the Indicators tab of the incident analysis page. See Analyzing an incident.

    Additional Info

    Specify what to show in the Additional Info column of the Event Monitor.

    Select Use system default or Use custom message. A custom message can include variables and log field names. For more information, hover over the help icon.

    Handler Settings

    Notifications

    Select a notification profile for the event handler. See Creating notification profiles.

Creating a custom event handler

You can create a custom event handler from scratch or clone a predefined event handler and customize its settings. See Cloning event handlers.

Configuring an event handler includes defining the following main sections in the GUI:

Option

Description

Event handler attributes

The status, name, description, MITRE techniques, data selector, and automation stitch for the event handler.

Rules

The rules for event generation.

  1. Choose Your Logs: Start by selecting the device and log type that you want to monitor for events. Choose log fields to categorize logs into smaller groups.

  2. Refine Your Logs: Once logs are grouped, you can refine the data within each group by applying filters with other log fields. Logs that match the filters will be retained within each group.

  3. Define Event Conditions: Once you've organized and filtered the logs, set up criteria that enables the system to automatically initiate events when log records reoccur within each group.

Handler Settings

The notification profile for the event handler.

Screenshot of the creation of Event Handlers

To create a new event handler:
  1. Go to Incidents & Events > Handlers > Basic Handlers.
  2. In the toolbar, click Create New.

    The Add New Basic Event Handler pane displays.

  3. Configure the following options, and click OK to save the event handler.

    Option

    Description

    Status

    Enable or disable the event handler.

    Enabled event handlers show a icon in the Status column. Disabled event handlers show a icon in the Status column.

    Name

    Enter a name for the event handler.

    Description

    (Optional) Enter a description for the event handler.

    MITRE Domain

    If applicable, select the MITRE ATT&CK domain that the event handler will help to cover. For more information, see MITRE ATT&CK®.

    MITRE Tech ID

    Select the MITRE ATT&CK technique ID(s) that the event handler provides coverage for.

    Data Selector

    Select a data selector for the event handler.

    This selects devices, subnets, and filters used for the event handler. See Creating data selectors.

    Automation Stitch

    Enable or disable automation stitch.

    When enabled, FortiAnalyzer sends a notification to FortiGate when events are generated by the event handler. The events are available in the FortiAnalyzer GUI as well. For more information, see Using the Automation Stitch for event handlers.

    Rules

    Add New Rule

    Click to add a rule. The Add New Rule pane displays. Configure the options below, and then click OK to save the rule.

    You can add multiple rules to the event handler. Each rule has an OR relationship with other rules enabled in the event handler.

    Status

    Enable or disable the rule. If the rule is disabled, it will not be used to generate events.

    Name

    Enter a name for the rule.

    Event Severity

    Select the severity from the dropdown list: Critical, High, Medium, or Low.

    Choose Your Logs

    Log Device Type

    If you are in a Security Fabric ADOM, select the log device type from the dropdown list. If you are not in a Security Fabric ADOM, you cannot change the Log Device Type.

    The Fabric log device type can be used to generate alerts from SIEM logs when SIEM logs are available.

    Log Type

    Select the log type from the dropdown list.

    When Devices is set to Local Device, you cannot change the Log Type or Log Subtype.

    Log Subtype

    Select the category of event that this event handler monitors. The available options depend on the platform type.

    This option is only available when the Log Type has a subtype. For example, Event Log and Traffic Log have log subtypes which can be selected from the dropdown.

    Log Field

    Select the log fields for the system to categorize logs into smaller groups.

    For example, consider the scenario where the Log Field is set using Source IP (srcip). When log entries are recorded with source IPs such as 192.168.1.1, 192.168.1.2, and 192.168.1.3, the system will categorize these logs into distinct groups:

    • Group 1: Logs with the source IP 192.168.1.1

    • Group 2: Logs with the source IP 192.168.1.2

    • Group 3: Logs with the source IP 192.168.1.3

    This grouping mechanism allows analysis of log data based on the specified source IP addresses.

    Refine Your Logs

    Log Filters

    Select All Filters or Any One of the Filters.

    Configure the filter(s):

    • Log Field: Select a log field from the dropdown.
      After the log device and log type are selected, the Log Field dropdown list will only include log fields that belong to the specified log type. For example, the Botnet IP log field is available when the Log Type is DNS, but not available when the Log Type is Event Log.

    • Match Criteria: Select an operator from the dropdown. The available options depends on the selected log field.
      Some log fields, such as Source Port, will provide a variety of operators in the dropdown list, such as Equal To, Not Equal To, Greater Than or Equal To, Less Than or Equal To, Greater Than, and Less Than.
      Other log fields, such as Log Description, will be limited to Equal To and Not Equal To.

    • Value: Select a value from the dropdown list or enter a value in the text box. The available options depends on the selected log field.
      If there is no dropdown list provided by FortiAnalyzer, you must manually enter a value to find in the raw log.
      If a dropdown list is provided, you can select a value from the list. For some log fields, such as Level, the dropdown list also allows you to enter a custom value. If there is no textbox to enter a custom value in the dropdown list, you must use the Generic Text Filter instead.

    In the Action column, click plus (+) to insert a new filter below. You can insert multiple filters. To delete a filter, click the x next to the filter.

    Log Filter by Text

    Enter a generic text filter. See Using the Generic Text Filter.

    For information on text format, hover the cursor over the help icon. The operator ~ means contains and !~ means does not contain.

    Define Event Conditions

    Trigger an event when:

    Select the radio button for one of the following options and configure the criteria:

    • A group contains <integer> or more log occurences

    • Within a group, the log field <log field> has <integer> or more unique values

      • Click the toggle icon to change to "[...] has fewer than <integer> unique values"

    • The sum of <measure> is greater than or equal to <integer>

    Note

    The "sum" option is used for data exfiltration detection. This option is only supported in Fabric ADOMs.

    Additionally, configure the following in relation to your selection:

    • All logs were generated within <integer> minutes

    Advanced Settings

    Event Type Override

    Specify a custom event type, or leave this field blank to use the default value.

    Event Message

    (Optional) Enter a custom event message.

    By default, Group by key-value pair(s) will be displayed as the event message in Event Monitor.

    Examples:

    • Virus:JS/Runfile.B!tr

    • Endpoint:172.17.58.118 Virus:BlackMoon

    You can customize event messages by using Group By variables: $groupby1 and $groupby2

    Examples:

    • Virus $groupby1 found in traffic

    • Endpoint $groupby1 infected with virus $groupby2

    Event Status

    Select Allow FortiAnalyzer to choose or select a status from the dropdown list: Unhandled, Mitigated, Contained, (Blank). You can use a custom event status by clicking the plus (+) that appears in the Event Status dropdown.

    Event statuses, including custom statuses, are displayed in the Event Status column in the Event Monitor.

    Tags

    (Optional) Enter custom tags.

    Tags can be used as a filter when using default or custom views.

    Indicators

    (Optional) Add indicators by clicking the plus (+). You can configure the Log Field, Indicator Type, and Count for each indicator created in an event handler. Use the buttons in the Action column to add (+) or remove (x) indicators. Up to five indicators can be created.

    When Indicators is selected in Event Monitor > Display Options, the Indicators column displays indicator types for detected events. You can see additional details when clicking on an indicator. See Event Monitor

    If an incident is raised from an event that includes indicators, they can be viewed in the Indicators tab of the incident analysis page. See Analyzing an incident.

    Additional Info

    Specify what to show in the Additional Info column of the Event Monitor.

    Select Use system default or Use custom message. A custom message can include variables and log field names. For more information, hover over the help icon.

    Handler Settings

    Notifications

    Select a notification profile for the event handler. See Creating notification profiles.