README

Logs security events to a configurable sink for further processing.

A common use case is to ban bad actors on an internet-facing reverse proxy server, if the internal webmail server has logged too many failed authentication attempts.

In reverse proxy configurations the actual client IP is resolved if the request originates from a trusted proxy.

Security Events

A security event provides a message and contains the following standard fields:

timestamp text
The timestamp of the event in ISO-8601 format. Depending on the log sink, the timestamp may be part of the sink payload and the format may vary.
client_ip text
The IP address of the client (resolved in reverse proxy configurations), or the text UNKNOWN, if the client IP cannot be determined.

Depending on the event, additional data may be logged as well.

User Login Failure

Logged whenever RoundCube triggers a login_failed event.

Event message: Login failed

host text
The server hostname to authenticate against.
user text
Name of the user for which the authentication attempt failed.
code integer
The RoundCube error code.

Log Sinks

A log sink receives security events and stores these for further processing.

Unless the log sink is structured, data fields are appended to the message as key=value pairs that are separated by a comma and space. Values with text data are enclosed in double quotes (existing double quotes are replaced by single quotes).

File

Unstructured sink that appends security events to a configured file, one event per line.
Each line starts with the timestamp and client IP, followed by the message and key-value pairs of additional data fields.

<ISO-8601 timestamp> <SP> <Client IP> <SP> <Message> ":" <SP> <Additional Data Fields>

Syslog

Unstructured sink that utilises the standard system log facilities. The timestamp is managed by syslog and the client IP is formatted as an additional data field.

Unless overwritten in configuration, events are reported to LOG_USER on Windows and LOG_AUTHPRIV or LOG_AUTH on other platforms.

Installation

The plugin can either be installed via Composer or manually. If the webmail server allows outgoing requests, Composer is the more comfortable option as it automatically resolves dependencies and simplifies updates.

Using Composer

⚠️ Note that it is not recommended to run Composer as root. Plugin installation requires script support enabled, as the RoundCube installer needs to move the downloaded plugin to the plugins directory and optionally can enable the plugin automatically.

Get Composer.
Within the RoundCube webmail root directory, add a new dependency to the plugin. Use dev-main as the version constraint for the latest in-development version.
```
php composer.phar require 'takerukoushirou/roundcube-security_log:^1.0'
```
Composer may ask whether to enable the plugin. Confirm with y.

To update the installed plugin to the latest version, simply run:

php composer.phar update --no-dev

Manual

Download the latest release archive or checkout the latest release branch.
Extract the contents into a folder named roundcube_security_log within the plugins directory of your RoundCube installation.

There are no external dependencies.

Repeat manual installation for updates. It may be advisable to keep multiple versions of the plugin in separate folders and use a symlink named roundcube_security_log from within the plugins directory to the latest version folder instead.

Configuration

To enable the plugin, add roundcube_security_log to the $config['plugins'] array in the RoundCube configuration file.
When using Composer, the installation routine will ask whether to automatically enable the plugin.

Options

On a fresh installation, navigate to the plugin directory and copy config.inc.php.dist to config.inc.php.
When using Composer, a copy is automatically created.

Edit config.inc.php within the plugin directory as needed.
All options and their accepted values are described in config.inc.php.dist.

Act on Security Events

Security log entries generated by this plugin on the (internal) webmail server can be used to, for example, automatically ban bad actors from accessing the internet-facing reverse proxy.

Fail2Ban

Included with this plugin is a Fail2Ban filter and jail definition that can be used to automatically ban hosts after a configured amount of failed login attempts within a specified time window.

Copy the filter from the fail2ban/filter.d directory and the two jail definitions from the fail2ban/jail.d directory to the corresponding directories of your Fail2Ban installation on the internet-facing server. To configure ban time, search window and allowed login retries, or what action to perform, modify roundcube-security_log.local and restart Fail2Ban. Failures are recorded under the Fail2Ban jail roundcube-security.

Note that if no reverse proxy is used and no other feature of this plugin is needed, a filter for the default RoundCube log is included with Fail2Ban and could be used directly instead of this plugin.

Reverse Proxy

This plugin can be used to communicate failed login attempts to a or multiple reverse proxy servers to ban bad actors.

Included with this plugin are configuration file examples for rsyslogd:

roundcube-security-forward.conf (for webmail server)
A forwarder example that forwards all syslog messages generated by this plugin to the reverse proxy using the RELP. Configure target host and port number as needed.
roundcube-security-sink.conf (for reverse proxy)
Receives forwarded security log messages and writes these to a local log file. Configure port number and target log file as needed.

On the reverse proxy, Fail2Ban can be used to consume the forwarded log messages and to automatically ban bad actors.

License

GNU General Public License v3 or higher. See LICENSE file for details.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

takerukoushirou / roundcube-security_log

Maintainers

Details