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:

Option

Description

Event handler attributes

Event handler attributes such as name, description, and devices.

Filters

Filters are rules for event generation.

  • Select the log filters to limit the logs that trigger an event.
  • Group the logs by primary and secondary (optional) values to separate the events that are generated for different Group By values.
  • Set the number of occurrences within a time frame that triggers an event.
  • Configure event fields such as event status and severity.

Additional Info

Specify what to show in the Additional Info column. You can use the system default information or configure a custom information message.

Notifications

Configure notifications to be sent on event generation.

You can send alert notifications to a fabric connector, email address, SNMP community, or syslog server.

Screenshot of the creation of Event Handlers

To create a new event handler:
  1. Go to FortiSoC/Incidents & Events > Handlers > Event Handler List.
  2. In the toolbar, click Create New.
  3. Configure the settings as required and click OK.

    Field

    Description

    Status

    Enable or disable the event handler.

    Enabled event handlers have a Status of ON and show the icon in the Event Handler List. Disabled event handlers have a Status of OFF and show the icon in the Event Handler List.

    Name

    Add a name for the handler.

    Description

    Type a description of the event handler.

    Devices

    Select the devices to include.

    • All Devices.
    • Specify: To add devices, click the Add icon.
    • Local Device: Select if the event handler is for local FortiAnalyzer event logs. This option is only available in the root ADOM and is used to query FortiAnalyzer event logs.

      For Local Device, the Log Type must be Event Log and Log Subtype must be Any.

    Subnets

    Select All Subnets to include all subnets, or select Specify to choose which subnet(s) or subnet group(s) will be included or excluded from triggering events. See Subnets

    Pre-filters

    Click Add Pre-Filter to configure exclusion filters for all available log fields in the event handler.

    Filters

    Configure one or more filters for the handler. You can add multiple filters each with its own set of filter settings. You can enable or disable specific filters in an event handler.

    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 handler monitors. The available options depend on the platform type.

    This option is only available when Log Type is set to Event Log or Traffic Log.

    Group By

    Select how to group the events. Click Add beside the Group By field to add up to two additional Group By fields, to a maximum of three.

    Logs match

    Select All or Any of the following conditions.

    Log Field

    Select a log field to filter from the dropdown list.

    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 a match criteria from the dropdown list. The available options depend 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 depend 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.

    Add

    Add a Log Field to the filter.

    Remove

    Delete the filter.

    Generic Text Filter

    Enter a generic text filter.

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

    For more information on creating a generic text filter, see Using the Generic Text Filter in an event handler.

    Generate alert when at least n Exact/Distinct matches occurred over a period of n minutes

    Enter threshold values to generate alerts. Enter the number of matching Exact or Distinct events that must occur in the number of minutes to generate an alert.

    When Distinct is selected, you can further specify the alert criteria by indicating the field that must be distinct (for example, Source IP or Application).

    Event Type Override

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

    Event Message

    If you wish, enter a custom event message. The default message is the Group By value. You can use variables in the event message.

    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 entering it into the text field that appears in the Event Status dropdown.

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

    Event Severity

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

    Tags

    If you wish, enter custom tags. Tags can be used as a filter when using default or custom views.

    Indicators

    Optionally, enable indicators. You can configure the Log Field, Indicator Type, and Count for each indicator created in an event handler. 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 Events

    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. You can use the system default information or configure a custom information message.

    Use system default

    Select to use the system default message in the Additional Info column.

    Use custom message

    Type a custom message for the Additional Info column. A custom message can include variables and log field names. For more information, click the question mark icon.

    Notifications

    Configure alerts for the handler.

    Send Alert through Fabric Connectors

    Send an alert through one or more fabric connectors. Click the + button to add fabric connectors. For more information, see Fabric Connectors.

    Send Alert Email

    Send an alert by email. Specify email parameters including the mail server. For more information, see Mail Server.

    Send SNMP(...) Trap

    Select one or both checkboxes and specify an SNMP community or user from the dropdown list. Click the add icon to create a new SNMP community or user. For more information, see SNMP.

    Send Alert to Syslog Server

    Send an alert to the syslog server. Select a syslog server from the dropdown list. Click the add icon to create a new syslog server. For more information, see Syslog Server.

    Send Each Alert Separately

    Select to send each alert individually instead of in a group.

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:

