For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/api/latest/csm-threats/create-a-workload-protection-agent-rule-us1-fed.md. A documentation index is available at /llms.txt.

Create a Workload Protection agent rule (US1-FED)

POST https://api.ap1.datadoghq.com/api/v2/security_monitoring/cloud_workload_security/agent_ruleshttps://api.ap2.datadoghq.com/api/v2/security_monitoring/cloud_workload_security/agent_ruleshttps://api.datadoghq.eu/api/v2/security_monitoring/cloud_workload_security/agent_ruleshttps://api.ddog-gov.com/api/v2/security_monitoring/cloud_workload_security/agent_ruleshttps://api.us2.ddog-gov.com/api/v2/security_monitoring/cloud_workload_security/agent_ruleshttps://api.uk1.datadoghq.com/api/v2/security_monitoring/cloud_workload_security/agent_ruleshttps://api.datadoghq.com/api/v2/security_monitoring/cloud_workload_security/agent_ruleshttps://api.us3.datadoghq.com/api/v2/security_monitoring/cloud_workload_security/agent_ruleshttps://api.us5.datadoghq.com/api/v2/security_monitoring/cloud_workload_security/agent_rules

Overview

Create a new agent rule with the given parameters.

Note: This endpoint should only be used for the Government (US1-FED) site.

This endpoint requires the security_monitoring_cws_agent_rules_write permission.

Request

Body Data (required)

The definition of the new agent rule

Expand All

Field

Type

Description

data [required]

object

Object for a single Agent rule

attributes [required]

object

Create a new Cloud Workload Security Agent rule.

actions

[object]

The array of actions the rule can perform if triggered

coredump

object

The core dump action applied on the process matching the rule.

dentry

boolean

Whether the directory entry information is included in the core dump.

mount

boolean

Whether the mount information is included in the core dump.

no_compression

boolean

Whether the core dump is left uncompressed.

process

boolean

Whether the process memory is included in the core dump.

disabled

boolean

Whether the action is disabled

filter

string

SECL expression used to target the container to apply the action on

hash

object

Hash file specified by the field attribute

field

string

The field of the hash action

max_file_size

int64

The maximum size of the files to hash, in bytes.

kill

object

Kill system call applied on the container matching the rule

disable_container_disarmer

boolean

Whether the automatic container safeguard of the kill action is disabled.

disable_executable_disarmer

boolean

Whether the automatic executable safeguard of the kill action is disabled.

scope

string

The scope of the kill action.

signal

string

Supported signals for the kill system call

log

object

The log action applied when the rule is triggered.

level

string

The level of the log action.

message

string

The message of the log action.

metadata

object

The metadata action applied on the scope matching the rule

image_tag

string

The image tag of the metadata action

service

string

The service of the metadata action

short_image

string

The short image of the metadata action

network_filter

object

The network filter action applied on the network traffic matching the rule.

filter

string

The filter expression of the network filter action.

policy

string

The policy of the network filter action.

scope

string

The scope of the network filter action.

set

object

The set action applied on the scope matching the rule

append

boolean

Whether the value should be appended to the field.

default_value

string

The default value of the set action

expression

string

The expression of the set action.

field

string

The field of the set action

inherited

boolean

Whether the value should be inherited.

name

string

The name of the set action

private

boolean

Whether the value of the set action is private.

scope

string

The scope of the set action.

scope_field

string

The scope field of the set action.

size

int64

The size of the set action.

ttl

int64

The time to live of the set action.

value

 <oneOf>

The value of the set action

Object 1

string

Object 2

int32

Object 3

boolean

agent_version

string

Constrain the rule to specific versions of the Datadog Agent.

blocking

[string]

The blocking policies that the rule belongs to.

description

string

The description of the Agent rule.

disabled

[string]

The disabled policies that the rule belongs to.

enabled

boolean

Whether the Agent rule is enabled.

expression [required]

string

The SECL expression of the Agent rule.

filters

[string]

The platforms the Agent rule is supported on.

monitoring

[string]

The monitoring policies that the rule belongs to.

name [required]

string

The name of the Agent rule.

policy_id

string

The ID of the policy where the Agent rule is saved.

product_tags

[string]

The list of product tags associated with the rule.

silent

boolean

Whether the rule is silent.

type [required]

enum

The type of the resource, must always be agent_rule Allowed enum values: agent_rule

default: agent_rule

