Linux Intrusion Prevention on nftables

NFTBan is an open-source Linux Intrusion Prevention System (IPS) and nftables firewall manager. nftables in the kernel makes packet decisions; userspace components detect, classify, synchronize state, and report health. Dual-table architecture with kernel-level nft sets, commit-confirm safety, and Polkit privilege separation.

Download Latest Release Documentation
$ nftban status
Tables: ip nftban, ip6 nftban
Sets: 32 (16 IPv4 + 16 IPv6)
Modules: login portscan ddos suricata botguard feeds

$ nftban stats --brief
Blacklist: 437,291 IPv4 / 12,847 IPv6
Whitelist: 23 IPv4 / 4 IPv6
Open ports: TCP 3 / UDP 0

How NFTBan Works

Userspace modules detect and classify threats. The Go daemon is the centralized owner of runtime ban and set-update operations. nftables enforces packet decisions at the kernel level. Metrics and health checks provide observability.

Architecture

NFTBan operates as a control plane for nftables. Detection modules emit events through an IPC socket to the Go daemon (nftband), the centralized owner of runtime ban and set-update operations, which coalesces operations before writing to kernel nft sets. Schema loading and controlled lifecycle operations use separately defined paths.

Data Flow

Detection & monitoring modules (login, portscan, ddos, suricata, botguard, feeds, geoban)
    │
    ▼
Event pipeline (deduplicates and coalesces events across sources)
    │
    ▼
Operation queue (batches ban / set-update operations)
    │
    ▼
Source router (maps sources to target set families)
    │
    ▼
nftables kernel (ip nftban + ip6 nftban — packet enforcement)
    │
    ▼
Prometheus / health / watchdog

Dual-Set Architecture

Two set types handle different workloads:

  • Interval sets (blacklist_ipv4, blacklist_ipv6) — CIDR-aggregated data from threat feeds and geoban. Auto-merge enabled. Permanent entries.
  • Hash sets (blacklist_manual_ipv4, blacklist_manual_ipv6) — Individual IPs from auto-detection modules. O(1) lookup. Kernel-managed timeout expiry.

Detection & Monitoring Modules

Named detection and monitoring modules: DDoS protection, BotGuard, BotScan, Portscan detection, Login monitoring, Blacklist & threat feeds, GeoBan, Suricata integration, RBL monitoring, and DNS-tunnel detection. Enforcing modules update kernel sets; observe-only modules produce findings and reports, not packet decisions.

DDoS Protection

Protects against L3/L4 floods, with SYN-flood handling and optional SYNPROXY. Packet enforcement is in nftables (kernel); existing packet enforcement does not depend on the daemon staying active. The daemon provides management, penalty-set writes, and telemetry.

BotGuard (HTTP Guard)

Detects and classifies HTTP abuse. The daemon manages classification across its state model; nftables enforces current set membership at the kernel level.

BotScan (HTTP Exploit Scanner)

Scans web access logs (Apache/Nginx) for exploit probes and scanner patterns. The scheduled scanner hands evidence to the daemon for centralized enforcement.

Portscan Detection

The nftables chain emits rate-limited detection evidence; a userspace consumer analyzes events and issues new bans through centralized enforcement. Previously issued bans keep being enforced by the kernel.

Login Monitoring

Go daemon detection with centralized enforcement. Sources include SSH, mail, FTP, control panels, web-auth, and supported Suricata signals, with configurable scoring and ban duration.

Blacklist & Threat Feeds

Synchronizes manual bans and threat-intelligence feeds into kernel enforcement sets, with CIDR aggregation and whitelist exclusion during sync. A validated replacement preserves the prior known-good state when new data cannot be safely committed.

GeoBan

Country-based policy using a GeoIP database loaded into shared interval sets with CIDR aggregation. Feeds and GeoBan share sets and counters, so a shared counter cannot attribute a drop to one producer.

Suricata Integration

Consumes eligible Suricata EVE JSON alerts and processes selected alerts into ban actions with configurable scoring. Suricata is the external IDS/DPI engine; NFTBan is not the DPI engine.

RBL Monitoring

Observe-only monitoring of eligible IPv4 and IPv6 addresses against DNSBL/RBL providers. Produces alerts and reports; it never bans and never writes nftables. Degraded coverage is not reported as clean.

