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, you can write custom Agent rules to detect events that Datadog does not surface with the standard OOTB rules alone.

Policies

Create a policy

  1. Go to Policies.
  2. Click New Policy. You can also open an existing policy, click Actions, and clone it.
  3. Enter a name for the policy and click Create. The new policy is created, but it is not enabled or deployed.
  4. Click the policy to open it.
  5. In New Rule, add custom Agent rules to the policy. To create an Agent rule, see Create a custom Agent rule.
  6. Click Edit next to Deployed on 0 agents.
  7. Add tags to the policy to target specific infrastructure.
  8. 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

Policy pinning is supported in Agent version 7.71.0 and later. Previous Agents continue to receive the latest policy updates automatically.

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.
  2. Click a Datadog-managed policy.
  3. 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.
  4. Click Pin. To unpin the policy version, click the pin option again.

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

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.
  2. Open a policy and click Edit.
  3. 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

You can create a custom Agent rule and deploy it as part of a custom policy. Later, when defining a custom detection rule, 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.
  2. Create a policy or open an existing one.
  3. 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 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.
  4. Enter a Name and Description for the rule.
  5. In Expression, define the match using Datadog Security Language (SECL).
  6. (Optional) Add variables or actions that run when the rule matches an event. See Variables and actions.
  7. 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

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 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

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.

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.

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.
  2. 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.
  3. 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.
  4. 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.
  5. (Optional) Under Add a description, add a description for the deployment.
  6. Click Update Policy to start the rollout. Track the progress from the Deployments page.

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.
  2. In Actions, select Download Policy.

Next, use the following instructions to upload the policy file to each 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):

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

    • Or restart the Datadog Agent.

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

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

      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
    # [...]

    3. 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 -.

    Disable default Agent rules

    1. To disable an Agent rule, navigate to the Agent Configuration page and select the policy using the rule.
    2. In the policy, open the rule.
    3. Set the status to Inactive.
    4. Click Save Changes.

    Deleting a rule from Rules configuration removes it from all policies that included that rule.

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