[comment]: # ({780b1aa2-780b1aa2})
# 13 Restricting agent checks

[comment]: # ({/780b1aa2-780b1aa2})

[comment]: # ({40953ae4-9de656b2})
#### 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](/manual/appendix/config/zabbix_agentd) parameters to define allow/deny rules:

-   `AllowKey=<pattern>`
-   `DenyKey=<pattern>`

The `<pattern>` must contain a single item key and 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.*[*]`).

::: noteimportant
To improve security, it is recommended to use exact item keys instead of wildcards.
For details, see [Securing allow/deny rules](#securing-allowdeny-rules).
:::

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

[comment]: # ({/40953ae4-9de656b2})

[comment]: # ({9a018340-3145c750})
#### Important notes

-   All [`system.run`](/manual/config/items/itemtypes/zabbix_agent#system-data) items are disabled by default (even when `DenyKey` is empty), as if `DenyKey=system.run[*]` was set as the [last rule](#allowdeny-rule-order).
    Because of this, you can allow specific `system.run` items without explicitly denying other `system.run` items.

-   An item specified in `AllowKey` must also be specified in `DenyKey` (except for `system.run` items); otherwise, Zabbix agent **will not start**.

-   If possible, use `AllowKey` to allow only required items and deny everything else.
    Some keys can be abused to read unintended files via path traversal (e.g., `vfs.file.contents["../../../../etc/passwd"]`), and new Zabbix agent versions may introduce keys not covered by your `DenyKey` rules.

-   `AllowKey` and `DenyKey` configuration does not affect `HostnameItem`, `HostMetadataItem`, or `HostInterfaceItem` agent parameters.

-   Denied items become unsupported without any hints or error messages; for example:
    -   Zabbix agent [`--print (-p)`](/manual/concepts/agent#other-agent-options) command-line parameter will not show denied item keys.
    -   Zabbix agent [`--test (-t)`](/manual/concepts/agent#other-agent-options) command-line parameter will return "Unsupported item key." for denied item keys.
    -   Zabbix agent log file will not log denied [remote commands](/manual/config/notifications/action/operation/remote_command) if `LogRemoteCommands=1`.

[comment]: # ({/9a018340-3145c750})

[comment]: # ({071aae59-66ec4bb8})
#### Allow/deny rule order

You can specify an unlimited number of `AllowKey` or `DenyKey` 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:

```default
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:

```default
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.
```

[comment]: # ({/071aae59-66ec4bb8})

[comment]: # ({cb10c569-253ad144})
#### Examples

The following examples show common configuration patterns for `AllowKey` and `DenyKey`.

[comment]: # ({/cb10c569-253ad144})

[comment]: # ({7c50f9f0-19895d10})
##### Allowing specific checks and commands