{
  "data": {
    "attributes": {
      "description": "My Agent rule",
      "enabled": true,
      "expression": "exec.file.name == \"sh\"",
      "filters": [],
      "name": "examplecsmthreat"
    },
    "type": "agent_rule"
  }
}

Response

OK

Response object that includes an Agent rule

Expand All

Field

Type

Description

data

object

Object for a single Agent rule

attributes

object

A Cloud Workload Security Agent rule returned by the API

actions

[object]

The array of actions the rule can perform if triggered

coredump

object

The core dump action applied on the process matching the rule.

dentry

boolean

Whether the directory entry information is included in the core dump.

mount

boolean

Whether the mount information is included in the core dump.

no_compression

boolean

Whether the core dump is left uncompressed.

process

boolean

Whether the process memory is included in the core dump.

disabled

boolean

Whether the action is disabled

filter

string

SECL expression used to target the container to apply the action on

hash

object

Hash file specified by the field attribute

field

string

The field of the hash action

max_file_size

int64

The maximum size of the files to hash, in bytes.

kill

object

Kill system call applied on the container matching the rule

disable_container_disarmer

boolean

Whether the automatic container safeguard of the kill action is disabled.

disable_executable_disarmer

boolean

Whether the automatic executable safeguard of the kill action is disabled.

scope

string

The scope of the kill action.

signal

string

Supported signals for the kill system call

log

object

The log action applied when the rule is triggered.

level

string

The level of the log action.

message

string

The message of the log action.

metadata

object

The metadata action applied on the scope matching the rule

image_tag

string

The image tag of the metadata action

service

string

The service of the metadata action

short_image

string

The short image of the metadata action

network_filter

object

The network filter action applied on the network traffic matching the rule.

filter

string

The filter expression of the network filter action.

policy

string

The policy of the network filter action.

scope

string

The scope of the network filter action.

set

object

The set action applied on the scope matching the rule

append

boolean

Whether the value should be appended to the field.

default_value

string

The default value of the set action

expression

string

The expression of the set action.

field

string

The field of the set action

inherited

boolean

Whether the value should be inherited.

name

string

The name of the set action

private

boolean

Whether the value of the set action is private.

scope

string

The scope of the set action.

scope_field

string

The scope field of the set action.

size

int64

The size of the set action.

ttl

int64

The time to live of the set action.

value

 <oneOf>

The value of the set action

Object 1

string

Object 2

int32

Object 3

boolean

agentConstraint

string

The version of the Agent

agent_version

string

The version constraint of the Datadog Agent the rule applies to

blocking

[string]

The blocking policies that the rule belongs to

category

string

The category of the Agent rule

creationAuthorUuId

string

The ID of the user who created the rule

creationDate

int64

When the Agent rule was created, timestamp in milliseconds

creator

object

The attributes of the user who created the Agent rule

handle

string

The handle of the user

name

string

The name of the user

defaultRule

boolean

Whether the rule is included by default

description

string

The description of the Agent rule

disabled

[string]

The disabled policies that the rule belongs to

enabled

boolean

Whether the Agent rule is enabled

every

int64

The rate limiting duration of the Agent rule, in nanoseconds

expression

string

The SECL expression of the Agent rule

filters

[string]

The platforms the Agent rule is supported on

group_id

string

The group of rules the Agent rule belongs to

monitoring

[string]

The monitoring policies that the rule belongs to

name

string

The name of the Agent rule

product_tags

[string]

The list of product tags associated with the rule

silent

boolean

Whether the rule is silent.

updateAuthorUuId

string

The ID of the user who updated the rule

updateDate

int64

Timestamp in milliseconds when the Agent rule was last updated

updatedAt

int64

When the Agent rule was last updated, timestamp in milliseconds

updater

object

The attributes of the user who last updated the Agent rule

handle

string

The handle of the user

name

string

The name of the user

version

int64

The version of the Agent rule

id

string

The ID of the Agent rule

type

enum

The type of the resource, must always be agent_rule Allowed enum values: agent_rule

default: agent_rule

