Event Rules

Overview

With Application Security Monitoring (ASM) enabled, the Datadog tracing library actively monitors all web services and API requests for suspicious security activity.

An event rule specifies conditions on the incoming request to define what the library considers suspicious. The Datadog tracing library includes hundreds of out-of-the-box ASM event rules, which are used to display suspicious requests in the trace explorer and in the default signal rules.

You can add to the event rules without upgrading the tracing library.

Structure of an ASM event rule

An event rule is a JSON object composed of a category, a name, tags, and conditions. When a suspicious request is detected, tags from the rules are propagated onto the suspicious request, and can be used to build detection rules.

Conditions

Conditions define when the rule tags an incoming request. The conditions are composed of inputs and operators.

Inputs

An input represents which part of the request the operator is applied to. The following inputs are used in the event rules:

NameDescriptionExample
server.request.uri.rawThe full request URI received by the application servicehttps://my.api.com/users/1234/roles?clientId=234
server.request.path_paramsThe parsed path parameters (key/value map)userId => 1234
server.request.queryThe parsed query parameters (key/value map)clientId => 234
server.request.headers.no_cookiesThe incoming http requests headers, excluding the cookie header (key/value map)user-agent => Zgrab, referer => google.com
grpc.server.request.messageThe parsed gRPC message (key/value map)data.items[0] => value0, data.items[1] => value1
server.request.bodyThe parsed HTTP body (key/value map)data.items[0] => value0, data.items[1] => value1
server.response.statusThe http status code200

Operators

nameDescription
match_regexPerform regular expression match on the inputs
phrase_matchPerform a fast keyword list matching
is_xssSpecial operator to check for cross-site scripting (XSS) payloads
is_sqliSpecial operator to check for SQL injection (SQLI) payloads

Configure an ASM event rule in your service

  1. In Datadog, navigate to the Event Rules page under ASM Configuration.

  2. Click Download Configuration in the top right corner to download the configuration file, appsec-rules.json, to your local machine.

  3. Update the file to include the JSON definition of your new rule, following the specification above. For example:

        {
            "id": "id-123",
            "name": "My event rule",
            "tags": {
                "category": "attack_attempt",
                "crs_id": "920260",
                "type": "http_protocol_violation"
            },
            "conditions": [
                {
                    "operator": "match_regex",
                    "parameters": {
                        "inputs": [
                            {
                                "address": "server.request.uri.raw"
                            }
                        ],
                        "options": {
                            "case_sensitive": true,
                            "min_length": 6
                        },
                        "regex": "\\%u[fF]{2}[0-9a-fA-F]{2}"
                    }
                }
            ],
            "transformers": []
        },
       
  4. Using a utility such as SCP or FTP, copy the appsec-rules.json file to your application server, for example, /home/asm/appsec-rules.json.

  5. Following the instructions in the ASM Getting Started for adding application variables in your environment, add the DD_APPSEC_RULES environment variable to your service with the full path to the file:

    DD_APPSEC_RULES=/home/asm/appsec-rules.json
    
  6. Restart your service.

What to do next

Next, configure detection rules to create security signals based on those suspicious requests defined by the event rules you created. You can modify the provided out-of-the-box ASM detection rules or create new ones.

Further Reading