Skip to content

Home

Jump to bottom
Antonios Voulvoulis edited this page Jan 3, 2026 · 45 revisions

NFTBan Documentation

Version: 1.0.0-beta | Release: December 2025

First major release - Production tested, community feedback welcome!

🎯 What is NFTBAN?

NFTBAN is an enterprise-grade firewall management engine built on Linux nftables. The name stands for NFTables BAN actions, emphasizing the system's foundation on native nftables technology for high-performance, kernel-level packet filtering.

Moving beyond legacy iptables-based scripts, NFTBAN provides a resilient, self-healing network defense layer by combining the raw power of nftables with advanced privilege separation and real-time threat intelligence.

Key Features:

  • Native nftables integration - Direct kernel-level firewall control
  • Intelligent log monitoring - Built-in module for detecting login anomalies and suspicious patterns
  • Threat intelligence feeds - Automatic blocking of known malicious IPs
  • Geographic blocking (GeoBan) - Block/allow traffic by country
  • Port scan detection - Automatic detection and blocking of reconnaissance attempts
  • DDoS protection - Rate limiting and flood protection
  • Suricata IDS integration - Optional deep packet inspection (Mode 2)
  • Prometheus metrics - Full observability (Mode 2)

📦 Two Installation Modes

NFTBan supports two deployment modes depending on your server resources:

🖥️ Mode 1: CLI-Only

For: VPS, small servers, minimal resource usage

Includes:

  • ✅ NFTables firewall with nftban table
  • ✅ nftban-core binary (core Go operations: ban, unban, geoip, feeds)
  • ✅ Login monitoring module (detects failed SSH, service anomalies)
  • ✅ Login alerts via email
  • ✅ Threat feeds processing
  • ✅ Portscan detection
  • ✅ DDoS protection rules
  • ✅ Geographic blocking
  • ✅ Complete CLI (47 commands)
  • ❌ No Web GUI
  • ❌ No Prometheus metrics
  • ❌ No Suricata IDS

Resources: ~50MB RAM, minimal CPU

👉 Installation Guide: CLI-Only Mode

🚀 Mode 2: GUI + Prometheus (Full Featured)

For: Production servers, monitoring infrastructure

Includes:

  • ✅ Everything from Mode 1 (including nftban-core)
  • ✅ Web GUI (nftban-ui Go HTTP server on port 3940)
  • ✅ Prometheus metrics exporter
  • ✅ Suricata IDS integration (deep packet inspection)
  • ✅ Grafana dashboards support
  • ✅ Advanced statistics and reporting
  • ✅ REST API for automation

Resources: ~200MB RAM, moderate CPU

👉 Installation Guide: GUI + Prometheus Mode

📚 Documentation Index

🚀 Getting Started

🔧 Configuration

🔐 Binary Verification

📊 CLI & Commands

🔐 Security

🐛 Troubleshooting

🚀 Quick Start

New Installation

Option A: CLI-Only (Lightweight)

# Install NFTBan CLI-only
nftban setup --mode cli

Option B: GUI + Prometheus (Full)

# Install NFTBan with GUI
nftban setup --mode gui

After Installation

# Check system status
nftban status

# Run health check
nftban health summary

# Apply a security profile
nftban profile apply standard

# Enable login monitoring
nftban login enable

# Enable threat feeds
nftban feeds enable

🔧 Central Configuration

NFTBan uses a central configuration file that all scripts source for consistency:

Main Config: /etc/nftban/nftban.conf

# Key settings
NFTBAN_VERSION="1.0.0"
NFTBAN_LOG_LEVEL="INFO"
NFTBAN_DEBUG_TRACE="false"

# Feature toggles
NFTBAN_LOGIN_MONITOR_ENABLED="false"
NFTBAN_FEEDS_ENABLED="false"
NFTBAN_GEOIP_ENABLED="false"
NFTBAN_DDOS_ENABLED="false"
NFTBAN_PORTSCAN_ENABLED="false"

# Paths (DO NOT MODIFY)
NFTBAN_BIN="/usr/bin/nftban"
NFTBAN_LIB_DIR="/usr/lib/nftban"
NFTBAN_CONFIG_DIR="/etc/nftban"
NFTBAN_DATA_DIR="/var/lib/nftban"
NFTBAN_LOG_DIR="/var/log/nftban"

👉 Full Configuration Reference

📁 Directory Structure (FHS Compliant)

/usr/bin/nftban                 # Main CLI entry point
/usr/lib/nftban/                # Libraries and modules
├── bin/                        # Go binaries (nftban-core, nftban-ui)
├── cli/                        # CLI command handlers
├── core/                       # Core modules
├── helpers/                    # Helper scripts
└── tests/                      # Test suites

/etc/nftban/                    # Configuration (root:nftban 750)
├── nftban.conf                 # Central config
├── conf.d/                     # Module configs
├── whitelist.d/                # Whitelist files
├── blacklist.d/                # Blacklist files
└── distros/                    # Distro-specific configs

/var/lib/nftban/                # Runtime data (nftban:nftban 750)
├── geoip/                      # GeoIP databases
├── reports/                    # Generated reports
├── metrics/                    # Statistics data
└── exports/                    # User exports

/var/log/nftban/                # Log files (nftban:nftban 750)
├── nftban.log                  # Main log
├── login-monitor.log           # Login monitoring events
├── bans.log                    # Ban/unban actions
└── debug_trace.log             # Debug trace (when enabled)

/var/cache/nftban/              # Cache files
/run/nftban/                    # Runtime (PIDs, sockets)

👉 FHS Compliance Details

🛡️ Protection Modules

Login Monitoring

NFTBan includes a built-in log monitoring module that analyzes authentication logs to detect:

  • Failed SSH login attempts
  • Brute force patterns
  • Service authentication failures
  • Suspicious login behavior
nftban login status     # Check status
nftban login enable     # Enable monitoring
nftban login test       # Test detection

Threat Feeds

Automatic blocking of known malicious IPs from threat intelligence sources:

  • FireHOL Level 1-3
  • Emerging Threats
  • Spamhaus DROP/EDROP
  • And more...
nftban feeds list       # List available feeds
nftban feeds enable     # Enable feeds
nftban feeds update     # Update now

Port Scan Detection

Automatic detection and blocking of port scanning attempts:

nftban portscan status  # Check status
nftban portscan enable  # Enable detection

DDoS Protection

Rate limiting and flood protection:

nftban ddos status      # Check status
nftban ddos enable      # Enable protection

Geographic Blocking

Block or allow traffic by country:

nftban geoban list      # List blocked countries
nftban geoban block CN  # Block country
nftban geoip lookup IP  # Lookup IP location

🔬 Debug & Troubleshooting

NFTBan v1.0 includes comprehensive debug tools:

# Enable debug trace
nftban debug enable

# Run smoke tests
nftban smoke quick          # Quick test (3 commands)
nftban smoke run            # Standard test (~20 commands)
nftban smoke all            # Comprehensive test (ALL 47 commands)

# Check for stuck scripts
nftban smoke check

# View recent trace entries
nftban smoke trace recent 50

# Full debug dump
nftban debug dump all

👉 Debug & Troubleshooting Guide

🆘 Need Help?

  1. Check CLI Commands Reference - Complete command list
  2. Run health check: nftban health summary
  3. Run smoke test: nftban smoke quick
  4. Check debug trace: nftban debug trace orphans
  5. View logs: nftban debug logs main 100

📜 License

Mozilla Public License 2.0 (MPL-2.0) Copyright © 2024–2026 NFTBAN Project

Website: https://nftban.com

Next Steps:

NFTBan Wiki

Getting Started

Architecture

Modules

Operator Reference

Verification & Trust

Reference

Legal

Clone this wiki locally