Home

NFTBan Documentation

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.

It provides automated threat detection and response with native nftables control, Polkit-based privilege separation, and real-time threat intelligence.

---

Project Information

Property	Value
Version	1.19.0
License	MPL-2.0
Repository	github.com/itcmsgr/nftban
Config Path	/etc/nftban/
Library Path	/usr/lib/nftban/

---

Audit Status

Last Audit: 2026-02-23 Overall Risk: LOW (v1.19.0 security maintenance applied) OpenSSF Scorecard: 7+ (supply-chain hardened)

Severity	Count	Status
Critical	0	Fixed in v1.19.0
High	0	Fixed in v1.19.0
Medium	16	Tracked for v1.19.1
Low	13	Tracked

---

Documentation Index

Project Overview

• Project Statistics - Codebase stats, language breakdown, CI/CD pipeline, security audit status

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

Performance

• Performance Benchmarks - IPC latency, netlink throughput, scalability analysis
• Optimization Tools and Tweaks - CIDR aggregation, feed optimization, large set management

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