Skip to content

Fail2Ban Log Triggered Automatic Banning

github-actions[bot] edited this page Nov 18, 2026 · 3 revisions

Watches your logs, bans the IPs that earn it โ€” the lightest-weight IPS in this repo

Part of the ULTIMATE CYBERSECURITY MASTER GUIDE ยท Incident Response ยท IDS & IPS section

Blue Team IDS/IPS Fail2Ban


๐ŸŽฏ Purpose

Guide for deploying Fail2Ban, a lightweight host tool that monitors configured logs or a supported backend, matches failures with filters, and runs configured actions when a jail threshold is reached. Firewall rules are a common action; the selected action and platform determine the actual response.

โš™๏ธ Function

Covers install, the jail/filter/action configuration model, protecting SSH (the most common use case) plus other common services, testing a jail actually works, and the operational commands for inspecting and manually unbanning.

๐Ÿ† Goal

Configure a jail for a service whose authentication failures are recorded in a supported source and matched by an appropriate filter. Fail2Ban can add a host-level response to repeated failures; it does not replace strong authentication, application rate limits, or network-level monitoring.

๐Ÿ“‹ When to Use

  • Consider it for exposed services when their logs or journal entries are available, a matching filter is appropriate, and the configured action fits the host.
  • Use service-specific jails only after confirming the applicationโ€™s log format, filter, and supported backend on the installed Fail2Ban version.
  • You want some automatic response to brute-forcing without deploying a full network IDS/IPS stack
  • A honeypot or IDS from elsewhere in this repo flagged repeated brute-force attempts and you want the actual mitigation, not just visibility

๐Ÿ“‹ Table of Contents


๐ŸŽฏ Where This Fits

Fail2Ban is not a replacement for Suricata/Snort or Security Onion. It does not inspect packets or understand protocols. A jail connects a configured log or supported backend to a filter and one or more actions. When the filter records enough failures within the configured window, the action runs; a firewall ban is common, but behavior depends on the selected action and host. Fail2Ban is useful for targeted, host-level responses to events its filters can reliably identify. It does not provide universal application coverage or replace strong authentication, application controls, or network monitoring.

Fail2Ban event-to-action flow: a configured log source is matched by a filter, thresholded by a jail, and passed to a configured action; the action may ban and later unban an address.

Conceptual flow only: the source, filter, thresholds, action, and ban duration depend on the service, installed version, and host configuration.


๐Ÿš€ Deployment Workflow

