Customizing detection rules

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

You can view or customize Apigee Sense detection rules to ensure that you're catching only those requests that might be unwanted. Apigee Sense detection rules define patterns that represent possibly unwanted client requests.

For more on viewing the results of detection rules, see Getting started with the Apigee Sense console.

Tuning example

For example, you might have noticed in your detection reports that some unwanted requests conform to the Brute Guessor pattern, which reports a larger proportion of response errors during a 24-hour period. But you also notice that the pattern is catching requests that you want to allow through your API proxies.

By customizing the Brute Guessor pattern (following table), you can tune it to better allow requests you want and catch those you don't. The Brute Guessor pattern defines the conditions and values shown in the following table. If a set of requests meets these conditions over a 24-hour period, Apigee Sense reports that those requests conform to the Brute Guessor pattern.

Conditions Value
Minimum number of calls from IP 100
Minimum percent of errors threshold 90

There may be scenarios where your design may allow for > 90% of errors in a 24-hour period. In this case, due to the protection setting of the rule, genuine sources may be blocked. This feature allows you to change the condition values. In the previous example you might begin by changing condition values to the following:

Conditions Value
Minimum number of calls from IP 100
Minimum percent of errors threshold 95

The specific customizing changes you make will vary based on what your request data says about how valid clients are using your APIs. But you'll likely find that the process is iterative, in which you make incremental changes until you arrive at a useful rule definition.

Tuning detection iteratively

For those detection rules that need tuning, you might find it's best to take an incremental and iterative approach. Each iteration could take a day or so due to how the Apigee Sense detection and analysis cycle works. In that cycle, Apigee Sense stores metadata about client requests, analyzes that data in a batch, then presents the results for you to view in the Apigee Sense console.

For example, you might use the following process:

  1. Use the Apigee Sense console's detection reports to identify a detection rule that could use tuning, such as a rule that is detecting too many requests that are actually useful.
  2. Identify which of the rule's conditions need adjusting so that the percentage of unwanted requests it captures is higher.
  3. In the Apigee Sense console, edit the rule to make a modestly incremental change to the condition values you've identified.
  4. After an hour, use the detection reports to evaluate whether your change has had the effect you want.
  5. Iterate as needed until you have useful results.

Guidelines and best practices

As you customize detection rules, keep in mind the following.

  • A rule's conditions combine in a logical AND relationship. In other words, if there are three conditions, all three conditions must be met for requests to conform to the rule's pattern.
  • Some rule conditions define minimum thresholds, while others define maximum thresholds.
  • Tune rules to strike a balance between catching enough requests to identify unwanted traffic, but not so many that you catch useful traffic. As a best practice, err on the side of catching fewer requests to avoid capturing useful traffic.
  • Very small changes to condition values might not make a noticeable difference. Use your own judgement as to how great a change to make.

For more about patterns, conditions, and a time windows, see Taking action on suspicious activity.

Customizing a detection rule

Once you've identified a detection rule that could use tuning, use the following steps to view or customize a detection rule, or even to disable rules if you consider them unuseful. You'll also be able to see who last edited the rule.

  1. Open the New Edge experience.
  2. In the New Edge experience, click the Analyze menu, then click Sense.
  3. In the navigation bar, click Detection > Rules.
  4. On the Detection Rules page, locate the rule you want to view or customize.
  5. Hover your mouse over the rule's row in the list, then click the button at the far right end of the row. The following shows the edit button available for administrators. Note that you can also disable rules, causing Apigee Sense to stop evaluating requests to your APIs using that pattern.
  6. In the rule's dialog box, view or adjust condition values.
  7. Click Save.
  8. After an hour, examine analysis results in the Detection report to evaluate whether your changes have had the result you want.