Security rules

Each log file you ingest needs to be validated by OneAgent and must abide by its security rules (file matching rules). Dynatrace's security rules for log filepaths ensure data protection by managing OneAgent access to files. By implementing these security measures, Dynatrace ensures defense against unauthorized access and data misuse. You also have the option to add or override these predefined security rules in the configuration file on the host where OneAgent is installed, allowing for flexibility in adapting to specific security needs.

Security rules apply to both automatically detected log files and custom log sources.

Default security rules

If a custom log source includes files disallowed by security rules, these files will be ignored by Log Agent. Default security rules do not block any automatically detected files. If you alter the security rules to be more strict, blocking some automatically detected files, it will result in auto-detection ignoring these files accordingly.

Important

Security rules cannot be used to expand the autodetector to detect more files. You can only use them to limit the detection of files. If you need to include a log source that isn't automatically detected, use a custom log source configuration.

The rules prohibit log paths in critical system directories (such as /etc, /boot, /proc, and several others), paths containing .ssh, paths with the .pem extension, and paths in directories starting with a dot (indicating hidden directories).

Dynatrace version 1.303+

Acceptable log paths must either have a log or txt extension, or be located in one of the following directories: log, logs, applogs, logfile, logfiles, or have the filename catalina.out. A log extension can be followed by another extension, and a txt extension can also be followed by another extension. An additional rotation extension is also allowed.

To ensure data protection and compliance, the following security rules must be adhered to for log paths:

