Restricting agent checks

Overview

You can control which item keys Zabbix agent or agent 2 is allowed or denied to use when executing item checks, remote commands, or scripts.

To do that, use these agent configuration parameters to define allow/deny rules:

• AllowKey=<pattern>
• DenyKey=<pattern>
• AllowKeyRegexp=<pattern>
• DenyKeyRegexp=<pattern>

The <pattern> must contain a single item key.
For AllowKey and DenyKey, the <pattern> supports wildcards (*). The wildcard matches any number of any characters in its position, and can be used to match item keys or parameters (e.g., vfs.file.*[*]).
For AllowKeyRegexp and DenyKeyRegexp, the <pattern> supports regular expressions. The regular expression pattern can be used to match item keys and their parameter strings. See also examples of correct escaping.
Note that Zabbix agent and Zabbix agent 2 may support different regular expression syntax.

In contrast to other agent configuration parameters, you can specify an unlimited number of AllowKey, DenyKey, AllowKeyRegexp, or DenyKeyRegexp parameters.

Important notes

• Use AllowKey or AllowKeyRegexp to allow only the items that are required, and DenyKey or DenyKeyRegexp as the last rule to deny all others. This is safer than relying on deny rules alone, because new Zabbix agent versions may introduce item keys not covered by your DenyKey or DenyKeyRegexp rules.

• Make allow rules as specific as possible: use exact item keys instead of wildcards (*) in AllowKey rules, and use the most specific regular expression patterns in AllowKeyRegexp rules.

• If you use DenyKey or DenyKeyRegexp, deny entire item keys rather than specific files or commands. Rules that target specific parameters can be bypassed; for example, path traversal (vfs.file.contents["../../../../etc/passwd"]) can read a file that a rule for its direct path was meant to block. For details, see Securing allow/deny rules.

• All system.run items are denied by default (even when DenyKey and DenyKeyRegexp are empty), as if DenyKey=system.run[*] was set as the last rule. Because of this, you can allow specific system.run items without explicitly denying other system.run items. This implicit deny applies only to system.run; for all other keys, allow rules have no effect unless a deny rule follows them.

• AllowKey, DenyKey, AllowKeyRegexp, and DenyKeyRegexp configuration does not affect HostnameItem, HostMetadataItem, or HostInterfaceItem agent parameters.

• Denied items become unsupported without any indication that they were denied; they look the same as nonexistent item keys. For example:

  • Zabbix agent --print (-p) command-line parameter will not show denied item keys.
  • Zabbix agent --test (-t) command-line parameter will return Unsupported item key. for denied item keys.
  • When logging is activated (LogRemoteCommands=1), Zabbix agent log file will not log denied remote commands.

Allow/deny rule order

You can specify an unlimited number of AllowKey, DenyKey, AllowKeyRegexp, or DenyKeyRegexp rules, though their order matters.

• Rules are evaluated one by one, from top to bottom.
• When an item key matches a rule, it is either allowed or denied, and rule evaluation stops.

For example, when evaluating vfs.file.contents[/etc/passwd], the rules are processed as follows:

AllowKey=vfs.file.contents[/tmp/app.log]    # Item key pattern does not match, agent proceeds to the next rule.
AllowKey=vfs.file.contents[/etc/passwd]     # Item key pattern matches; agent allows the item check and stops rule evaluation.
DenyKey=vfs.file.*[*]                       # Agent ignores the rule, as the evaluation has stopped.

The following rule order will deny the item check:

DenyKey=vfs.file.*[*]                       # Item key pattern matches; agent denies the item check and stops rule evaluation.
AllowKey=vfs.file.contents[/etc/passwd]     # Agent ignores the rule, as the evaluation has stopped.
AllowKey=vfs.file.contents[/tmp/app.log]    # Agent ignores the rule, as the evaluation has stopped.

Examples

The following examples show common configuration patterns for AllowKey, DenyKey, AllowKeyRegexp, and DenyKeyRegexp.

Allowing specific checks and commands

Allow only two vfs.file item checks and two system.run commands:

using AllowKey and DenyKey:

AllowKey=vfs.file.contents[/tmp/app.log]
AllowKey=vfs.file.size[/tmp/app.log]
AllowKey=system.run[/usr/bin/uptime]
AllowKey=system.run[/usr/bin/df -h /]
DenyKey=vfs.file.*[*]

