Creating Custom Detection Rules

Docs > Datadog Security > Cloud Security Management Threats > CSM Threats Detection Rules > Creating Custom Detection Rules

This topic explains how to create custom Datadog Agent and detection rules for CSM Threats.

In addition to the out of the box (OOTB) default Agent and detection rules, you can write custom Agent and detection rules. Custom rules help to detect events Datadog is not detecting with its OOTB rules.

RBAC for custom rule management

Here are some important role and permissions to use for custom rules RBAC:

The security_monitoring_cws_agent_rules_actions permission can be used to turn on and configure the Active Protection feature. Active Protection enables you to proactively block and terminate crypto mining threats identified by the Datadog Agent threat detection rules.
- To use the security_monitoring_cws_agent_rules_actions permission, a user with the Datadog Admin role must create a role containing the security_monitoring_cws_agent_rules_actions permission and then add only those users that manage Active Protection to this role.
The Datadog Standard role enables users to create/update a custom rule by default, as long as the operation does not change the protection settings on the rule.

Custom detection rules summary

Custom detection rules depend on Agent rules. They are composed of existing, deployed Agent rules and additional expression parameters.

There are two use cases:

Create a detection rule using an existing Agent rule: To create a threat detection rule that uses an existing Agent rule, you only need to create a threat detection rule that references the Agent rule and adds any additional expression parameters you need.
Create a threat detection rule using a new Agent rule: To detect an event that the current Agent rules do not support, you need to create a custom Agent rule to detect that event, and then create a custom threat detection rule that uses the custom Agent rule.

For more information, see CSM Threats Detection Rules.

You can create custom rules using these methods:

Simple: Use the Assisted rule creator to create the custom Agent and detection rules together.
- For steps on using the Assisted rule creator, see Create the custom Agent and detection rules together.
Advanced: Create custom Agent and detection rules individually by defining their threat detection expressions.
- For steps on this method, see Create a custom agent rule and Create a custom detection rule.

Create the custom Agent and detection rules together

The Assisted rule creator option helps you create the Agent and dependent detection rules together, and ensures that the Agent rule is referenced in the detection rules. Using this tool is faster than the advanced method of creating the Agent and detection rules separately.

As you define the rules using this tool, the threat expressions generated for these rules are displayed in the tool.

To use the simple rule creator:

In Agent Configuration or Threat Detection Rules, select New Rule, and then select Assisted rule creator.
Define the detection. To monitor your resource effectively, you have the following detection type options:
- To detect nonstandard and suspicious changes to files, select File integrity monitoring (FIM).
- To track and analyze system software processes for malicious behavior or policy violations, select Process activity monitoring.
- Enter the file/process names or paths to monitor.
Specify more conditions. Enter any arguments to add to the threat rule expression. For example, the argument foo is added as process.argv in ["foo"].
Set severity and notification lists.
- Select the severity for the signal generated when this threat is detected.
- Select notification lists to notify when a signal is generated.
Add the rule name and description.
Here’s an example of a new FIM rule, including the expressions generated for each rule.
Select Create N Rules.
In Generate Rules, select Confirm. The rules are generated.
Select Finish. The Agent Configuration page displays the new rules.
In Agent Configuration, select Deploy Agent Policy.

Create a custom Agent rule

You can create an individual custom Agent rule, deploy it as a new Agent policy, and reference it in a custom detection rule.

On the Agent Configuration page, select New Rule, and then select Manual rule creator.
Add a name and description for the rule.
In Expression, define the Agent expression using Datadog Security Language (SECL) syntax.
For example, to monitor for suspicious container clients:
```
exec.file.path in ["/usr/bin/docker", "/usr/local/bin/docker",
"/usr/bin/kubectl", "/usr/local/bin/kubectl"] && container.id != ""
```
Click Create Agent Rule. This automatically navigates you back to the Agent Configuration page.

