weakforced

Anti-Abuse for servers at authentication time

View on GitHub

% WFORCE(1) % Open-Xchange % 2018

NAME

wforce - daemon to detect brute-force login attempts and enforce other policies for logins

SYNOPSIS

wforce [OPTION]…

DESCRIPTION

wforce implements a simple HTTP server that accepts JSON formatted commands that report successful/unsuccessful logins and query whether a login should be allowed to proceed.

wforce can act as both a client and server. As a server it typically runs under systemd control, although it can also be run as a traditional daemon or in ‘interactive’ mode. As a client, it connects to a wforce server and provides the same interactive commands.

wforce is scriptable in Lua, see the wforce.conf file for a simple example, and wforce.conf.example for a more sophisticated example. In fact all configuration is done using the Lua language, as wforce.conf is simply a Lua script.

SCOPE

wforce depends on the systems performing login authentication to integrate with it using the HTTP/JSON API. Example clients of the API include Dovecot and OX AppSuite.

wforce provides a simple clustering mechanism through the process of configuring “siblings” in wforce.conf. All modifications to the blacklists or the string stats DB (either from Lua or the REST API) will be replicated to all configured siblings. Replication uses the UDP protocol, so if siblings are not on a local subnet, you should ensure that any firewalls forward UDP on the configured ports.

OPTIONS

-c
Act as a client, connecting to a wforce instance at the IP/Port specified in the ‘controlSocket’ function in wforce.conf. A custom configuration file can be specified.
-C,–config FILE
Load configuration from FILE.
-R,–regexes FILE
Read device parsing regexes from FILE (usually regexes.yaml).
-s
Run in foreground, but do not spawn a console. Use this switch to run wforce inside a supervisor (use with e.g. systemd and daemontools).
-d,–daemon
Operate as a daemon.
-e,–execute CMD
Connect to wforce and execute CMD.
-f,–facility FACILITY NAME
Log using the specified facility name, e.g. local0
-l,–loglevel <0-7>
Logs sent to stdout will be filtered according to the specified log level, matching the equivalent syslog level (0 - Emerg to 7 - Debug).
-h,–help
Display a helpful message and exit.

CONSOLE COMMANDS

The following commands can be run from the console when wforce is started with the -c option.

BUGS

The replication function of clustering means that as more servers are added to a cluster, incremental performance gains may be less each time, eventually possibly leading to performance degradation. This is because each server keeps a full copy of the stats DBs and the blacklists, and changes to those are replicated to all siblings. This can be mitigated by partitioning siblings into smaller clusters that do not share information, at the expense of missing potential abuse activity.

SEE ALSO

wforce.conf(5) wforce_webhook(5) wforce_api(7)