1. Install:
   โ””โ”€> apt install fail2ban (or your distro's equivalent).

2. Copy the default config to your override file:
   โ””โ”€> jail.conf -> jail.local. Never edit jail.conf directly โ€”
       package updates will overwrite it.

3. Set your baseline [DEFAULT] policy:
   โ””โ”€> ignoreip (your own management IPs โ€” don't lock yourself out),
       bantime, findtime, maxretry.

4. Enable the jails you need:
   โ””โ”€> Enable only jails for services actually running, after confirming
       the log source, filter, and action match the host.

5. Restart and validate:
   โ””โ”€> systemctl restart fail2ban
   โ””โ”€> Deliberately fail auth a few times from a test IP, confirm
       the ban actually happens.

6. Operate:
   โ””โ”€> fail2ban-client status <jail> to check state.
   โ””โ”€> Unban manually when you lock out something legitimate.

๐Ÿ”ง Installation

sudo apt-get update
sudo apt-get install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Key files, all under /etc/fail2ban/:

File Purpose
fail2ban.conf Global daemon settings โ€” don't edit
fail2ban.local Your overrides to the above, if needed
jail.conf Default jail definitions โ€” don't edit
jail.local Your jail overrides โ€” edit this one
filter.d/ Regex filter definitions (one per service type)
action.d/ Ban action definitions (iptables, sendmail, etc.)

The pattern throughout Fail2Ban's config is the same as much of this repo's other tooling: never edit the .conf shipped by the package, always override in the matching .local file so package updates don't silently discard your changes.


๐Ÿงฉ The Jail / Filter / Action Model

  • A jail ties a service to a filter and a response โ€” "watch this log, using this pattern, and do this when it matches."
  • A filter is the regex that recognizes a failure in that service's log format.
  • An action is the configured response for a ban or unban event. Firewall rules are common, but the action can vary by platform and configuration.

Baseline [DEFAULT] section in jail.local:

[DEFAULT]
# Never ban these โ€” your own management IPs, always
ignoreip = 127.0.0.1/8 ::1 192.168.1.0/24

# How long a ban lasts (seconds)
bantime = 3600

# The window failures are counted within (seconds)
findtime = 600

# Failures allowed before a ban triggers
maxretry = 5

# Optional email on ban (needs working local mail/SMTP)
# destemail = you@example.com
# sender = fail2ban@example.com
# mta = sendmail
# action = %(action_mwl)s

Set ignoreip before enabling anything else. This is the single most important line in the file โ€” get it wrong and you can ban your own management access.


๐Ÿ”’ Protecting SSH

The default, and most common, use case:

[sshd]
enabled = true
port = ssh
filter = sshd
logpath = /var/log/auth.log
maxretry = 3
bantime = 3600
findtime = 600

Distro-specific source: Check the installed packageโ€™s defaults: authentication log locations and backends vary by distribution and version. Use the configured path for file-based monitoring. With the systemd backend, follow the installed filterโ€™s journal matching configuration; upstream documents that logpath is not valid with this backend. Do not combine a guessed file path with a journald backend.

If you moved SSH to a non-standard port (a pattern used elsewhere in this repo's honeypot guides โ€” see Cowrie and OpenCanary), update port to match.


๐ŸŒ Protecting Other Services

Fail2Ban ships filters for dozens of services out of the box. A couple of common additions:

[apache-auth]
enabled = true
port = http,https
filter = apache-auth
logpath = /var/log/apache2/error.log
maxretry = 5
bantime = 3600

[nginx-http-auth]
enabled = true
port = http,https
filter = nginx-http-auth
logpath = /var/log/nginx/error.log
maxretry = 5
bantime = 3600

Only enable jails for services actually running on the box โ€” an enabled jail watching a log file that never gets written to is harmless but pointless.


โœ… Validating & Operating

Check jail status:

sudo fail2ban-client status sshd

Output shows currently-failed counts, total failures, and the list of currently-banned IPs.

See the actual firewall rules Fail2Ban created:

sudo iptables -L f2b-sshd -n --line-numbers

Manually unban an IP (e.g. you locked out something legitimate, or a test ban you triggered on purpose):

sudo fail2ban-client set sshd unbanip <ip-address>

Dump the fully-resolved effective config โ€” invaluable when a jail isn't behaving as expected, since it shows the merged result of jail.conf โ†’ jail.local โ†’ jail.d/*.conf:

sudo fail2ban-client -d

Test a filter's regex against real log lines before trusting it in production โ€” a bad regex either misses real attacks or bans legitimate users:

fail2ban-regex /var/log/auth.log /etc/fail2ban/filter.d/sshd.conf

๐Ÿฉน Common Gotchas

Symptom Cause Fix
Locked out of your own SSH session Your own IP wasn't in ignoreip and you triggered the threshold (common while testing) Add your management IP(s) to ignoreip before testing; if already locked out, access via console/out-of-band and run the unban command above
Jail shows enabled = true but never bans anything logpath points at a file that doesn't exist or isn't being written on this distro (e.g. Ubuntu-style path used on RHEL) Confirm the actual log path/backend for your specific distro โ€” see the SSH section's distro-specific note above
Edits to jail.conf disappear after a package update jail.conf is the package-managed default, meant to be read-only Always edit jail.local (or drop files in jail.d/) instead โ€” never jail.conf directly
Filter doesn't match despite obviously-failed log lines present Log format differs slightly from what the bundled filter regex expects (common after a service version upgrade) Use fail2ban-regex against the actual log file and filter to see exactly where the match fails
Bans aren't persistent across service restarts This is expected default behavior โ€” Fail2Ban's ban list is in-memory unless configured otherwise Acceptable for most use cases; if persistence matters, look into Fail2Ban's database (dbfile) settings rather than assuming this is a bug

โš ๏ธ Security Notes

โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
                    โš ๏ธ CRITICAL WARNING โš ๏ธ
โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

โ–บ SET ignoreip BEFORE ANYTHING ELSE. This is the single most
  common way people lock themselves out of their own systems
  with this tool. Add every management IP you access the box
  from before enabling any jail.

โ–บ THIS IS A COMPLEMENT, NOT A REPLACEMENT. Fail2Ban stops
  simple brute-forcing; it does nothing against a slow, low-and-
  slow attack that stays under the threshold, or an attacker
  rotating source IPs. Pair it with the other detection layers
  in this repo, don't treat it as sufficient on its own.

โ–บ TEST FROM A SEPARATE SESSION. When validating a new jail,
  trigger the failure condition from a connection you're
  prepared to lose โ€” never from the only session you have open
  to the box.

โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

๐Ÿ“š Resources

  • Fail2Ban GitHub: github.com/fail2ban/fail2ban
  • Bundled filter/jail reference: /etc/fail2ban/jail.conf and /etc/fail2ban/filter.d/ on any installed system โ€” the shipped comments are thorough and version-accurate for your install

Related Files


๐Ÿ›ก๏ธ Use These Resources Responsibly

Detection first, blocking second.

Repository: ULTIMATE CYBERSECURITY MASTER GUIDE

Maintained by: Pacific Northwest Computers

โญ Star this repo if you find it useful! โญ


๐Ÿ“„ Source: IncidentResponse/IDS&IPS/fail2ban.md | โœ๏ธ Suggest an edit | โฌ…๏ธ Back to Incident Response

Clone this wiki locally