cPGuard Standalone Configuration

What is cPGuard standalone configuration?

 cPGuard has default support to 3 major control panels which are cPanel, DirectAdmin, and Plesk. There are specific scripts for these control panels to integrate cPGuard scanner, WAF, and other modules to work with them without any other manual configuration. But for any other control panels or web servers without any control panel, the server administrator must provide some details to configure cPGuard to work with that environment.  The cPGuard standalone configuration refers to that custom values and is located at /opt/cpguard/cpguard.ini

Major configuration sections in cpguard.ini

To function cPGuard on a standalone server, we need to know the web server name, web server configuration path, option to build the directory watchlist for automatic scanning, and WAF server details. Each section are given below in detail

Web server name – web_server 

This is the Web Application Server name in which you have configured your Websites/Virtual hosts. The supported Web Servers are Apache,Nginx, and Litespeed.

Web server configuration – web_server_conf 

This is a file or directory path in which you have configured your websites. As a web security suite, cPGuard needs to fetch the virtualhost configurations to detect the websites configured and the document root of each website. This input is processed to create the watchlist ( the list of directories to scan for automatic virus scan ) and the domain associated with each. This helps cPGuard to scan only the website files and eliminate the overhead of monitoring unwanted files.

Example values for this parameter are given below

/etc/apache2/sites-enabled/*.conf,
/home/*/apache.conf,
/etc/apache2/apache2.conf;
/etc/nginx/nginx.conf

Domain, Document-root & User source – domain_list

This is an optional but recommended input for the list of domain names, document roots, and associated users with them. If you set a value for this parameter, this will be the source to build the directory watchlist for automatic scanning. We have scripts that will try to detect the virtual host definitions based on the value given for “web_server_conf”; but the “domain_list” configuration will override that and use it to build the watch list.

We recommend setting this value to ensure that all required directories are watched by the scanner engine in custom environments. We made this simple so that you can create this input with little scripting. We expect a path to a JSON file or a script that can generate a JSON input in the following format.

[
{
“domain”: “example.com”,
“docroot”: “/home/username/public_html/”,
“user”: “username”
},
{
“domain”: “subdomain.example.com”,
“docroot”: “/home/username/subdomain/”,
“user”: “username”
}
]

WAF server name – waf_server

The server in which ModSecurity is installed and WAF rules should be loaded. Please note that cPGuard WAF requires ModSecurity 2.9.4 or higher to load the rules. Leave empty if ModSecurity is not installed but note that the cPGuard WAF module will be disabled if this is not set. You can later install ModSecurity, and modify this configuration value.

Allowed options are apache, nginx, and litespeed.

WAF Server configuration – waf_server_conf

The file into which we can include cPGuard WAF ModSecurity configuration file. Please be careful with this value as a wrong entry can cause a Web Server crash. The file path must be suitable to “Include” our custom configuration file, where we define the WAF configuration. If you provide a new file location, we will create the file and add the configuration…otherwise we append the Include configuration to the existing file mentioned.

WAF webserver restart command – waf_server_restart_cmd

This is the command to restart the WAF server which is needed after you change the WAF configuration. Please make sure to give the complete path of the command ( like /usr/sbin/service nginx restart ) to avoid any errors.

WAF Audit Log location – waf_audit_log

This is the ModSec audit log file path in which the WAF server will log all WAF/ModSec activities. The WAF log collection script will refer to the given file to collect the WAF log, and save it into the local WAF database to display it in the WAF logs page in UI. If you leave this path empty, cPGuard will attempt to search for the audit log file in standard locations.

Examples
/var/log/modsec_audit.log
/var/log/nginx/error_log
/var/log/nginx/modsec_audit.log

User & Email data – user_list

You need to specify the path of  JSON file or path to a script that will generate JSON in the following format. The input must contain the user names and contact email addresses for each user. cPGuard uses for creating user list, sending user notification emails etc. If you leave this field empty, the modules that use this data will be disabled

The JSON structure should be similar to the following:
[
{
“user”: “exampleuser1”,
“email”: “[email protected]”
},
{
“user”: “exampleuser2”,
“email”: “[email protected]”
}
]

Automatic account suspension script – suspend_hook

A PHP code that can be triggered/executed when a user suspend event occurs in cPGuard. This is an optional feature and can be enabled if you wish to configure automatic account suspension on your server. Please refer /opt/cpguard/app/scripts/suspend_hook_sample.php for sample code