A log path is not in any of the following: /etc, /boot, /proc, /dev, /bin, /sbin, WindowsRoot:\windows, or WindowsRoot:\winnt. However, Windows|winnt\system32\winevt\Logs is accepted AND
A log path does not contain .ssh AND
A log path does not have the .pem extension AND
A log path is not located in a directory whose name starts with . (for example, /.hidden) AND
One of the following conditions is met:
- A log path must have the log extension separated by ., -, or _ (it can be followed by another extension with the same separator set) OR
- A log file is located in one of the following directories (which doesn't need to be the direct parent): log, logs, applogs, logfile, logfiles OR
- A log file has file name catalina.out, optionally followed by another extension (e.g. added by rotation mechanism).
Please note that all matching is case-insensitive on all operating systems, not just on Windows.

Acceptable log paths must either have a log extension with certain separators, be located within the first or second level of a log or logs directory (or on the third level since Log Agent 1.287), be situated at any level of the /var/log directory, or have the filename catalina.out.”

The rules take into account the resolved paths of symbolic links for security matching, emphasizing the importance of the actual file location over the symlink path.

A log path is not in any of the following: /etc, /boot, /proc, /dev, /bin, /sbin, /usr, WindowsRoot:\windows, or WindowsRoot:\winnt. However, Windows|winnt\system32\winevt\Logs is accepted AND
A log path does not contain .ssh AND
A log path does not have the .pem extension AND
A log path is not located in a directory whose name starts with . (for example, /.hidden) AND
A log path must have the log extension separated by ., -, or _ (it can be followed by another extension with the same separator set) OR
- A log path must be located on the first or second level of the log or logs directory (since Log Agent 1.287 it can also be located on the third level) OR
- A log path must be located on any level of the /var/log directory OR
- A log path must have the file name catalina.out.
Please note that all matching is case-insensitive on all operating systems, not just on Windows.

Files with paths that do not fulfill one or more criteria are not accepted. Once the conditions above are met, log file matching takes place. Check the log file matching rules.

Override security rules

You can add or override predefined security rules only in the configuration file on the host where OneAgent is installed.

Save your changes as a separate file placed in the OneAgent persistent configuration directory.
- /var/lib/dynatrace/oneagent/agent/config/logmodule on Linux and UNIX
- %PROGRAMDATA%\dynatrace\oneagent\agent\config\logmodule on Windows
  
  Any log file with the .json suffix is allowed in the above directories.
Do not edit the file that contains predefined rules:
- /opt/dynatrace/oneagent/agent/conf on Linux and UNIX
- %PROGRAMFILES%\dynatrace\oneagent\agent\conf on Windows
Rules defined by you under the custom configuration take precedence over the default rules. Additionally, the first matching rule determines whether a path passes the security test. The override configuration file (the one that you save in the persistent configuration directory) format needs to be the same as the format for a file with predefined rules.

Override configuration file

There is a predefined directory pattern that is executed from right to left. For example, /log/ will match /log/file and /var/log/file but not /log/dir/file
Only one directory is matched. For example, /log/*/ will match /log/dir/file but not /log/dir/dir2/file
The [-.\\_] expression in a pattern means that one of the characters provided in the square brackets must be present for a match to occur.

The override configuration file is a JSON object that defines rules for allowing or excluding certain log paths based on specified directory and file patterns.

The following structure is given in the file:

allowed-log-paths-configuration: Marks the array of the rules.

Each rule consists of three key-value pairs, with the following mandatory keys:

directory-pattern
file-pattern
action

The description of the keys is given below:

directory-pattern: This object specifies the pattern for matching directories. The directory pattern is executed from right to left, for example: /log/ will match /log/file.txt and /var/log/file.txt but not /log/dir/file.txt. The following rules apply:
- A directory is matched by a wildcard *. For example, /log/*/ will match /log/dir/file.txt but not /log/dir/dir2/file.txt.
- ** matches any number of subdirectories. For example, the pattern /log/dir/**/ will match /log/dir/dir1/dir2/dir3/file.txt and /log/dir/file.txt.
- ^ matches the start of the path. It anchors the pattern to the beginning of the examined path For example, ^/usr/*/ matches paths starting with /usr/, such as /usr/log/file.txt and /usr/local/file.txt, but will not match /some/usr/log/file.txt. For Windows paths, the anchor can also skip the drive letter. For example, the pattern ^/Users/Public/ would match the actual path C:\Users\Public\file.txt. JSON treats \ as an escape character, so when specifying Windows paths, you can use either C:\\Users\\Public or C:/Users/Public but not C:\Users\Public. All pattern matching is case insensitive.
You can combine special characters such as *, **, and ^ within a single directory pattern to create more complex matching rules. For example, the pattern ^/log/**/dir/*/*/ will match the path /log/some/deep/dir/and/deeper/file.txt.
file-pattern: This object specifies the pattern for matching files within the directories matched by the directory pattern.

Dynatrace version 1.303+

This pattern is applied using full match, case insensitive. This means a pattern such as error_*.txt will match error_1.txt but not severe_error_1.txt. In this example, the file pattern should contain a wildcard at the beginning: *error_*.txt to match both files. There is one exception to that rule introduced to avoid common mistakes related to rotated files: Log Agent treats each rule with INCLUDE action as its file-pattern had an additional optional extension, separated by ., -, or _. This means that a rule with the INCLUDE action and file pattern set to *.txt will catch not only error.txt but also error.txt.1.

Dynatrace version 1.302 and earlier

This pattern is applied using full match, case insensitive. This means that a pattern such as *.txt will match error.txt but not error.txt.1. To properly detect files that follow rotation patterns, the file pattern must include a wildcard at the end. For example, to match files that rotate from error.txt to error.txt.1, the file pattern should be constructed as *.txt*.
action: This object specifies the action to be taken for the matched file. In this case, EXCLUDE or INCLUDE.

The [-.\\_] expression in square brackets means that one of the characters provided in the square brackets must be present for a match to occur.

An example override configuration file is given below:

Example override configuration file

{
    "allowed-log-paths-configuration":[
       {
          "directory-pattern":"/",
          "file-pattern":"*.pem",
          "action":"EXCLUDE" // or INCLUDE
       },
       ... your rules ...
    ]
 }

Examples of OneAgent security rules

Each custom log source path you add needs to be validated by OneAgent and abide by its security rules (file matching rules). Some predefined security rules are applied on the OneAgent side. Examples of exclude and include rules for UNIX, Linux, and Windows are listed in the table below.

Operating system

Directory pattern

File pattern

Action

UNIX

/

*.pem

EXCLUDE

UNIX

/

*[-.\\_]log[-.\\_]*

INCLUDE

Linux

/.ssh/

EXCLUDE

Linux

/

*[-.\\_]log

INCLUDE

Windows

/.*/

EXCLUDE

Windows

/windows/system32/winevt/Logs/

INCLUDE

Security rule lists for UNIX, Linux, and Windows

The full list of security rules for UNIX:

Dynatrace version 1.303+

{
  "@version": "1.0.0",
  "allowed-log-paths-configuration": [
    {
       "directory-pattern":"/",
       "file-pattern":"*.pem",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.ssh/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.*/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/",
       "file-pattern":".*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/etc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/boot/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/proc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/dev/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/bin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/sbin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]txt",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "catalina.out*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfile/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfile/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfiles/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfiles/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/applogs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/applogs/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/lib/docker/containers/*/",
      "file-pattern": "*.log",
      "action": "INCLUDE"
    }
  ]
}

Dynatrace version 1.301 and earlier

{
  "allowed-log-paths-configuration": [
    {
       "directory-pattern":"/",
       "file-pattern":"*.pem",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.ssh/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.*/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/",
       "file-pattern":".*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/etc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/boot/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/proc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/dev/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/bin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/sbin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/usr/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log[-.\\_]*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "catalina.out*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/*/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/*/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/lib/docker/containers/*/",
      "file-pattern": "*.log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/log/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    }
  ]
}

The full list of security rules for Linux:

Dynatrace version 1.303+

{
  "@version": "1.0.0",
  "allowed-log-paths-configuration": [
    {
       "directory-pattern":"/",
       "file-pattern":"*.pem",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.ssh/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.*/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/",
       "file-pattern":".*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/etc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/boot/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/proc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/dev/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/bin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/sbin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]txt",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "catalina.out*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfile/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfile/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfiles/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfiles/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/applogs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/applogs/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/lib/docker/containers/*/",
      "file-pattern": "*.log",
      "action": "INCLUDE"
    }
  ]
}

Dynatrace version 1.301 and earlier

{
  "allowed-log-paths-configuration": [
    {
       "directory-pattern":"/",
       "file-pattern":"*.pem",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.ssh/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.*/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/",
       "file-pattern":".*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/etc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/boot/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/proc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/dev/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/bin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/sbin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/usr/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log[-.\\_]*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "catalina.out*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/*/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/*/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/lib/docker/containers/*/",
      "file-pattern": "*.log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/log/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    }
  ]
}

The full list of security rules for Windows:

Dynatrace version 1.303+

{
  "@version":"1.0.0",
  "allowed-log-paths-configuration":[
    {
      "directory-pattern":"/",
      "file-pattern":"*.pem",
      "action":"EXCLUDE"
    },
    {
      "directory-pattern":"/.ssh/",
      "file-pattern":"*",
      "action":"EXCLUDE"
    },
    {
      "directory-pattern":"/.*/",
      "file-pattern":"*",
      "action":"EXCLUDE"
    },
    {
      "directory-pattern":"/",
      "file-pattern":".*",
      "action":"EXCLUDE"
    },
    {
      "directory-pattern":"/windows/system32/winevt/Logs/",
      "file-pattern":"*",
      "action":"INCLUDE"
    },
    {
      "directory-pattern":"/winnt/system32/winevt/Logs/",
      "file-pattern":"*",
      "action":"INCLUDE"
    },
    {
      "directory-pattern":"^/windows/**/",
      "file-pattern":"*",
      "action":"EXCLUDE"
    },
    {
      "directory-pattern":"^/winnt/**/",
      "file-pattern":"*",
      "action":"EXCLUDE"
    },
    {
      "directory-pattern":"/",
      "file-pattern":"*[-.\\_]log",
      "action":"INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]txt",
      "action": "INCLUDE"
    },
    {
      "directory-pattern":"/",
      "file-pattern":"catalina.out*",
      "action":"INCLUDE"
    },
    {
      "directory-pattern": "/log/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfile/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfile/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfiles/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logfiles/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/applogs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/applogs/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    }
  ]
}

Dynatrace version 1.301 and earlier

{
    "allowed-log-paths-configuration":[
       {
          "directory-pattern":"/",
          "file-pattern":"*.pem",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/.ssh/",
          "file-pattern":"*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/.*/",
          "file-pattern":"*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/",
          "file-pattern":".*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/windows/system32/winevt/Logs/",
          "file-pattern":"*",
          "action":"INCLUDE"
       },
       {
          "directory-pattern":"/winnt/system32/winevt/Logs/",
          "file-pattern":"*",
          "action":"INCLUDE"
       },
       {
          "directory-pattern":"^/windows/**/",
          "file-pattern":"*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"^/winnt/**/",
          "file-pattern":"*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/",
          "file-pattern":"*[-.\\_]log[-.\\_]*",
          "action":"INCLUDE"
       },
       {
          "directory-pattern":"/",
          "file-pattern":"*[-.\\_]log",
          "action":"INCLUDE"
       },
       {
          "directory-pattern":"/",
          "file-pattern":"catalina.out*",
          "action":"INCLUDE"
       },
       {
          "directory-pattern": "/log/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/log/*/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/log/*/*/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/logs/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/logs/*/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/logs/*/*/",
          "file-pattern": "*",
          "action": "INCLUDE"
       }
    ]
}