Table of Contents

13 Restricting agent checks

13 Restricting agent checks

Overview

It is possible to restrict checks on the agent side by creating an item blacklist, a whitelist, or a combination of whitelist/blacklist.

To do that use a combination of two agent configuration parameters:

AllowKey=<pattern> - which checks are allowed; <pattern> is specified using a wildcard (*) expression
DenyKey=<pattern> - which checks are denied; <pattern> is specified using a wildcard (*) expression

Note that:

All system.run[*] items (remote commands, scripts) are disabled by default, even when no deny keys are specified;
Since Zabbix 5.0.2 the EnableRemoteCommands agent parameter is:

   * deprecated by Zabbix agent
          * unsupported by Zabbix agent2

Therefore, to allow remote commands, specify an AllowKey=system.run[<command>,*] for each allowed command, * stands for wait and nowait mode. It is also possible to specify AllowKey=system.run[*] parameter to allow all commands with wait and nowait modes. To disallow specific remote commands, add DenyKey parameters with system.run[] commands before the AllowKey=system.run[*] parameter.

Important rules

A whitelist without a deny rule is only allowed for system.run[*] items. For all other items, AllowKey parameters are not allowed without a DenyKey parameter; in this case Zabbix agent will not start with only AllowKey parameters.
The order matters. The specified parameters are checked one by one according to their appearance order in the configuration file:
- As soon as an item key matches an allow/deny rule, the item is either allowed or denied; and rule checking stops. So if an item matches both an allow rule and a deny rule, the result will depend on which rule comes first.
- The order affects also EnableRemoteCommands parameter (if used).
Unlimited numbers of AllowKey/DenyKey parameters is supported.
AllowKey, DenyKey rules do not affect HostnameItem, HostMetadataItem, HostInterfaceItem configuration parameters.
Key pattern is a wildcard expression where the wildcard (*) character matches any number of any characters in certain position. It might be used in both the key name and parameters.
If a specific item key is disallowed in the agent configuration, the item will be reported as unsupported (no hint is given as to the reason);
Zabbix agent with --print (-p) command line option will not show keys that are not allowed by configuration;
Zabbix agent with --test (-t) command line option will return "Unsupported item key." status for keys that are not allowed by configuration;
Denied remote commands will not be logged in the agent log (if LogRemoteCommands=1).

Use cases

Deny specific check

Blacklist a specific check with DenyKey parameter. Matching keys will be disallowed. All non-matching keys will be allowed, except system.run[] items.

For example:

# Deny secure data access
       DenyKey=vfs.file.contents[/etc/passwd,*]

A blacklist may not be a good choice, because a new Zabbix version may have new keys that are not explicitly restricted by the existing configuration. This could cause a security flaw.

Deny specific command, allow others

Blacklist a specific command with DenyKey parameter. Whitelist all other commands, with the AllowKey parameter.

# Disallow specific command
       DenyKey=system.run[ls -l /]
        
       # Allow other scripts
       AllowKey=system.run[*]

Allow specific check, deny others

Whitelist specific checks with AllowKey parameters, deny others with DenyKey=*

For example:

# Allow reading logs:
       AllowKey=vfs.file.*[/var/log/*]
       
       # Allow localtime checks
       AllowKey=system.localtime[*]
       
       # Deny all other keys
       DenyKey=*

Pattern examples

Pattern	Description	Matches	No match
*	Matches all possible keys with or without parameters.	Any	None
vfs.file.contents	Matches `vfs.file.contents` without parameters.	vfs.file.contents	vfs.file.contents[/etc/passwd]
vfs.file.contents[]	Matches `vfs.file.contents` with empty parameters.	vfs.file.contents[]	vfs.file.contents
vfs.file.contents[]*	Matches `vfs.file.contents` with any parameters; will not match `vfs.file.contents` without square brackets.	vfs.file.contents[] vfs.file.contents[/path/to/file]	vfs.file.contents
vfs.file.contents[/etc/passwd,]*	Matches `vfs.file.contents` with first parameters matching /etc/passwd and all other parameters having any value (also empty).	vfs.file.contents[/etc/passwd,] vfs.file.contents[/etc/passwd,utf8]	vfs.file.contents[/etc/passwd] vfs.file.contents[/var/log/zabbix_server.log] vfs.file.contents[]
vfs.file.contents[passwd]	Matches `vfs.file.contents` with first parameter matching passwd and no other parameters.	vfs.file.contents[/etc/passwd]	vfs.file.contents[/etc/passwd,] vfs.file.contents[/etc/passwd, utf8]
vfs.file.contents[passwd,]*	Matches `vfs.file.contents` with only first parameter matching passwd and all following parameters having any value (also empty).	vfs.file.contents[/etc/passwd,] vfs.file.contents[/etc/passwd, utf8]	vfs.file.contents[/etc/passwd] vfs.file.contents[/tmp/test]
vfs.file.contents[/var/log/zabbix_server.log,,abc]*	Matches `vfs.file.contents` with first parameter matching /var/log/zabbix_server.log, third parameter matching 'abc' and any (also empty) second parameter.	vfs.file.contents[/var/log/zabbix_server.log,,abc] vfs.file.contents[/var/log/zabbix_server.log,utf8,abc]	vfs.file.contents[/var/log/zabbix_server.log,,abc,def]
vfs.file.contents[/etc/passwd,utf8]	Matches `vfs.file.contents` with first parameter matching /etc/passwd, second parameter matching 'utf8' and no other arguments.	vfs.file.contents[/etc/passwd,utf8]	vfs.file.contents[/etc/passwd,] vfs.file.contents[/etc/passwd,utf16]
vfs.file.*	Matches any keys starting with `vfs.file.` without any parameters.	vfs.file.contents vfs.file.size	vfs.file.contents[] vfs.file.size[/var/log/zabbix_server.log]
vfs.file.[]	Matches any keys starting with `vfs.file.` with any parameters.	vfs.file.size.bytes[] vfs.file.size[/var/log/zabbix_server.log, utf8]	vfs.file.size.bytes
vfs..contents*	Matches any key starting with `vfs.` and ending with `.contents` without any parameters.	vfs.mount.point.file.contents vfs..contents	vfs.contents

system.run and AllowKey

A hypothetical script like 'myscript.sh' may be executed on a host via Zabbix agent in several ways:

1. As an item key in a passive or active check, for example:

system.run[myscript.sh]
system.run[myscript.sh,wait]
system.run[myscript.sh.nowait]

Here the user may add "wait", "nowait" or omit the 2nd argument to use its default value in system.run[].

2. As a global script (initiated by user in frontend or API).

A user configures this script in Administration → Scripts, sets "Execute on: Zabbix agent" and puts "myscript.sh" into the script's "Commands" input field. When invoked from frontend or API the Zabbix server sends to agent:

system.run[myscript.sh,wait] - up to Zabbix 5.0.4
system.run[myscript.sh] - since 5.0.5

Here the user does not control the "wait"/"nowait" parameters.

3. As a remote command from an action. The Zabbix server sends to agent:

system.run[myscript.sh,nowait]

Here again the user does not control the "wait"/"nowait" parameters.

What that means is if we set AllowKey like:

AllowKey=system.run[myscript.sh]

then

system.run[myscript.sh] - will be allowed
system.run[myscript.sh,wait], system.run[myscript.sh,nowait] will not be allowed - the script will not be run if invoked as a step of action

To allow all described variants you may add:

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

to the agent/agent2 parameters.

Documentation