Agent Expressions

Agent Expressions

Cloud Workload Security is currently in public beta.

Agent Expression Syntax

Rules for Cloud Workload Security (CWS) are first evaluated in the Datadog Agent to decide what system activity to collect. This portion of a CWS rule is called the Agent expression. Agent expressions use Datadog’s Security Language (SECL). The standard format of a SECL expression is as follows:

<trigger>.<event-attribute> <operator> <value> <event-attribute> ...

Using this format, an example rule looks like this:

open.file.path == "/etc/shadow" && file.path not in ["/usr/sbin/vipw"]

Triggers

Triggers are events that correspond to types of activity seen by the system. The currently supported set of triggers is:

SECL EventTypeDefinitionAgent Version
execProcessA process was executed or forked7.27
openFileA file was opened7.27
chmodFileA file’s permissions were changed7.27
chownFileA file’s owner was changed7.27
mkdirFileA directory was created7.27
rmdirFileA directory was removed7.27
renameFileA file/directory was renamed7.27
unlinkFileA file was deleted7.27
utimesFileChange file access/modification times7.27
linkFileCreate a new name/alias for a file7.27
setxattrFileSet exteneded attributes7.27
removexattrFileRemove extended attributes7.27
mountFileMount a filesystem7.27
unmountFileUnmount a filesystem7.27

Operators

SECL operators are used to combine event attributes together into a full expression. The following operators are available:

SECL OperatorTypesDefinitionAgent Version
==ProcessEqual7.27
!=FileNot equal7.27
>FileGreater7.27
>=FileGreater or equal7.27
<FileLesser7.27
<=FileLesser or equal7.27
!FileNot7.27
^FileBinary not7.27
in [elem1, ...]FileElement is contained in list7.27
not in [elem1, ...]FileElement is not contained in list7.27
[~pattern, ...]FileRegex pattern is (not) contained in list7.27
=~FileString matching7.27
&FileBinary and7.27
|FileBinary or7.27
&&FileLogical and7.27
||FileLogical or7.27

Helpers

Helpers exist in SECL that enable users to write advanced rules without needing to rely on generic techniques such as regex.

Command line arguments

The args_flags and args_options are helpers to ease the writing of CWS rules based on command line arguments.

args_flags is used to catch arguments that start with either one or two hyphen characters but do not accept any associated value.

Examples:

  • version is part of args_flags for the command cat --version
  • l and n both are in args_flags for the command netstat -ln

args_options is used to catch arguments that start with either one or two hyphen characters and accepts a value either specified as the same argument but separated by the ‘=’ character or specified as the next argument.

Examples:

  • T=8 and width=8 both are in args_options for the command ls -T 8 --width=8
  • exec.args_options ~= [ “s=.*\’” ] can be used to detect sudoedit was launched with -s argument and a command that ends with a \

File rights

The file.rights attribute can now be used in addition to file.mode. file.mode can hold values set by the kernel, while the file.rights only holds the values set by the user. These rights may be more familiar because they are in the chmod commands.