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.

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.

The Monarx solution supports two types of quarantine directories: global and per-user. Our default (no defined directory) results in no local directory creation - which is our recommended configuration. Restoration of a quarantined file should always be done view our web app / API.

If a global quarantine directory is defined and exists then all files that are cleaned will be copied there before being cleaned (compromised) or removed (malicious).

Independently, if a per-user quarantine directory exists we'll write files there. Per user quarantine directories take priority over global, so if defined we will not create or maintain a global quarantine directory. It is possible to have the Monarx solution create per-user quarantine directories when needed. This is done by adding three additional values to the quarantine.user configuration: <uid>, <gid> and <mode>. The <uid> and <gid> can be integers or the string $USER, indicating that the directory should have the same user and group as the user’s home directory. The mode is expressed as an octal number the same way as with the chmod user command. The file that is written to the quarantine directory will have the same owner and permissions as the original file. The original file name is also retained with an additional component for uniqueness.

If any user quarantine directories are defined then the Monarx system will automatically add them as excluded directories to avoid looping on previously discovered files. The quarantine.user field must contain $USER in the path.

All global quarantine directories must reside outside of all configured user bases.

Let’s say that the system has a quarantine-user with entries in the /etc/passwd and /etc/group files as follows:

quarantine:x:100:100:quarantine:/var/log/.quarantine:/bin/bash

quarantine:x:100:

With the following quarantine.user setting the directories are created under the users but are owned by the quarantine user and group. Since the .quarantine-directory is accessible only to the owner (0700) the users cannot access those files directly.

​quarantine.user = $USER/.quarantine/ 100 100 0700

If the quarantine.user specifies an absolute path then the $USER represents the user name of the user that owns the directory and the quarantine directory can be anywhere in the file system. The following creates users' quarantine directories in “/var/log/.quarantine/” thus allowing them to be easily accessible in a single place yet be separated by the user.

When used that way there is no need for a separate global quarantine directory.