Skip to main content
Sumo Logic

Write a Match Rule

Learn how to write a match rule.

This topic has information about the Match rules and how to create them in the CSE UI.

About Match rules

A Match rule is the simplest type of CSE rule. Each time a single Record matches the rule expression, a Signal is fired. 

A Match rule doesn’t allow you to define other conditions for Signal, like requiring multiple Records to match the rule expression, or looking for events of the different types within a timespan.

Here’s an example of the rule expression for a Match rule:

metadata_vendor = 'Amazon AWS' AND metadata_product = 'CloudTrail' AND metadata_deviceEventId = 'AwsApiCall-CreateUserPoolClient'

This rule fires a Signal each time a UserPoolClient, which has permission to call unauthenticated API operations, is created.

Create a Match rule

  1. Choose Rules from the Content menu.
  2. On the Create a Rule page, click Create in the Match card. 
    select-rule-type.png
  3. In the rules editor:
    1. Name. Enter a name for the rule. 
    2. Enabled. By default the rule will be enabled. It's good practice to use the slider to disable the rule so that it won’t be applied to incoming Records until you’ve tested it.   

      match.png

Configure “If Triggered” settings

In the When a Record matches the expression area, enter a rule expression, a boolean expression that when “true”, causes the rule to fire. For a Match rule, if a single Record matches the rule expression, the rule will fire a Signal. A rule expression can:

  • Use any of the functions supported by the CSE Rules Syntax.
  • Reference selected fields in the CSE schema.  You can click the help icon (the question mark) above the expression field to expand the field template guide, which contains a list of all the fields that CSE can normalize to v3 of the CSE Schema. Note that the existence of a field in the guide doesn't mean that your ingested Records necessary include that field.​​​​​

For more information see, About Rule Expressions in the About CSE Rules topic.

Test your rule expression

After creating a rule expression, you can test it against existing Records in CSE. 

  1. Click Test Rule above the rule expression. 
  2. The If Triggered section expands, and CSE searches for Records that match the rule expression. If there are no matching Records, you'll see a There aren't any matches for the expression message.
  3. If no matches were returned, try changing the time range. 

Configure “Then Create a Signal” settings

  1. On Entity. Select the Entity field—an IP address, MAC address, hostname, or username—in the Record that the resulting Signal should be associated with. (In CSE, an Insight is a set of Signals with the same Entity field.) Select a value from the pull-down list. 
  2. using the name. Define the name for Signals fired by the rule. You can enter text, and include Record fields from the custom token list. Including Record field values in the Signal name can make it more meaningful.
  3. with the summary.
  4. with the description. Define the description for the Signal the same way you did the Signal name, using text and Record fields. The Signal description should be a good indication of what the rule looks for.
  5. with a severity of. Severity is an estimate of the criticality of the detected activity, from 1 (lowest) to 10 (highest). There are several ways to specify Severity.
    • Constant. If you want every Signal that the rule fires to have the same severity, choose Constant, and select a severity level.
      constant-severity.png
    • Dynamic. Choose Dynamic if you want to base the severity level on a value of a field in the Record. Use the down arrows to display a list of fields, and select one. If you want the severity to be exactly the value of the field, you’re done. If you want to assign a different severity value based on the value of the Record field you selected, click Configure Mappings and see the instructions below.
      dynamic-severity.png
    • Dynamic with mappings. On the popup that appears: 
      • Default Signal Severity. Enter or select a default severity to assign if the selected Record field does not contain a value.
      • Record Value. Enter a value that the selected Record field supports.
      • Signal Severity. Enter a value, from 0 to 10, inclusive.
      • The Record Value and Signal Severity fields refresh. Continue adding field and severity values until you’re done.
        dynamic-rule-mappings.png
  6. with tags. If desired, you can add metadata tags to your rule. Tags are useful for adding context to items like Rules, Insights, Signals, Entities. You can also search for and filter items by tag. For more information, see Using Tags with Insights, Signals, Entities, and Rules.

Save as prototype

If you are not sure that your rule is ready for prime time, you can save it as a prototype. A prototype rule generates Signals, but those Signals won't contribute to Insights. (Signals generated by a prototype rule do not increment the rule's On Entity entity's Activity Score.) Running the rule as a prototype for a while allows you to determine whether the rule is too noisy and fires too many Signals.

To make the rule a prototype, click the box next to Save this rule as a prototype. When you are satisfied with the rule's behavior you can uncheck the box.