Security rules

  • Latest Dynatrace
  • Explanation
  • 4-min read

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. Security rules apply to all files detected by Log Agent.

You can use the predefined security rules as-is (see Predefined security rules) or override the predefined rules with a custom configuration (see Override security rules).

Predefined security rules

Predefined security rules apply to both autodiscovered log files and custom log sources.

  • In their default configuration, the predefined security rules do not block any files discovered by the autodiscovery mechanism.
  • If a custom log source includes files disallowed by the predefined security rules, these files will be ignored by the OneAgent Log Module. To ingest these files, you need to override the predefined security rules on the relevant host, see Override security rules, below.

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.
Security rules for Dynatrace version 1.301 and earlier

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 OneAgent Log Module 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 OneAgent Log Module 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 the predefined security rules

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

Dynatrace provides a script to check if a specific path is supported, and to prepare a custom configuration file to allow for ingesting log files from non-standard file paths.

You can either restrict or relax the predefined security rules:

  • If you restrict the predefined security rules, both autodiscovery and custom log sources are affected.

  • If you relax the predefined security rules, only custom log sources are affected.

    (Autodiscovered log sources are not affected because the autodiscovery mechanism has a built-in pattern list that is itself more restrictive than the predefined security rules. For more information, see Autodiscovery requirements.)

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

Security rule lists for UNIX, Linux, and Windows

Security rules for UNIX

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"
}
]
}
Security rules for Linux

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"
}
]
}
Security rules for Windows

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"
}
]
}
Related tags
Log Analytics