DNS-Tunnel Detection

Advisory, non-blocking detection of suspicious DNS-query behavior. Alerts are delivered via the central communication path.

Operational Safety

Mechanisms that prevent lockouts, enforce correctness, and maintain structural integrity.

Commit-Confirm

Firewall rule changes require explicit confirmation within a configurable grace period. Uncommitted changes are automatically rolled back. Prevents SSH lockout from misconfigured rules.

Whitelist Precedence

Whitelisted IPs cannot be banned. Ban operations on whitelisted addresses are rejected with an error. Adding an IP to the whitelist automatically removes it from blacklists.

Rule Order Enforcement

Blacklist rules are placed before ct state established in the input chain. This prevents attackers from maintaining connections after being banned. Validated by smoke tests.

FHS Auto-Healing

Filesystem Hierarchy Standard compliance with systemd timer-driven auto-repair. Paths: /usr/lib/nftban/, /etc/nftban/, /var/lib/nftban/, /var/log/nftban/.

Privilege Model

NFTBan uses role groups and Polkit for approved privileged operations, without requiring blanket sudo access.

  • nftban — Operator/admin access: ban/unban, config, and module control
  • nftban-auditor — Read-only audit/reporting access: status, logs, and reports (no mutating actions)

Services execute as the nftban user with CAP_NET_ADMIN granted via systemd capability bounding. Approved privileged operations are mediated by Polkit and NFTBan authorization.

Observability

100+ Prometheus metrics. Four health check modes. Watchdog monitoring. Structured logging.

Metrics

  • 100+ Prometheus metrics (promauto + sampler + textfile collector)
  • Prometheus, Zabbix, and OpenMetrics export backends
  • Textfile at /var/lib/nftban/metrics/nftban.prom
  • HTTP endpoint at :9940/metrics

Health & Diagnostics

  • Four modes: summary, check, json, auto-heal
  • Schema validation (tables, sets, chains, rule order)
  • Watchdog for resource monitoring
  • Smoke test suite with 74+ checks

Architecture at a Glance

Durable characteristics of the design. For current counts, see the live Project Statistics page and the latest GitHub Releases.

2 nftables tables (ip nftban + ip6 nftban)
IPv4+IPv6 Dual-stack enforcement sets
Go Centralized daemon owns ban and set updates
Polkit Role-based operator and auditor access

System Requirements

Requirement Value
Kernel Linux 5.10+ (nftables support)
Distributions Primary: Ubuntu 24.04, Debian 12, EL9. Also supported: Ubuntu 26.04, Debian 13, EL10, and Ubuntu 22.04. Packages are built and released through CI and validated on representative DEB and RPM platforms before fleet rollout.
Dependencies bash 5+, nftables 1.0+, jq, systemd
Go Runtime Not required (statically compiled binaries)
Packages RPM + DEB, x86_64 + ARM64
Disk ~50 MB installed
Memory ~20 MB base (daemon), scales with set sizes

Installation

# Rocky / AlmaLinux / RHEL 9 (use el10 for v10)
wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-el9-x86_64.rpm
sudo dnf install -y nftban-el9-x86_64.rpm

# Ubuntu 24.04 (also: ubuntu22.04, ubuntu26.04, debian12, debian13)
wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-ubuntu24.04-amd64.deb
sudo dpkg -i nftban-ubuntu24.04-amd64.deb && sudo apt-get install -f -y

# Getting started
nftban status              # System status
nftban health summary      # Health diagnostics
nftban login enable        # Enable SSH login alerts
nftban feeds update        # Update threat feeds

Operations & Auditability

NFTBan runs scheduled maintenance and freshness jobs, and routes operational messages through a centralized communication path. Notifications and reports use HTML templates and can be delivered through a local MTA or curl-based SMTP, with delivery evidence recorded. A read-only nftban-auditor role, mediated by Polkit and NFTBan authorization, supports audit and compliance reporting. Health and validation reports interpret system health, while kernel state remains the enforcement truth. Logs are rotated with bounded retention.

You can verify end-to-end mail delivery with nftban mail test --dry-run, and review current status with nftban health and nftban validate.