Option

Description

Event handler attributes

Event handler attributes such as name, description, and devices.

Filters

Filters are rules for event generation.

  • Select the log filters to limit the logs that trigger an event.
  • Group the logs by primary and secondary (optional) values to separate the events that are generated for different Group By values.
  • Set the number of occurrences within a time frame that triggers an event.
  • Configure event fields such as event status and severity.

Additional Info

Specify what to show in the Additional Info column. You can use the system default information or configure a custom information message.

Notifications

Configure notifications to be sent on event generation.

You can send alert notifications to a fabric connector, email address, SNMP community, or syslog server.

Screenshot of the creation of Event Handlers

To create a new event handler:
  1. Go to FortiSoC/Incidents & Events > Handlers > Event Handler List.
  2. In the toolbar, click Create New.
  3. Configure the settings as required and click OK.

    Field

    Description

    Status

    Enable or disable the event handler.

    Enabled event handlers have a Status of ON and show the icon in the Event Handler List. Disabled event handlers have a Status of OFF and show the icon in the Event Handler List.

    Name

    Add a name for the handler.

    Description

    Type a description of the event handler.

    Devices

    Select the devices to include.

    • All Devices.
    • Specify: To add devices, click the Add icon.
    • Local Device: Select if the event handler is for local FortiAnalyzer event logs. This option is only available in the root ADOM and is used to query FortiAnalyzer event logs.

      For Local Device, the Log Type must be Event Log and Log Subtype must be Any.

    Subnets

    Select All Subnets to include all subnets, or select Specify to choose which subnet(s) or subnet group(s) will be included or excluded from triggering events. See Subnets

    Pre-filters

    Click Add Pre-Filter to configure exclusion filters for all available log fields in the event handler.

    Filters

    Configure one or more filters for the handler. You can add multiple filters each with its own set of filter settings. You can enable or disable specific filters in an event handler.

    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 handler monitors. The available options depend on the platform type.

    This option is only available when Log Type is set to Event Log or Traffic Log.

    Group By

    Select how to group the events. Click Add beside the Group By field to add up to two additional Group By fields, to a maximum of three.

    Logs match

    Select All or Any of the following conditions.

    Log Field

    Select a log field to filter from the dropdown list.

    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 a match criteria from the dropdown list. The available options depend 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 depend 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.

    Add

    Add a Log Field to the filter.

    Remove

    Delete the filter.

    Generic Text Filter

    Enter a generic text filter.

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

    For more information on creating a generic text filter, see Using the Generic Text Filter in an event handler.

    Generate alert when at least n Exact/Distinct matches occurred over a period of n minutes

    Enter threshold values to generate alerts. Enter the number of matching Exact or Distinct events that must occur in the number of minutes to generate an alert.

    When Distinct is selected, you can further specify the alert criteria by indicating the field that must be distinct (for example, Source IP or Application).

    Event Type Override

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

    Event Message

    If you wish, enter a custom event message. The default message is the Group By value. You can use variables in the event message.

    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 entering it into the text field that appears in the Event Status dropdown.

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

    Event Severity

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

    Tags

    If you wish, enter custom tags. Tags can be used as a filter when using default or custom views.

    Indicators

    Optionally, enable indicators. You can configure the Log Field, Indicator Type, and Count for each indicator created in an event handler. 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 Events

    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. You can use the system default information or configure a custom information message.

    Use system default

    Select to use the system default message in the Additional Info column.

    Use custom message

    Type a custom message for the Additional Info column. A custom message can include variables and log field names. For more information, click the question mark icon.

    Notifications

    Configure alerts for the handler.

    Send Alert through Fabric Connectors

    Send an alert through one or more fabric connectors. Click the + button to add fabric connectors. For more information, see Fabric Connectors.

    Send Alert Email

    Send an alert by email. Specify email parameters including the mail server. For more information, see Mail Server.

    Send SNMP(...) Trap

    Select one or both checkboxes and specify an SNMP community or user from the dropdown list. Click the add icon to create a new SNMP community or user. For more information, see SNMP.

    Send Alert to Syslog Server

    Send an alert to the syslog server. Select a syslog server from the dropdown list. Click the add icon to create a new syslog server. For more information, see Syslog Server.

    Send Each Alert Separately

    Select to send each alert individually instead of in a group.