rwserve-brute-force v1.0.14
Open Source RWSERVE plugin
Brute Force
Detect and block repetitive POSTs
Motivation
Attempts to circumvent your website's authorization process are a fact of life.
Detecting and dealing with them are necessary. One common hacking method is
simple brute force trial and error. When a series of unsuccessful requests to
login occurs in a short period of time, this plugin will add the user-agent's
remote address to a blacklist: subsequent requests to login will be blocked with
status code 403 Forbidden
.
Sometimes a legitimate user may trigger this detector and accidentally lock themselves out. For this reason, the blackout is automatically removed after a given period of time.
Often these cracking attempts will be routed through a botnet, where each
request comes from a large collection of different IP addresses. For those
types of attacks, you can set the max-visits
variable to a low value, to detect
and block attempts aggressively.
In order to monitor the usefulness of this plugin you can enable the log-failures
configuration switch. When true
the IP address of each blocked request will be
printed to the website's log.
Customization
This plugin is open source and can be modified or enhanced to perform tasks such as these:
- Permanently block IP addresses that request a honeypot resource.
- Redirect a blacklisted user via
303 See Other
to a customer service help page. - Detect botnet thunderstorms and automatically increase threshold sensitivity.
Download
The plugin module is available from NPM
. Before proceeding, you should already have Node.js
and RWSERVE
configured and
tested.
This module should be installed on your web server in a well-defined place, so
that it can be discovered by RWSERVE
. The standard place for public domain
plugins is /srv/rwserve-plugins
.
Configuration is Everything
Make the software available by declaring it in the plugins
section of your
configuration file. For detailed instructions on how to do this, refer to the plugins
documentation on the Read Write Tools HTTP/2 Server
website.
TL;DR
The config
settings can be adjusted using this guidance.
max-visits
is a positive integer. This is the number of requests to the target
resource allowed during the grace period before being blocked. A typical setting
might be 3 to 6, while an aggressive setting would be 1.
grace-period
is an integer number of seconds specifying a window of time during
which requests are counted. The counter for each IP address is reset to zero
when this much time has elapsed since the first request. If the counter exceeds
the max-visits threshold, a blackout is begun.
blackout-period
is an integer number of seconds specifying the window of time
during which all requests to the target resource, by the blacklisted IP, are
blocked. When this time period has elapsed, the IP address is removed from the
blacklist and subsequent requests are honored, starting with a new grace period.
log-failures
is a switch that may be either true or false
. If true, each request by an IP address during a blackout period is recorded in
the web log. If false, blackouts are silently enforced without recording to the
web log.
The router
section lists one or more target resources that will participate in
the brute force scheme. In the above example, all HTTP POST
requests for
resource paths beginning with /rbac/credentials
will participate.
Cookbook
A full configuration file with typical settings for a server running on
localhost port 7443, is included in this NPM module at etc/brute-force-config
.
To use this configuration file, adjust these variables if they don't match your
server setup:
Usage
Server
Start the server using the configuration file just prepared. Use Bash to start the server in the background, like this:
Forcing a blackout
Use CURL to submit a sequence of POST requests to your sever. The first five
requests will return with 403 Forbidden
with a response header rw-rbac-forbidden
indicating that invalid credentials were provided. The sixth and subsequent
requests will return 403 Forbidden
without any supplemental header. Close
examination of the server's logged messages will reveal something like error RwserveBruteForce RA=127.0.0.1; CT=6
indicating the remote address (RA) and count (CT) for the blocked request.
Deployment
Once you've tested the plugin and are ready to go live, adjust your production
web server's configuration in /etc/rwserve/rwserve.conf
and restart it using systemd
. . .
. . . then monitor its request/response activity with journald
.
Prerequisites
This is a plugin for the Read Write Tools HTTP/2 Server, which works on Linux platforms.
Review
License
The rwserve-brute-force plugin is licensed under the MIT License.