using AllowKeyRegexp and DenyKeyRegexp:

AllowKeyRegexp=^vfs\.file\.(contents|size)\[/tmp/app\.log\]$
AllowKeyRegexp=^system\.run\[/usr/bin/(uptime|df -h /)\]$
DenyKeyRegexp=^vfs\.file\..*\[[\s\S]*\]$

Allowing scripts

Allow Zabbix agent to execute scripts on hosts via all available methods:

• Global scripts that can be executed in the frontend or via API (this method always uses the system.run[myscript.sh] key)
• Remote commands from action operations (this method always uses the system.run[myscript.sh,nowait] key)
• system.run Zabbix agent items with the script, for example:
  • system.run[myscript.sh]
  • system.run[myscript.sh,wait]
  • system.run[myscript.sh,nowait]

AllowKey=system.run[myscript.sh,*]

or

AllowKeyRegexp=(?s)^system\.run\[myscript\.sh,.*\]$

To control the wait/nowait parameter, you must set a different rule. For example, you can allow only system.run[myscript.sh,wait] items, thus excluding other methods:

AllowKey=system.run[myscript.sh,wait]

or

AllowKeyRegexp=^system\.run\[myscript\.sh,wait\]$

Securing allow/deny rules

These examples show how to secure overly permissive AllowKey/AllowKeyRegexp or DenyKey/DenyKeyRegexp rules.

Consider the following rules:

using AllowKey and DenyKey:

AllowKey=system.run["C:\Program^ Files\Zabbix^ Agent^ 2\scripts\test.bat*"]
DenyKey=vfs.file.*
DenyKey=system.cpu.load[*]

using AllowKeyRegexp and DenyKeyRegexp:

AllowKeyRegexp=^system\.run\["C:\\Program\sFiles\\Zabbix\sAgent\s2\\scripts\\test\.bat.*"\]$
DenyKeyRegexp=^vfs\.file\..*$
DenyKeyRegexp=^system\.cpu\.load\[.*\]$

These rules contain a wildcard (*), which can be misused:

• The test.bat script can be executed with any arguments, including unintended ones.
• The vfs.file.* pattern matches item keys without parameters; however, all vfs.file items require parameters.
• The system.cpu.load[*] pattern matches only item keys with parameters; however system.cpu.load items do not require parameters.

To secure these rules, explicitly allow executing test.bat only with specific arguments, and deny correct item key patterns; for example:

using AllowKey and DenyKey:

AllowKey=system.run["C:\Program^ Files\Zabbix^ Agent^ 2\scripts\test.bat status"]
AllowKey=system.run["C:\Program^ Files\Zabbix^ Agent^ 2\scripts\test.bat version"]
DenyKey=vfs.file.*[*]
DenyKey=system.cpu.load
DenyKey=system.cpu.load[*]

using AllowKeyRegexp and DenyKeyRegexp:

AllowKeyRegexp=^system\.run\["C:\\Program\sFiles\\Zabbix\sAgent\s2\\scripts\\test\.bat (status|version)"\]$
DenyKeyRegexp=^vfs\.file\..+\[[\s\S]*\]$
DenyKeyRegexp=^system\.cpu\.load(\[.*\])?$

You can test the rules by running the following commands, which will return ZBX_NOTSUPPORTED.

cd "C:\Program Files\Zabbix Agent 2"
zabbix_agent2.exe -t system.run["C:\Program^ Files\Zabbix^ Agent^ 2\scripts\test.bat debug"]
zabbix_agent2.exe -t vfs.file.size["C:\ProgramData\MyApp\config.ini"]
zabbix_agent2.exe -t vfs.file.contents["C:\Windows\System32\drivers\etc\hosts"]
zabbix_agent2.exe -t system.cpu.load
zabbix_agent2.exe -t system.cpu.load[all,avg1]

Pattern examples

The following tables show how item key patterns are matched:

• A key matches the pattern only if it meets all conditions in the Matches column.
• Parameters must be fully enclosed in square brackets (e.g., vfs.file.contents[* and vfs.file.contents*utf8] are invalid patterns).
• The examples illustrate pattern matching only; actual items require parameters.

Using wildcard-based rules:

Using regular expression-based rules: