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 firewall packet decisions — accept, drop, and policy bypass — are enforced by nftables in the kernel. NFTBan's controlled daemon and synchronization paths update the kernel sets they own, while kernel-native rules and meters enforce traffic policy directly. Observe-only and advisory modules produce findings without modifying packet enforcement. Health and enforcement-status surfaces derive their authoritative verdict from kernel and validator evidence.
- 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)
- Network and transport-layer rate limiting and connection limits
- Set-driven SSH brute-force connection-rate-limit (
tcp dport @ssh_ports ct count) — follows every detected sshd listener port across IPv4/IPv6 - HTTP bot classification (BotGuard) using dedicated nftables HTTP signal sets
- Malicious-HTTP / exploit-probe scanning (BotScan) with durable ban-evidence handoff to the daemon
- Server public IPv4/IPv6 reputation monitoring via DNSBL/RBL checks, with explicit degraded-coverage reporting — observe-only and non-enforcing
- Optional Suricata DPI integration (EVE JSON)
- 4-axis health model with kernel-derived truth validator
- Atomic nftables schema rebuild (validate before load)
- Structured transactional installer with emergency SSH protection and per-run forensic logging
| Priority | Component | Role |
|---|---|---|
| 1 | Kernel (nft list ruleset) |
What is actually enforcing |
| 2 | Validator (nftban validate) |
Derives health from kernel evidence |
| 3 | CLI (nftban) |
Health/enforcement-status surfaces present validator-derived truth; other commands manage operator intent and invoke controlled operations |
| 4 | Config (/etc/nftban/) |
Operator intent (not runtime truth) |
When sources disagree on enforcement truth, kernel wins.
NFTBan derives protection state from kernel-observable evidence. What each evidence type actually proves:
| Evidence | What it proves |
|---|---|
| Referenced set membership | Enforcement state exists for a rule-linked set |
| Dedicated rule counter increment | Traffic reached that specific enforcement path |
| Shared counter increment | Enforcement occurred, but producer attribution may be unavailable |
| Structure only | Capability is installed, not necessarily active |
| Journal / daemon evidence | Module activity per that module's bounded evidence contract |
Interpretation rules:
- A counter > 0 proves rule traversal; a shared counter cannot prove which module caused it.
- Counter = 0 = neutral (not a failure).
- Set membership proves state exists, not that the set is rule-linked, correctly ordered, reachable, or attributable to a specific module.
- Absence of evidence is not evidence of absence.
| Module | Protects or Monitors | Signal Source | Operation |
|---|---|---|---|
| DDoS Protection | Network and transport-layer floods | nftables meters and counters | Kernel-enforced; daemon provides runtime management/telemetry where applicable |
| BotGuard (HTTP Guard) | HTTP abuse and connection attacks | nftables HTTP signals | Go daemon with centralized enforcement |
| BotScan (HTTP Exploit Scanner) | Malicious HTTP requests and exploit probes | Web access logs | Scheduled scanner + daemon consumer (centralized enforcement) |
| Portscan Detection | Reconnaissance and connection scanning | Connection-pattern analysis | Go daemon module + centralized enforcement |
| Login Monitoring | Brute-force and authentication abuse | Journald, service logs, panel logs, web-auth logs, Suricata | Go daemon detection + centralized enforcement (legacy shell path in-tree, not deployed) |
| Blacklist & Threat Feeds | Known hostile addresses | Manual entries and external intelligence feeds | Centrally synchronized enforcement |
| Suricata Integration | IDS-detected network threats | Suricata EVE JSON (external IDS) | External IDS producer + NFTBan processing |
| RBL Monitoring | Server-IP reputation and mail-delivery blocklisting risk | Public IPv4/IPv6 DNSBL checks | Scheduled and on-demand; observe-only; alerts and reports (no bans, no nftables writes) |
| DNS Tunnel Detection | Suspicious DNS behavior | DNS-query analysis | Advisory and non-blocking |
See the Architecture Overview for the full protection-domain / evidence / runtime taxonomy.
Packages for all listed targets are built and released through CI. Package-native installation is validated on representative DEB and RPM platforms before fleet rollout. Tiers reflect recommendation/age, not support level: Tier 0 = primary/recommended · Tier 1 = newer releases · Tier 2 = older supported LTS.
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-debian12-amd64.deb
sudo apt install -y ./nftban-debian12-amd64.debwget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-el9-x86_64.rpm
sudo dnf install -y ./nftban-el9-x86_64.rpmwget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-ubuntu26.04-amd64.deb
sudo apt install -y ./nftban-ubuntu26.04-amd64.debwget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-debian13-amd64.deb
sudo apt install -y ./nftban-debian13-amd64.debwget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-el10-x86_64.rpm
sudo dnf install -y ./nftban-el10-x86_64.rpmwget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-ubuntu22.04-amd64.deb
sudo apt install -y ./nftban-ubuntu22.04-amd64.deb| Tier | Distribution | Version | Package |
|---|---|---|---|
| 0 | Rocky / Alma / RHEL / CentOS Stream | 9 | nftban-el9-x86_64.rpm |
| 1 | Rocky / Alma / RHEL / CentOS Stream | 10 | nftban-el10-x86_64.rpm |
| Tier | Distribution | Version | Package |
|---|---|---|---|
| 0 | Ubuntu | 24.04 (Noble) | nftban-ubuntu24.04-amd64.deb |
| 0 | Debian | 12 (Bookworm) | nftban-debian12-amd64.deb |
| 1 | Ubuntu | 26.04 (Resolute Raccoon) | nftban-ubuntu26.04-amd64.deb |
| 1 | Debian | 13 (Trixie) | nftban-debian13-amd64.deb |
| 2 | Ubuntu | 22.04 (Jammy) | nftban-ubuntu22.04-amd64.deb |
Packages are distro-specific and FHS compliant. Use the package matching your exact distribution version. See Supported Platforms for the full platform contract.
# 1. Review readiness and current configuration first
nftban health # 4-axis kernel-derived truth
nftban validate # validator verdict
# 2. SAFETY FIRST — whitelist your management/SSH IP before enabling enforcement,
# so a detection rule can never lock you out of your own host:
nftban whitelist add YOUR.MANAGEMENT.IP # your admin/SSH source IP
nftban check YOUR.MANAGEMENT.IP # confirm it is whitelisted, not banned
# 3. Enable only the modules appropriate for this host
nftban ddos enable
nftban portscan enable
nftban login enable
# 4. Optional, policy-dependent modules (review before enabling)
nftban botguard enable # HTTP abuse protection
nftban geoban enable # country blocking — operator policy decision
# Observe-only server-IP reputation check; does NOT modify nftables and issues no bans
nftban rbl server check
# Common operations
nftban ban 1.2.3.4 # permanent ban
nftban ban 1.2.3.4 --timeout 3600 # 1-hour ban (positive integer seconds)
nftban unban 1.2.3.4
nftban status--timeout requires a positive integer (seconds) — non-integer / negative /
zero / fractional / signed / hex / leading-zero values are rejected at parse
time with a clear ERROR (since v1.141.0). Omit --timeout for a permanent ban.
Whitelist both IPv4 and IPv6 management addresses where applicable.
| 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: detection runs as a Go daemon module; kernel-attributable enforcement evidence is limited, so validator visibility is bounded by the module contract.
- Login Monitoring: combines kernel, daemon, source-visibility, and bounded journal evidence. Quiet traffic and unavailable input sources are distinguished according to the current health contract.
- Blacklist: shared counters — per-source attribution is not possible from the kernel alone.
The validator reports observable truth, not complete system behavior.
Kernel (nftables) ← packet decisions enforced here
↑ reads
Go validator ← derives health state
↑ reads
CLI (nftban) ← health surfaces present validator truth; also drives operations
↑ reads
Config (/etc/nftban/) ← operator intent
| Component | Type | Purpose |
|---|---|---|
nftban |
Shell CLI | Operator interface, configuration management, diagnostics, scheduled workflows, and controlled lifecycle operations |
nftband |
Go daemon | Centralized ban execution, detector event processing, evidence consumption (incl. BotScan signals), set synchronization/reconciliation, and runtime module services |
nftban validate |
Go binary (impl: /usr/lib/nftban/bin/nftban-validate) |
Read-only kernel truth validator (~1ms) |
The following rules define NFTBan behavior:
- Kernel is the only enforcement authority
- Validator derives truth from kernel state
- Health and enforcement-status surfaces derive their authoritative verdict from kernel and validator evidence; other CLI commands manage operator intent and invoke controlled operations
- 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 serves runtime metrics at http://127.0.0.1:9580/metrics
(the /metrics endpoint is loopback-restricted; Prometheus text exposition
format). This is the canonical runtime metrics surface. Note that the daemon's
:9580 listener binds all interfaces and its /health and /api/v1/*
endpoints are not loopback-restricted — firewall :9580 to trusted sources.
Validator-backed health surfaces use the validator as their canonical
kernel-evidence source, reducing duplicate nftables inspection.
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 / 24.04 / 26.04 LTS (Resolute Raccoon), Debian 12 / 13
- nftables: 1.0+
- Bash: 4.4+
- systemd: 252+
- jq: JSON processor
- Go 1.25+: For building from source (optional; matches the
go.modtoolchain)
Ubuntu 26.04 LTS (Resolute Raccoon) is a Tier 1 target — released, packaged,
and installable — see the Quick Install — Tier 1
section and the DEB Packages table for the
install snippet and .deb URL. Tier 0 remains the primary/recommended baseline
(Ubuntu 24.04, Debian 12, EL9).
SLSA Level 3 provenance for the standalone nftban-core release binary (other
release assets — nftband and the complete DEB/RPM packages — are checksum-verified
via SHA256SUMS, not covered by that provenance). Plus automated security checks —
CodeQL, OSV-Scanner, gitleaks, Trivy, gosec, ShellCheck, Semgrep, fuzzing, and
Dependency Review — with an SBOM on every release and all GitHub Actions SHA-pinned.
Reporting is split by process (shared security@nftban.com mailbox): security
vulnerabilities → the private process in SECURITY.md (GitHub private
Security Advisory preferred; email fallback security@nftban.com with a [SECURITY]
subject prefix — never a public issue). Community/conduct reports →
security@nftban.com per the Code of Conduct.
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