---
title: Policy Management
description: >-
  Create, deploy, and scope Workload Protection policies, and write custom Agent
  rules for your infrastructure.
breadcrumbs: >-
  Docs > Datadog Security > Workload Protection > Detect and Monitor > Agent
  Rules > Policy Management
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Policy Management

Agent rules are **organized in policies**. A policy is a set of Agent rules that you deploy together and **scope to specific infrastructure** (hosts, clusters, and so on).

In addition to the out-of-the-box (OOTB) [default Agent rules](https://docs.datadoghq.com/security/workload_protection/detect_and_monitor/agent_rules.md#ootb-rules), you can write **custom Agent rules** to detect events that Datadog does not surface with the standard OOTB rules alone.

## Policies{% #policies %}

### Create a policy{% #create-a-policy %}

1. Go to [Policies](https://app.datadoghq.com/security/workload-protection/policies).
1. Click New Policy. You can also open an existing policy, click Actions, and clone it.
1. Enter a name for the policy and click Create. The new policy is created, but it is not enabled or deployed.
1. Click the policy to open it.
1. In New Rule, add custom Agent rules to the policy. To create an Agent rule, see Create a custom Agent rule.
1. Click Edit next to Deployed on 0 agents.
1. Add tags to the policy to target specific infrastructure.
1. To deploy the policy, toggle the switch next to Policy is disabled and confirm. This uses Remote Configuration, as detailed below in that page.

### Pin a Datadog-managed policy to its current version{% #pin-a-datadog-managed-policy-to-its-current-version %}

{% alert level="info" %}
Policy pinning is supported in Agent version 7.71.0 and later. Previous Agents continue to receive the latest policy updates automatically.
{% /alert %}

When Datadog-managed policies are updated by Datadog, they are automatically deployed to your infrastructure.

To control when a new policy version is deployed to your infrastructure, you can pin the policy to its current version. Pinning a policy version prevents policy updates from being automatically rolled out when Datadog releases a new policy version.

To pin a policy, do the following:

1. Go to [Policies](https://app.datadoghq.com/security/workload-protection/policies).
1. Click a Datadog-managed policy.
1. In Version, click the pin option. If your infrastructure is running Agents below version 7.71.0, an outdated agents warning appears. View and upgrade your Agent version in [Fleet Automation](https://app.datadoghq.com/fleet).
1. Click Pin. To unpin the policy version, click the pin option again.

### Conflicting rules{% #conflicting-rules %}

When two policies deployed to the same host contain the same rule with a different status (active and inactive), the rule will be considered active.

### Apply tags{% #apply-tags %}

Tags define where a policy applies, such as environments, clusters, or hosts. Add tags to a policy to limit its rules to part of your infrastructure.

1. Go to [Agent Configuration](https://app.datadoghq.com/security/configuration/workload/agent-rules).
1. Open a policy and click Edit.
1. Enter tags and click Apply. If the policy is enabled, the policy is applied to the tag targets.

When you add tags, Datadog displays how many agents the tags target as well the infrastructure running each agent. For example, `Tags match 144 agents`.

## Create a custom Agent rule{% #create-a-custom-agent-rule %}

You can create a custom Agent rule and deploy it as part of a custom policy. Later, when defining a custom [detection rule](https://docs.datadoghq.com/security/workload_protection/detect_and_monitor/detection_and_finding_rules/detection_rules.md), you reference the custom Agent rule and add expression parameters. Custom Agent rules are deployed to the Agent in a custom policy separate from the default policies. The custom policy contains only custom Agent rules.

1. Go to [Agent Configuration](https://app.datadoghq.com/security/configuration/workload/agent-rules).
1. Create a policy or open an existing one.
1. With the policy open, in Actions, select Manual rule creator to open the Agent rule editor. The same editor is also available from the [Agent rules](https://app.datadoghq.com/security/workload-protection/agent-rules) page in Datadog. To use the Assisted rule creator wizard instead—which walks you through both the Agent rule and the threat detection rule—see [Create the custom Agent and detection rules together](https://docs.datadoghq.com/security/workload_protection/detect_and_monitor/detection_and_finding_rules/detection_rules.md#create-the-custom-agent-and-detection-rules-together).
1. Enter a Name and Description for the rule.
1. In Expression, define the match using [Datadog Security Language (SECL)](https://docs.datadoghq.com/security/workload_protection/detect_and_monitor/agent_rules/secl_guide.md).
1. (Optional) Add variables or actions that run when the rule matches an event. See [Variables and actions](https://docs.datadoghq.com/security/workload_protection/detect_and_monitor/agent_rules/variables_and_actions.md).
1. Click Create Agent Rule. You are returned to the policy.

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.

## Enable and deploy policies{% #enable-and-deploy-policies %}

Enabled policies apply their rules to the infrastructure targets identified by their tags. Enabling a policy is the same as deploying it.

You can use **Remote Configuration** in the Datadog UI to automatically deploy the custom policy to the hosts designated by the policy tags (all hosts or a defined subset of hosts), or you can **manually deploy** the policy to the Agent on each host.

### Remote Configuration{% #remote-configuration %}

**Remote Configuration** is how Datadog automatically delivers policies to your agents. It uses a secure mechanism to guarantee that only signed and authenticated policies are pushed to your agents. To deploy a policy using remote configuration, follow the steps detailed in Create a policy.

#### Deployment strategies{% #deployment-strategies %}

To roll out a change to Agent rules or policies with Remote Configuration, you can choose between two strategies: deploy the change instantly to all your hosts, or stagger the deployment in steps using a managed deploy. Monitor deployments from the [Deployments page](https://app.datadoghq.com/security/workload-protection/deployments).

##### Deploy instantly{% #deploy-instantly %}

Deploy instantly sends the updated policy to all hosts in scope at the same time, without staged validation. This generally takes a few minutes, and is best when you want the change applied everywhere right away.

Select Deploy instantly, then click Update Policy. Track the progress from the [Deployments page](https://app.datadoghq.com/security/workload-protection/deployments).

##### Managed deployment{% #managed-deployment %}

A managed deployment rolls out your change in stages so you can validate it on a subset of hosts before it reaches your entire infrastructure.

1. When editing a policy or a rule, select Start a managed deployment. If the policy or rule was already rolled out with a managed deploy, select Start from your last deployment to reuse the last deployment's parameters. For a rule change, the reused parameters are those of the last deployment of the policy containing the rule.
1. Under Customize deployment roll-out plan, set the scope of the deployment, then configure up to 10 stages to roll out the change gradually. Define each stage By percentage of hosts in scope or By host tags.
1. Under Set up monitoring and delay time, select one or more monitors to check during the deployment. If a monitor alerts while the deployment is in progress, the rollout pauses. Then set the delay time to wait before continuing to the next stage.
1. Under Set deployment window, set the days, times, and timezone when the deployment can run. If the deployment runs past a window, it pauses and resumes in the next one.
1. (Optional) Under Add a description, add a description for the deployment.
1. Click Update Policy to start the rollout. Track the progress from the [Deployments page](https://app.datadoghq.com/security/workload-protection/deployments).

### Manual deployment{% #manual-deployment %}

For **manual deployment**, you install a policy file on each Agent yourself. You can build the policy and its rules in the Datadog UI and **download** the generated file. If you already know the policy syntax, author a `.policy` file by hand. Then upload or sync that file to every Agent where the policy should run, as described below.

1. On the Agent Configuration page, open a policy.
1. In Actions, select Download Policy.

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

{% tab title="Host" %}
Copy the `default.policy` file to the target host in the `/etc/datadog-agent/runtime-security.d` folder (that will contains all your `.policy` files). The file must have `read` and `write` access for the `root` user on the host.

To apply the changes, do **one** of the following:

- Reload runtime policies (no full Agent restart):

  ```bash
  sudo /opt/datadog-agent/embedded/bin/system-probe runtime policy reload
  ```

- Or restart the [Datadog Agent](https://docs.datadoghq.com/agent/configuration/agent-commands.md?tab=agentv6v7#restart-the-agent).

{% /tab %}

{% tab title="Helm" %}

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

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

   ```yaml
   securityAgent:
       # [...]
       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
       # [...]
   ```

1. 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 -`.

{% /tab %}

## Disable default Agent rules{% #disable-default-agent-rules %}

1. To disable an Agent rule, navigate to the [Agent Configuration](https://app.datadoghq.com/security/configuration/workload/agent-rules) page and select the policy using the rule.
1. In the policy, open the rule.
1. Set the status to Inactive.
1. Click Save Changes.

Deleting a rule from [Rules configuration](https://app.datadoghq.com/security/workload-protection/agent-rules) removes it from **all policies** that included that rule.

## RBAC for custom rule management{% #rbac-for-custom-rule-management %}

Here are some important [role and permissions](https://docs.datadoghq.com/account_management/rbac/permissions.md) to use for custom rules RBAC:

- The `security_monitoring_cws_agent_rules_actions` permission can be used to turn on and configure the [Automated response](https://docs.datadoghq.com/security/workload_protection/respond_and_report.md#automated-response) feature used to enable the blocking mode in the 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 Automated response 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.