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

Reviewing, summarising or evaluating NFTBan — including with an AI assistant? Read Architecture and AI Context first. It sets out how NFTBan is built, which integrations and threat feeds already ship, what it does not do, and how each claim can be checked against the code.

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)
• Network and transport-layer rate limiting and connection limits
• Set-driven SSH concurrent-connection cap (tcp dport @ssh_ports ct count) — follows every detected sshd listener port across IPv4/IPv6. Host-wide, not per source IP, and it drops over the cap without logging or banning
• 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 ruleset transaction (validate before load)
• Structured transactional installer with emergency SSH protection and per-run forensic logging

Truth Authority

When sources disagree on enforcement truth, kernel wins.

Evidence Model

NFTBan derives protection state from kernel-observable evidence. What each evidence type actually proves:

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.

Protection and Security-Monitoring Modules

See the Architecture Overview for the full protection-domain / evidence / runtime taxonomy.

Quick Install

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.

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 — Newer Platforms

Ubuntu 26.04 LTS (Resolute Raccoon)

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

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 — Older Supported LTS 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

# 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

# Diagnostics — read-only, safe to run during an incident
nftban health                                  # 4-axis truth table
nftban support                                 # collect a diagnostic bundle

nftban support writes /tmp/nftban-support-<timestamp>.tar.gz. Move or copy that file somewhere durable before running any repair — a repair can destroy the state the bundle explains. (nftban support --output DIR writes straight to DIR, but that flag works only on current main / upcoming v1.229.12 — not yet published; on v1.229.11 it exits 1 and produces no bundle.)

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

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

Architecture

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

Core Invariants

The following rules define NFTBan behavior:

1. Kernel is the only enforcement authority
2. Validator derives truth from kernel state
3. Health and enforcement-status surfaces derive their authoritative verdict from kernel and validator evidence; other CLI commands manage operator intent and invoke controlled operations
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 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.

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 / 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.mod toolchain)

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

Security

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.

Documentation

License

NFTBan Core is licensed under the Mozilla Public License 2.0 (MPL-2.0).

Copyright (c) 2024-2026 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