Home

NFTBan Documentation

NFTBan is a firewall management engine built on Linux nftables. It combines native nftables control with privilege separation, real-time threat intelligence, and self-healing infrastructure.

---

Project Information

Property	Value
Version	1.9.4
License	MPL-2.0
Repository	/home/gituser/github/nftban
Config Path	/etc/nftban/
Library Path	/usr/lib/nftban/

---

Audit Status

Last Audit: 2026-02-06 Overall Risk: MEDIUM

Severity	Count	Status
Critical	1	Open
High	5	Open
Medium	19	Open
Low	28	Tracked

---

Documentation Index

Getting Started

• Installation Guide - Prerequisites, firewall conflicts, install, post-config

Configuration

• Configuration Reference - Central config file reference
• Registry Architecture - Commands, config, reports registries
• Queue and Mail Contract - Task queue and mail delivery interface
• FHS Compliance - Directory structure and permissions
• NFT Schema Validation - nftables schema, rule order, CVE detection
• GeoIP Database Guide - Geographic blocking, database options, auto-updates

CLI and Commands

• CLI Commands Reference - Complete command reference (all subcommands)
• Debug and Troubleshooting - Debug trace and smoke tests
• Security Profiles - Automated security configuration

Monitoring and Export

• Metrics Architecture - Metrics pipeline, Prometheus, Zabbix, connectors
• Timer Schedule - Systemd timer architecture and optimization

Security

• Security Architecture - Access control, Polkit, FHS auto-heal, groups and permissions
• Security Operations Guide - Hardening, portmapper, RBL monitoring, emergency procedures

Feature Guides

• Suricata IDS Integration - Deep packet inspection setup and rules
• Web Panel Compatibility - cPanel, DirectAdmin, Plesk, CWP integration
• Binary Verification (SLSA) - Verify binary provenance

Platform and CI

• Supported Platforms - Tier 0/1/2 platform contract, CI failure classification

Development

• Coding Standards - Bash coding standards and best practices
• Project Statistics - Codebase metrics and project size

---

Quick Start

# After install, check system status
nftban status
nftban health summary

# Apply a security profile
nftban profile apply standard

# Enable features as needed
nftban login enable       # Login monitoring
nftban feeds enable       # Threat intelligence feeds
nftban portscan enable    # Port scan detection
nftban ddos enable        # DDoS protection
nftban suricata enable    # Suricata IDS integration
nftban gui enable         # Web dashboard (port 3940)
nftban metrics enable     # Prometheus metrics

See the Installation Guide for full setup instructions.

---

Key Features

• Native nftables integration - Direct kernel-level firewall control
• Login monitoring - Built-in detection of SSH brute-force and authentication anomalies
• 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
• DDoS protection - Rate limiting and flood protection (classic + Suricata modes)
• Suricata IDS integration - Optional deep packet inspection
• RBL monitoring - Real-time blackhole list checking with alerts
• Metrics collection - Prometheus, Zabbix, and connector exports (ES, Kafka, syslog)

---

Central Configuration

Main config: /etc/nftban/nftban.conf

# 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"

See Configuration Reference for all options.

---

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)
/var/log/nftban/                # Log files (nftban:nftban 750)
/var/cache/nftban/              # Cache files
/run/nftban/                    # Runtime (PIDs, sockets)

See FHS Compliance for details.

---

Need Help?

1. Check CLI Commands Reference
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

---

Documentation Standards

This wiki follows the NFTBan documentation style guide:

• Professional, concise tone
• FHS-compliant paths (e.g., /etc/nftban/, not ~/.nftban/)
• Exact systemd unit names (e.g., nftban-ui.service)
• Mermaid diagrams with evidence-based relationships
• Code blocks with appropriate language tags

---

License

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