Linux Intrusion Prevention System & nftables Firewall Manager
NFTBan is an open-source Linux Intrusion Prevention System (IPS) and firewall manager built on nftables, designed to integrate cleanly with modern Linux security stacks.
All packet decisions (accept, drop, bypass) are enforced in the nftables kernel. The Go daemon writes to kernel sets. The Go validator derives health from kernel state. The CLI presents kernel-derived truth.
- nftables-native enforcement with kernel-managed timeouts
- Threat feed ingestion with CIDR aggregation
- Country blocking via GeoIP (DB-IP Lite default)
- Login brute-force detection across SSH, mail, FTP, panel services
- Port scan detection (classic + Suricata modes)
- L3/L4 rate limiting and connection limits
- HTTP bot classification with 6 dedicated kernel sets
- Optional Suricata DPI integration (EVE JSON)
- 4-axis health model with kernel-derived truth validator
- Atomic nftables schema rebuild (validate before load)
- 5-phase installer with emergency SSH table
| Priority | Component | Role |
|---|---|---|
| 1 | Kernel (nft list ruleset) |
What is actually enforcing |
| 2 | Validator (nftban-validate) |
Derives health from kernel evidence |
| 3 | CLI (nftban) |
Presents validator output to operator |
| 4 | Config (/etc/nftban/) |
Operator intent (not runtime truth) |
When sources disagree, kernel wins.
NFTBan derives protection state from kernel-observable evidence:
| Evidence | Meaning | Strength |
|---|---|---|
| Counter > 0 | Packet processing observed | Strong |
| Set membership > 0 | State present in kernel | Strong |
| Structure exists | Rules/chains present | Weak (presence only) |
| Journal event | External event (daemon/logs) | Context-dependent |
Interpretation rules:
- Counter > 0 = positive evidence of enforcement
- Counter = 0 = neutral (not a failure)
- Structure alone does not imply enforcement
- Absence of evidence is not evidence of absence
| Module | Layer | Evidence | Daemon |
|---|---|---|---|
| DDoS Protection | L3/L4 | 5 dedicated kernel counters | NO |
| BotGuard | L7 HTTP | 6 dedicated kernel sets | YES |
| Portscan Detection | L3/L4 | Structure only (no counter) | NO |
| Login Monitoring | L2 Auth | Journal + shared sets | YES |
| Blacklist & Feeds | L1 IP | Shared sets + counters | Partial |
| Suricata IDS | L7 DPI | EVE JSON (external) | YES |
| DNS Tunnel | Advisory | DNS analysis (non-blocking) | YES |
wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-ubuntu24.04-amd64.deb
sudo apt install -y ./nftban-ubuntu24.04-amd64.debwget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-el9-x86_64.rpm
sudo dnf install -y ./nftban-el9-x86_64.rpmSee Supported Platforms for full matrix.
# Check system health (kernel-derived truth)
nftban health
# Check validator output directly
nftban-validate --json
# Enable modules
nftban ddos enable
nftban portscan enable
nftban botguard enable
nftban login enable
nftban geoban enable
# Common operations
nftban ban 1.2.3.4
nftban unban 1.2.3.4
nftban status| State | Meaning | Exit |
|---|---|---|
| PROTECTED | All axes pass, system capable of enforcement | 0 |
| IDLE | All axes pass, no relevant traffic | 0 |
| DEGRADED | One or more axes fail | 1 |
| DOWN | Critical failure | 2 |
nftban health # 4-axis truth table
nftban-validate --json # full validator outputThe validator is kernel-first and derives truth from observable evidence. Kernel-resident evidence (counters, sets, chains) is authoritative for enforcement state. Some module-specific runtime evidence may come from bounded daemon or journal observations where defined by the module contract.
Current scope boundaries:
- Portscan: no dedicated kernel counter — enforcement cannot be proven
- LoginMon: journal-based evidence — may enforce while validator reports IDLE
- Blacklist: shared counters — per-source attribution not possible from kernel
The validator reports observable truth, not complete system behavior.
Kernel (nftables) ← packet decisions enforced here
↑ reads
Go validator ← derives health state
↑ reads
CLI (nftban) ← presents to operator
↑ reads
Config (/etc/nftban/) ← operator intent
| Component | Type | Purpose |
|---|---|---|
nftban |
Shell CLI | Operator interface, schema generation |
nftband |
Go daemon | Ban execution, loginmon, BotGuard scoring |
nftban-validate |
Go binary | Read-only kernel truth validator (~1ms) |
The following rules define NFTBan behavior:
- Kernel is the only enforcement authority
- Validator derives truth from kernel state
- CLI presents validator output only
- Configuration expresses intent, not runtime state
- Shared evidence cannot be used for attribution
These invariants are enforced by validation logic and CI gates.
The daemon exposes runtime metrics on http://127.0.0.1:9580/metrics
(localhost only, Prometheus text exposition format). This is the canonical
runtime metrics surface. As of v1.89, the evidence layer reads all kernel
data from the validator — no duplicate nft queries.
The watchdog subsystem provides adaptive resource control. It monitors process, Go runtime, and kernel metrics, and adjusts operating mode (NORMAL → DEGRADED → SURVIVAL) based on memory and CPU pressure. Server profile detection (Small/Medium/Large) automatically tunes memory budgets and CIDR limits based on available RAM.
NFTBan is a system-level firewall product, not a general-purpose Go library.
| Package | Purpose |
|---|---|
pkg/ipc |
IPC client for daemon communication |
pkg/version |
Version information |
All packages under internal/ are implementation details.
- Linux: Rocky/Alma/RHEL 9-10, Ubuntu 22.04+, Debian 12+
- nftables: 1.0+
- Bash: 4.4+
- systemd: 252+
- jq: JSON processor
- Go 1.24+: For building from source (optional)
SLSA Level 3 provenance, 9 automated security tools (CodeQL, OSV-Scanner, gitleaks, Trivy, gosec, ShellCheck, Semgrep, Fuzz, Dependency Review), SBOM with every release, all GitHub Actions SHA-pinned.
See SECURITY.md for vulnerability reporting and full pipeline details.
| Section | Link |
|---|---|
| Wiki Home | Complete documentation |
| Architecture | System design + truth model |
| Health Model | 4-axis derivation |
| CLI Reference | All commands + trust levels |
| Glossary | Canonical terminology |
| Known Limitations | Validator scope per module |
| Installation | Install guide |
NFTBan Core is licensed under the Mozilla Public License 2.0 (MPL-2.0).
Copyright (c) 2024-2026 NFTBan Project / Antonios Voulvoulis
MPL-2.0 is file-level copyleft: you may use, modify, and distribute freely. Modified MPL files must remain open. Your own separate code is unaffected.
| Layer | License |
|---|---|
| Core engine | MPL-2.0 |
| Pro portal | Commercial |
| Brand assets | All rights reserved |
See LICENSE for full text. "NFTBan" is a trademark — forks must use a different name. See TRADEMARK.md.
NFTBan — Linux IPS & nftables Firewall Manager
nftban.com |
Report Issue |
Discussions