Allow only two [`vfs.file`](/manual/config/items/itemtypes/zabbix_agent#virtual-file-system-data) item checks and two [`system.run`](/manual/config/items/itemtypes/zabbix_agent#system-data) commands:

```default
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.*[*]
```

::: noteclassic
Setting `DenyKey=system.run[*]` is unnecessary, because all other `system.run` commands are denied by default.
:::

[comment]: # ({/7c50f9f0-19895d10})

[comment]: # ({038b9efe-3cc5f239})
##### Allowing scripts

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

-   [Global scripts](/manual/web_interface/frontend_sections/administration/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](/manual/config/notifications/action/operation#operation-details) (this method always uses the `system.run[myscript.sh,nowait]` key)
-   [`system.run`](/manual/config/items/itemtypes/zabbix_agent#system-data) Zabbix agent items with the script, for example:
    -   `system.run[myscript.sh]`
    -   `system.run[myscript.sh,wait]`
    -   `system.run[myscript.sh,nowait]`

```default
AllowKey=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:

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

[comment]: # ({/038b9efe-3cc5f239})

[comment]: # ({684f865a-1965a7d7})
##### Securing allow/deny rules

This example shows how to secure overly permissive `AllowKey` or `DenyKey` rules.

Consider the following rules:

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

::: noteclassic
On Windows, you must escape spaces in the path using a caret (`^`).
:::

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 only item keys without parameters; however, all [`vfs.file`](/manual/config/items/itemtypes/zabbix_agent#virtual-file-system-data) items require parameters.
-   The `system.cpu.load[*]` pattern matches only item keys with parameters; however [`system.cpu.load`](/manual/config/items/itemtypes/zabbix_agent#system-data) 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:

```default
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[*]
```

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

```bash
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]
```

[comment]: # ({/684f865a-1965a7d7})

[comment]: # ({23f78b84-16bccaff})
##### Pattern examples

The following table shows 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).

|Pattern|Matches|Examples|
|--|----|----|
|`*`|Any key with or without parameters| |
|`vfs.file.*`|Key starts with `vfs.file.`<br>No parameters|Matches:<br>`vfs.file.size`<br>`vfs.file.contents`<br><br>Does not match:<br>`vfs.file.contents[]`<br>`vfs.file.size[/var/log/app.log]`|
|`vfs.*.contents`|Key starts with `vfs.`<br>Key ends with `.contents`<br>No parameters|Matches: <br>`vfs..contents`<br>`vfs.mount.point.file.contents`<br><br>Does not match:<br>`vfs.contents`<br>`vfs.file.contents[]`|
|`vfs.file.*[*]`|Key starts with `vfs.file.`<br>Any or empty parameters|Matches<br>`vfs.file.get.custom[]`<br>`vfs.file.size[/var/log/app.log, utf8]`<br><br>Does not match:<br>`vfs.file.get.custom`|
|`vfs.file.contents`|Key is `vfs.file.contents`<br>No parameters|Matches:<br>`vfs.file.contents`<br><br>Does not match:<br>`vfs.file.contents[/etc/passwd]`|
|`vfs.file.contents[]`|Key is `vfs.file.contents[]`<br>Empty parameters|Matches:<br>`vfs.file.contents[]`<br><br>Does not match:<br>`vfs.file.contents`|
|`vfs.file.contents[*]`|Key is `vfs.file.contents`<br>Any or empty parameters|Matches:<br>`vfs.file.contents[/path/to/file]`<br><br>Does not match:<br>`vfs.file.contents`|
|`vfs.file.contents[/etc/passwd,*]`|Key is `vfs.file.contents`<br>First parameter is `/etc/passwd`<br>Any or empty second parameter|Matches:<br>`vfs.file.contents[/etc/passwd,]`<br>`vfs.file.contents[/etc/passwd,utf8]`<br><br>Does not match:<br>`vfs.file.contents[]`<br>`vfs.file.contents[/etc/passwd]`|
|`vfs.file.contents[*passwd*]`|Key is `vfs.file.contents`<br>First parameter includes `passwd`<br>No second parameter|Matches:<br>`vfs.file.contents[/etc/passwd]`<br><br>Does not match:<br>`vfs.file.contents[/etc/passwd,]`<br>`vfs.file.contents[/etc/passwd,utf8]`|
|`vfs.file.contents[*passwd*,*]`|Key is `vfs.file.contents`<br>First parameter includes `passwd`<br>Any or empty second parameter|Matches:<br>`vfs.file.contents[/etc/passwd,]`<br>`vfs.file.contents[/etc/passwd,utf8]`<br><br>Does not match:<br>`vfs.file.contents[/etc/passwd]`<br>`vfs.file.contents[/tmp/test]`|
|`vfs.file.contents[/etc/passwd,utf8]`|Key is `vfs.file.contents`<br>First parameter is `/etc/passwd`<br>Second parameter is `utf8`|Matches:<br>`vfs.file.contents[/etc/passwd,utf8]`<br><br>Does not match:<br>`vfs.file.contents[/etc/passwd,]`<br>`vfs.file.contents[/etc/passwd,utf16]`|

[comment]: # ({/23f78b84-16bccaff})