After you create a custom Agent rule, the change is saved along with other pending rule updates. To apply the change to your environment, deploy the updated custom policy to the Agent.

Deploy the policy in your environment

Custom Agent rules are deployed to the Agent in a custom policy separate from the default policy. The custom policy contains custom Agent rules as well as default rules that have been disabled.

You can use Remote Configuration to automatically deploy the custom policy to your designated hosts (all hosts or a defined subset of hosts), or manually upload it to the Agent on each host.

Remote Configuration for custom rules is in private beta. Fill out this form to request access.

Remote Configuration

On the Agent Configuration page, click Deploy Agent Policy.
Select Remote Configuration.
Choose whether to Deploy to All Hosts or Deploy to a Subset of Hosts. To deploy the policy to a subset of hosts, specify the hosts by selecting one or more service tags.
Click Deploy.

Manual deployment

On the Agent Configuration page, click Deploy Agent Policy.
Select Manual.
Click Download Agent Policy, then click Done.

Next, use the following instructions to upload the policy file to each host.

Copy the default.policy file to the target host in the {$DD_AGENT}/runtime-security.d folder. The file must have read and write access for the dd-agent user on the host. This may require use of a utility such as SCP or FTP.

To apply the changes, restart the Datadog Agent.

Create a ConfigMap containing default.policy, for example, kubectl create configmap jdefaultpol --from-file=default.policy.

Add the ConfigMap (jdefaultpol) to values.yaml with datadog.securityAgent.runtime.policies.configMap:

securityAgent:
  compliance:
    # [...]
  runtime:
    # datadog.securityAgent.runtime.enabled
    # Set to true to enable Security Runtime Module
    enabled: true
    policies:
      # datadog.securityAgent.runtime.policies.configMap
      # Place custom policies here
      configMap: jdefaultpol
  syscallMonitor:
    # datadog.securityAgent.runtime.syscallMonitor.enabled
    # Set to true to enable Syscall monitoring.
    enabled: false

Upgrade the Helm chart with helm upgrade <RELEASENAME> -f values.yaml --set datadog.apiKey=<APIKEY> datadog/datadog.
Note: If you need to make further changes to default.policy, you can either use kubectl edit cm jdefaultpol or replace the configMap with kubectl create configmap jdefaultpol --from-file default.policy -o yaml --dry-run=client | kubectl replace -f -.
Restart the Datadog Agent.

Create a custom detection rule

After you upload the new default policy file to the Agent, navigate to the Threat Detection Rules page.

On the Threat Detection Rules page, select New Rule, and then select Manual rule creator.
Select a rule type:
1. In Detection rule types, select Workload Security.
2. Select a detection method such as Threshold or New Value.
Define search queries:
1. Configure a new CSM Threats rule. A rule can have multiple rule cases combined with Boolean logic, for example (||, &&). You can also set the counter, group by, and roll-up window.
- Enter a query so that a trigger is only generated when a value is met. You can also enter suppression queries in the Suppression Rules, so that a trigger is not generated when the specified values are met.
Set rule cases:
1. Set a rule case for the trigger and severity.
2. Define the logic for when this rule triggers a security signal. For example, a>0 means a security signal triggers as long as the rule condition set in the search query is met at least once in the sliding time window.
3. Select a severity to associate the rule with and select all relevant parties you want to notify.
Say what’s happening:
1. Name the rule and add the notification message in Markdown format. Use Notification variables to provide specific details about the signal by referencing its tags and event attributes. After the message, add multiple tags to give more context to the signals generated by your custom rule.
  Datadog recommends including a remediation [runbook][10] in the body. As noted in the template, use substitution variables to dynamically generate contextualized content at runtime.

Disable default Agent rules

To disable a default Agent rule, navigate to the Agent Configuration page and select the rule toggle. When you disable a default Agent rule, the change is saved along with other pending rule updates. To apply the change to your environment, deploy the updated custom policy to the Agent.