fail2ban-node

A maintained Node.js client for fail2ban, wrapping the fail2ban-client CLI.

Why

Existing npm packages for fail2ban are unmaintained and rely on fragile Python pickle socket communication. This package uses the official fail2ban-client CLI — the stable, version-agnostic interface.

Requirements

• Node.js >= 18
• fail2ban-client installed on the system (Linux only)

Install

pnpm add fail2ban-node
# or
npm install fail2ban-node

Usage

const fail2ban = require('fail2ban-node');

// Check if fail2ban is running
const alive = await fail2ban.ping();

// Get all jails
const { total, list } = await fail2ban.status();
// { total: 2, list: ['sshd', 'nginx-http-auth'] }

// Get jail details
const jail = await fail2ban.jailStatus('sshd');
// {
//   currentlyFailed: 3,
//   totalFailed: 81,
//   fileList: ['/var/log/auth.log'],
//   currentlyBanned: 2,
//   totalBanned: 15,
//   bannedIPs: ['1.2.3.4', '5.6.7.8']
// }

// Ban an IP
await fail2ban.ban('sshd', '1.2.3.4');

// Unban an IP
await fail2ban.unban('sshd', '1.2.3.4');

// Reload configuration
await fail2ban.reload();

// Unban all IPs across all jails
await fail2ban.unbanAll();

API

Method	Description
ping()	Check if fail2ban is running. Returns boolean.
status()	Get total jail count and jail list.
jailStatus(jail)	Get detailed status for a specific jail.
ban(jail, ip)	Ban an IP in a jail.
unban(jail, ip)	Unban an IP from a jail.
reload()	Reload fail2ban configuration.
unbanAll()	Unban all IPs across all jails.

License

GPL-2.0 — same as fail2ban itself.