This document explains how the Monarx Agent is configured locally in /etc/monarx-agent.conf.

In order to function the agent requires the customer to insert identification credentials (obtained from Monarx) into the configuration file. That is the only piece of information that is absolutely needed; the rest of the configurable fields have meaningful default values to provide basic operation.

The Monarx system uses a concept called User Base to define the parts of the file system that is included in scanning and run-time processing. There are two default user bases: “/home/” (for cPanel) and “/var/www/” (Plesk) that are used if nothing has been configured in the monarx-agent.conf file.

You can configure user bases in the configuration file using either base or users. Both create a new User Base but provide different capabilities. base is used to provide a path up to the user directories and all directories immediately below the base are treated as users. The users do not have to correspond to defined user accounts for proper functioning of the Monarx solution but in standard environments they match one to one. Using the base allows the system to detect new user accounts (as well as removed ones) without any manual configuration. users explicitly tells which users are participating. This option is useful when testing with a limited number of users.

Both base and users can contain regular expressions for individual directories along the path. To use a regular expression for a directory, the entire path component has to be enclosed in parenthesis.

/(home[12])/ is recognized as a regular expression.

/home[12]/ is NOT a recognized as a regular expression.

/home([12])/ is NOT a recognized as a regular expression.

To illustrate, let’s say that you want to only include “user1” and “user2” but not "user3".

The same result can also be achieved with base but an additional field exclude_users is needed.

This works the same until additional users are added: if “user4” is added then it will be automatically included in the processing when base is used, but with users there is no change.

Since the base can also contain regular expressions, additional directory trees can be included in the same User Base.

Note that all “user3” directories will be excluded: if “home2” above were to have “user3” directory it would also be excluded. Since exclude_users cannot contain any directory separators you would need to create two distinct User Bases in order to exclude “user3” only under “home”.

Why ^user3$ and not just user3? Since excluded_users is a regular expression we need to specify that the directory name contains nothing more than “user3” by using the begin and end operators. user3 would match e.g. “accuser301” and “abuser3” along with anything else containing the string “user3”.

When a user base is explicitly configured then the default user bases are no longer used. Also if any additional configuration is needed above and beyond the system defaults then the user bases have to be explicitly configured.

We recommend setting host_id in monarx-agent.conf when first installing our agent. When an explicit host_id is not defined, we default to the hostname of a given instance - which if changed (or local identity we hold is deleted) would cause a duplicate Agent record in our agents module.

It is highly recommended to set host_id to a static value WHEN the hostname is not unique to this host/server/container, or WHEN the hostname is fluid (e.g. containerized environments). Any change to the host_id value AFTER INSTALLATION will result in a new agent being registered in the Monarx system.

There may be directories under the user directories that should not be processed by the hunter. A prime example would be a quarantine directory that contains previously discovered compromised or malicious files. The system looks for configured excluded directories in the file path after the user directory, so it cannot be used to exclude user bases or users.

The part of the path that exclude_dirs is tested against starts with the directory separator between the user directory and the rest of the path and ends at the directory separator right before the file name.

The exclude_dirs is a regular expression but unlike exclude_users it can contain directory separators. In the above example the exclude_dirs /(\.quarantine|backup)/ would match “/.quarantine/” or “/backup/” anywhere in the path following the user directory. If you need to exclude these directories only when they are directly below the user directory then exclude_dirs must be written as ^/(\.quarantine|backup)/.

It is possible to have the exclude_dirs be e.g. just “backup” in which case any directory containing “backup” would be excluded: “/mybackup/”, “/oldbackup/” and “/backup-old/” would all be excluded.

During the recursive hunter scan the exclude_dirs regular expression is evaluated for the current path which will dynamically grow or shrink. Because of this the “end of path” varies and using “$” to indicate end of path may yield unexpected results. Consider the following:

As the scan progresses the path to be evaluated changes. The “^” to indicate the beginning of the path can always be counted on, but as the green high lightnings suggest, the end of the path keeps changing.