Overview
App and API Protection (AAP) comes with a set of out-of-the-box detection rules which aim to catch attack attempts, vulnerabilities found by attacker, and business logic abuse that impact your production systems.
However, there are situations where you may want to customize a rule based on your environment or workload. For example, you may want to customize a detection rule that detects users performing sensitive actions from a geolocation where your business doesn’t operate.
Another example is customizing a rule to exclude an internal security scanner. AAP detects its activity as expected. However, you may not want to be notified of its regularly occurring scan.
In these situations, a custom detection rule can be created to exclude such events. This guide shows you how to create a custom detection rule for AAP.
Business logic abuse detection rule
AAP offers out of the box rules to detect business logic abuse (for example, resetting a password through brute force). Those rules require adding business logic information to traces.
Recent Datadog Tracing Libraries attempt to detect and send user login and signup events automatically without needing to modify the code. If needed, you can opt out of the automatic user activity event tracking.
You can filter the rules, and identify which business logic to start tracking. Additionally, you can use these rules as a blueprint to create custom rules based on your own business logic.
See the section below to see how to configure your rules.
Configuration
To customize an OOTB detection rule, you must first clone an existing rule. Navigate to your Detection Rules and select a rule. Scroll to the bottom of the rule and click the Clone Rule button. This now enables you to edit the existing rule.
Define an AAP query
Construct an AAP query using the same query syntax as in the AAP Trace Explorer. For example, create a query to monitor login successes from outside of the United States: @appsec.security_activity:business_logic.users.login.success -@actor.ip_details.country.iso_code:US.
Optionally, define a unique count and signal grouping. Count the number of unique values observed for an attribute in a given timeframe. The defined group-by generates a signal for each group-by value. Typically, the group-by is an entity (like user, IP, or service). The group-by is also used to join the queries together.
Use the preview section to see which AAP traces match the search query. You can also add additional queries with the Add Query button.
Joining queries
Joining queries to span a timeframe can increase the confidence or severity of the Security Signal. For example, to detect a successful attack, both successful and unsuccessful triggers can be correlated for a service.
Queries are correlated together by using a group by value. The group by value is typically an entity (for example, IP or Service), but can be any attribute.
For example, create opposing queries that search for the same business_logic.users.login.success activity, but append opposing HTTP path queries for successful and unsuccessful attempts:
Query 1: @appsec.security_activity:business_logic.users.login.success @actor.ip_details.country.iso_code:US.
Query 2: @appsec.security_activity:business_logic.users.login.success -@actor.ip_details.country.iso_code:US.
In this instance, the joined queries technically hold the same attribute value: the value must be the same for the case to be met. If a group by value doesn’t exist, the case will never be met. A Security Signal is generated for each unique group by value when a case is matched.
Exclude benign activity with suppression queries
In the Only generate a signal if there is a match field, you have the option to enter a query so that a trigger is only generated when a value is met.
In the This rule will not generate a signal if there is a match field, you have the option to enter suppression queries so that a trigger is not generated when the values are met. For example, if a service is triggering a signal, but the action is benign and you no longer want signals triggered from this service, create a query that excludes service.
Set a rule case
Trigger
Rule cases, such as successful login > 0, are evaluated as case statements. Thus, the first case to match generates the signal. Create one or multiple rule cases, and click on the grey area next to them to drag and manipulate their orderings.
A rule case contains logical operations (>, >=, &&, ||) to determine if a signal should be generated based on the event counts in the previously defined queries.
Note: The query label must precede the operator. For example, a > 3 is allowed; 3 < a is not allowed.
Provide a name for each rule case. This name is appended to the rule name when a signal is generated.
Severity and notification
In the Set severity to dropdown menu, select the appropriate severity level (INFO, LOW, MEDIUM, HIGH, CRITICAL).
In the Notify section, optionally, configure notification targets for each rule case.
You can also create notification rules to avoid manual edits to notification preferences for individual detection rules.
Time windows
An evaluation window is specified to match when at least one of the cases matches true. This is a sliding window and evaluates cases in real time.
After a signal is generated, the signal remains “open” if a case is matched at least once within the keep alive window. Each time a new event matches any of the cases, the last updated timestamp is updated for the signal.
A signal closes once the time exceeds the maximum signal duration, regardless of the query being matched. This time is calculated from the first seen timestamp.
Click Add Case to add additional cases.
Note: The evaluation window must be less than or equal to the keep alive and maximum signal duration.
Say what’s happening
Add a Rule name to configure the rule name that appears in the detection rules list view and the title of the Security Signal.
In the Rule message section, use notification variables and Markdown to customize the notifications sent when a signal is generated. Specifically, use template variables in the notification to inject dynamic context from triggered logs directly into a security signal and its associated notifications. See the Notification Variables documentation for more information and examples.
Use the Tag resulting signals dropdown menu to add tags to your signals. For example, attack:sql-injection-attempt.
Note: The tag security is special. This tag is used to classify the security signal. The recommended options are: attack, threat-intel, compliance, anomaly, and data-leak.
Further Reading
Additional helpful documentation, links, and articles:
