nftban

NFTBan

Linux Intrusion Prevention System & nftables Firewall Manager

CI/CD Status

Security & Supply Chain

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.

What NFTBan Provides

• 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

Truth Authority

When sources disagree, kernel wins.

Evidence Model

NFTBan derives protection state from kernel-observable evidence:

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

Protection Modules

Quick Install

Tier 0 — Primary Platforms

Ubuntu 24.04 LTS (Noble)

wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-ubuntu24.04-amd64.deb
sudo apt install -y ./nftban-ubuntu24.04-amd64.deb

Debian 12 (Bookworm)

wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-debian12-amd64.deb
sudo apt install -y ./nftban-debian12-amd64.deb

Rocky / AlmaLinux / RHEL 9

wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-el9-x86_64.rpm
sudo dnf install -y ./nftban-el9-x86_64.rpm

Tier 1 — Future Platforms

Debian 13 (Trixie)

wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-debian13-amd64.deb
sudo apt install -y ./nftban-debian13-amd64.deb

Rocky / AlmaLinux / RHEL 10

wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-el10-x86_64.rpm
sudo dnf install -y ./nftban-el10-x86_64.rpm

Tier 2 — Legacy Platforms

Ubuntu 22.04 LTS (Jammy)

wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-ubuntu22.04-amd64.deb
sudo apt install -y ./nftban-ubuntu22.04-amd64.deb

Available Packages

RPM Packages (EL Family)

DEB Packages (Ubuntu + Debian)

Packages are distro-specific and FHS compliant. Use the package matching your exact distribution version. See Supported Platforms for the full platform contract.

Quick Start

# 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

Health States

nftban health           # 4-axis truth table
nftban-validate --json  # full validator output

Validator Scope

The 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.

Architecture

Kernel (nftables)     ← packet decisions enforced here
  ↑ reads
Go validator          ← derives health state
  ↑ reads
CLI (nftban)          ← presents to operator
  ↑ reads
Config (/etc/nftban/) ← operator intent

Core Invariants

The following rules define NFTBan behavior:

1. Kernel is the only enforcement authority
2. Validator derives truth from kernel state
3. CLI presents validator output only
4. Configuration expresses intent, not runtime state
5. Shared evidence cannot be used for attribution

These invariants are enforced by validation logic and CI gates.

Metrics and Observability

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.

Go Module Notice

NFTBan is a system-level firewall product, not a general-purpose Go library.

Supported Public Packages

All packages under internal/ are implementation details.

Requirements

• 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)

Security

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.

Documentation

License

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.

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