{
  "data": {
    "attributes": {
      "actions": [
        {
          "coredump": {
            "dentry": false,
            "mount": false,
            "no_compression": false,
            "process": false
          },
          "disabled": false,
          "filter": "string",
          "hash": {
            "field": "string",
            "max_file_size": "integer"
          },
          "kill": {
            "disable_container_disarmer": false,
            "disable_executable_disarmer": false,
            "scope": "string",
            "signal": "string"
          },
          "log": {
            "level": "string",
            "message": "string"
          },
          "metadata": {
            "image_tag": "string",
            "service": "string",
            "short_image": "string"
          },
          "network_filter": {
            "filter": "string",
            "policy": "string",
            "scope": "string"
          },
          "set": {
            "append": false,
            "default_value": "string",
            "expression": "string",
            "field": "string",
            "inherited": false,
            "name": "string",
            "private": false,
            "scope": "string",
            "scope_field": "string",
            "size": "integer",
            "ttl": "integer",
            "value": {
              "type": "undefined"
            }
          }
        }
      ],
      "agentConstraint": "string",
      "agent_version": ">=7.62",
      "blocking": [],
      "category": "Process Activity",
      "creationAuthorUuId": "e51c9744-d158-11ec-ad23-da7ad0900002",
      "creationDate": 1624366480320,
      "creator": {
        "handle": "datadog.user@example.com",
        "name": "Datadog User"
      },
      "defaultRule": false,
      "description": "My Agent rule",
      "disabled": [],
      "enabled": true,
      "every": 60000000000,
      "expression": "exec.file.name == \"sh\"",
      "filters": [],
      "group_id": "group_id",
      "monitoring": [],
      "name": "my_agent_rule",
      "product_tags": [],
      "silent": false,
      "updateAuthorUuId": "e51c9744-d158-11ec-ad23-da7ad0900002",
      "updateDate": 1624366480320,
      "updatedAt": 1624366480320,
      "updater": {
        "handle": "datadog.user@example.com",
        "name": "Datadog User"
      },
      "version": 23
    },
    "id": "3dd-0uc-h1s",
    "type": "agent_rule"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Authorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          ## default
# 

# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/security_monitoring/cloud_workload_security/agent_rules" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "description": "My Agent rule", "enabled": true, "expression": "exec.file.name == \"sh\"", "name": "my_agent_rule" }, "type": "agent_rule" } } EOF
// Create a Workload Protection agent rule (US1-FED) returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	body := datadogV2.CloudWorkloadSecurityAgentRuleCreateRequest{
		Data: datadogV2.CloudWorkloadSecurityAgentRuleCreateData{
			Attributes: datadogV2.CloudWorkloadSecurityAgentRuleCreateAttributes{
				Description: datadog.PtrString("My Agent rule"),
				Enabled:     datadog.PtrBool(true),
				Expression:  `exec.file.name == "sh"`,
				Filters:     []string{},
				Name:        "examplecsmthreat",
			},
			Type: datadogV2.CLOUDWORKLOADSECURITYAGENTRULETYPE_AGENT_RULE,
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN"))
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewCSMThreatsApi(apiClient)
	resp, r, err := api.CreateCloudWorkloadSecurityAgentRule(ctx, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `CSMThreatsApi.CreateCloudWorkloadSecurityAgentRule`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `CSMThreatsApi.CreateCloudWorkloadSecurityAgentRule`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" go run "main.go"
// Create a Workload Protection agent rule (US1-FED) returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.CsmThreatsApi;
import com.datadog.api.client.v2.model.CloudWorkloadSecurityAgentRuleCreateAttributes;
import com.datadog.api.client.v2.model.CloudWorkloadSecurityAgentRuleCreateData;
import com.datadog.api.client.v2.model.CloudWorkloadSecurityAgentRuleCreateRequest;
import com.datadog.api.client.v2.model.CloudWorkloadSecurityAgentRuleResponse;
import com.datadog.api.client.v2.model.CloudWorkloadSecurityAgentRuleType;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));
    CsmThreatsApi apiInstance = new CsmThreatsApi(defaultClient);

    CloudWorkloadSecurityAgentRuleCreateRequest body =
        new CloudWorkloadSecurityAgentRuleCreateRequest()
            .data(
                new CloudWorkloadSecurityAgentRuleCreateData()
                    .attributes(
                        new CloudWorkloadSecurityAgentRuleCreateAttributes()
                            .description("My Agent rule")
                            .enabled(true)
                            .expression("""
exec.file.name == "sh"
""")
                            .name("examplecsmthreat"))
                    .type(CloudWorkloadSecurityAgentRuleType.AGENT_RULE));

    try {
      CloudWorkloadSecurityAgentRuleResponse result =
          apiInstance.createCloudWorkloadSecurityAgentRule(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println(
          "Exception when calling CsmThreatsApi#createCloudWorkloadSecurityAgentRule");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" java "Example.java"
"""
Create a Workload Protection agent rule (US1-FED) returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.csm_threats_api import CSMThreatsApi
from datadog_api_client.v2.model.cloud_workload_security_agent_rule_create_attributes import (
    CloudWorkloadSecurityAgentRuleCreateAttributes,
)
from datadog_api_client.v2.model.cloud_workload_security_agent_rule_create_data import (
    CloudWorkloadSecurityAgentRuleCreateData,
)
from datadog_api_client.v2.model.cloud_workload_security_agent_rule_create_request import (
    CloudWorkloadSecurityAgentRuleCreateRequest,
)
from datadog_api_client.v2.model.cloud_workload_security_agent_rule_type import CloudWorkloadSecurityAgentRuleType

body = CloudWorkloadSecurityAgentRuleCreateRequest(
    data=CloudWorkloadSecurityAgentRuleCreateData(
        attributes=CloudWorkloadSecurityAgentRuleCreateAttributes(
            description="My Agent rule",
            enabled=True,
            expression='exec.file.name == "sh"',
            filters=[],
            name="examplecsmthreat",
        ),
        type=CloudWorkloadSecurityAgentRuleType.AGENT_RULE,
    ),
)

configuration = Configuration()
configuration.access_token = environ["DD_BEARER_TOKEN"]
with ApiClient(configuration) as api_client:
    api_instance = CSMThreatsApi(api_client)
    response = api_instance.create_cloud_workload_security_agent_rule(body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" python3 "example.py"
# Create a Workload Protection agent rule (US1-FED) returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.access_token = ENV["DD_BEARER_TOKEN"]
end
api_instance = DatadogAPIClient::V2::CSMThreatsAPI.new

body = DatadogAPIClient::V2::CloudWorkloadSecurityAgentRuleCreateRequest.new({
  data: DatadogAPIClient::V2::CloudWorkloadSecurityAgentRuleCreateData.new({
    attributes: DatadogAPIClient::V2::CloudWorkloadSecurityAgentRuleCreateAttributes.new({
      description: "My Agent rule",
      enabled: true,
      expression: 'exec.file.name == "sh"',
      filters: [],
      name: "examplecsmthreat",
    }),
    type: DatadogAPIClient::V2::CloudWorkloadSecurityAgentRuleType::AGENT_RULE,
  }),
})
p api_instance.create_cloud_workload_security_agent_rule(body)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" rb "example.rb"
// Create a Workload Protection agent rule (US1-FED) returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_csm_threats::CSMThreatsAPI;
use datadog_api_client::datadogV2::model::CloudWorkloadSecurityAgentRuleCreateAttributes;
use datadog_api_client::datadogV2::model::CloudWorkloadSecurityAgentRuleCreateData;
use datadog_api_client::datadogV2::model::CloudWorkloadSecurityAgentRuleCreateRequest;
use datadog_api_client::datadogV2::model::CloudWorkloadSecurityAgentRuleType;

#[tokio::main]
async fn main() {
    let body = CloudWorkloadSecurityAgentRuleCreateRequest::new(
        CloudWorkloadSecurityAgentRuleCreateData::new(
            CloudWorkloadSecurityAgentRuleCreateAttributes::new(
                r#"exec.file.name == "sh""#.to_string(),
                "examplecsmthreat".to_string(),
            )
            .description("My Agent rule".to_string())
            .enabled(true)
            .filters(vec![]),
            CloudWorkloadSecurityAgentRuleType::AGENT_RULE,
        ),
    );
    let configuration = datadog::Configuration::new();
    let api = CSMThreatsAPI::with_config(configuration);
    let resp = api.create_cloud_workload_security_agent_rule(body).await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" cargo run
/**
 * Create a Workload Protection agent rule (US1-FED) returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration({
  authMethods: {
    AuthZ: {
      accessToken: process.env.DD_BEARER_TOKEN as string,
    },
  },
});
const apiInstance = new v2.CSMThreatsApi(configuration);

const params: v2.CSMThreatsApiCreateCloudWorkloadSecurityAgentRuleRequest = {
  body: {
    data: {
      attributes: {
        description: "My Agent rule",
        enabled: true,
        expression: `exec.file.name == "sh"`,
        filters: [],
        name: "examplecsmthreat",
      },
      type: "agent_rule",
    },
  },
};

apiInstance
  .createCloudWorkloadSecurityAgentRule(params)
  .then((data: v2.CloudWorkloadSecurityAgentRuleResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" tsc "example.ts"