Architecture Overview

NFTBan Architecture Overview

Comprehensive system architecture documentation for NFTBan v1.9.3, a modular firewall management tool built on nftables.

Table of Contents

• System Components
• Component Diagram
• Data Flow
• Module Interaction
• Directory Structure
• Configuration Flow

---

System Components

NFTBan consists of four primary components:

Component	Binary	Purpose	Port
CLI	/usr/sbin/nftban	Command-line interface for ban/unban/status operations	-
Daemon	nftband	Background service for IPC, metrics, and event processing	Unix socket
Web UI	nftban-ui	GOTH-based web dashboard for management	3940/tcp
Auth Helper	nftban-ui-auth	PAM authentication proxy for web UI	Unix socket

---

Component Diagram

The following diagram shows the high-level system architecture and component relationships.

graph TB
    subgraph "User Interfaces"
        CLI[nftban CLI<br/>/usr/sbin/nftban]
        WEB[Web Browser]
    end

    subgraph "Go Services"
        UI[nftban-ui<br/>:3940/tcp]
        AUTH[nftban-ui-auth<br/>PAM Helper]
        DAEMON[nftband<br/>Daemon]
    end

    subgraph "Shell Libraries"
        CORE[nftban Core<br/>/usr/lib/nftban/core/]
        LIB[nftban Lib<br/>/usr/lib/nftban/lib/]
        CMDS[CLI Commands<br/>/usr/lib/nftban/cli/]
    end

    subgraph "System Layer"
        NFT[nftables<br/>Kernel Firewall]
        SURI[Suricata IDS<br/>EVE JSON Logs]
        JOURNAL[systemd-journal]
    end

    subgraph "Data Storage"
        CONF[/etc/nftban/<br/>Configuration]
        STATE[/var/lib/nftban/<br/>State & Reports]
        LOG[/var/log/nftban/<br/>Logs]
        CACHE[/var/cache/nftban/<br/>Cache Files]
    end

    WEB --> UI
    UI --> AUTH
    UI --> DAEMON
    AUTH -->|PAM| JOURNAL

    CLI --> CMDS
    CMDS --> CORE
    CMDS --> LIB
    CORE --> NFT

    DAEMON --> CORE
    DAEMON --> STATE

    SURI --> DAEMON

    CORE --> CONF
    CORE --> STATE
    CORE --> LOG

    UI --> CACHE

    classDef go fill:#00ADD8,stroke:#00ADD8,color:#fff
    classDef bash fill:#4EAA25,stroke:#4EAA25,color:#fff
    classDef system fill:#666,stroke:#666,color:#fff
    classDef storage fill:#f9a825,stroke:#f9a825,color:#000

    class UI,AUTH,DAEMON go
    class CLI,CORE,LIB,CMDS bash
    class NFT,SURI,JOURNAL system
    class CONF,STATE,LOG,CACHE storage

Loading

Diagram Legend:

• Blue nodes: Go binaries
• Green nodes: Shell/CLI components
• Gray nodes: System services
• Yellow nodes: Data storage paths

---

Data Flow

This sequence diagram shows the flow of a typical ban operation from the web UI.

sequenceDiagram
    participant Browser
    participant UI as nftban-ui<br/>(:3940)
    participant Session as Session Store
    participant CLI as nftban CLI
    participant Core as Core Library
    participant NFT as nftables

    Browser->>UI: POST /api/v1/ban
    UI->>Session: Validate JWT
    Session-->>UI: Session Valid

    UI->>CLI: exec("nftban", "ban", ip)
    CLI->>Core: source nftban_ban.sh
    Core->>Core: Validate IP format
    Core->>Core: Check whitelist

    alt IP is whitelisted
        Core-->>CLI: Error: IP whitelisted
        CLI-->>UI: Exit code 1
        UI-->>Browser: 400 Bad Request
    else IP valid
        Core->>NFT: nft add element inet nftban blocklist
        NFT-->>Core: Success
        Core->>Core: Log to audit log
        Core-->>CLI: Success JSON
        CLI-->>UI: Exit code 0 + JSON
        UI-->>Browser: 200 OK + JSON
    end

Loading

---

Module Interaction

NFTBan uses a modular architecture with lazy-loading to minimize startup time.

flowchart LR
    subgraph "Entry Point"
        MAIN[nftban main.sh]
    end

    subgraph "Core Modules"
        VERSION[version.sh]
        OUTPUT[nftban_output.sh]
        SECURITY[nftban_security.sh]
        PATHSEC[nftban_path_security.sh]
    end

    subgraph "Feature Modules"
        BAN[nftban_ban.sh]
        STATS[nftban_stats.sh]
        FEEDS[nftban_feeds.sh]
        PORTSCAN[nftban_portscan.sh]
        DDOS[nftban_ddos.sh]
        GEOIP[nftban_geoip.sh]
    end

    subgraph "CLI Commands"
        CMD_BAN[cmd_ban.sh]
        CMD_STATUS[cmd_status.sh]
        CMD_FEEDS[cmd_feeds.sh]
        CMD_CONFIG[cmd_config.sh]
    end

    MAIN --> VERSION
    MAIN --> OUTPUT

    CMD_BAN --> BAN
    CMD_BAN --> SECURITY

    CMD_STATUS --> STATS
    CMD_STATUS --> OUTPUT

    CMD_FEEDS --> FEEDS
    CMD_FEEDS --> PATHSEC

    BAN --> SECURITY
    FEEDS --> SECURITY
    PORTSCAN --> BAN
    DDOS --> BAN
    GEOIP --> BAN

Loading

Module Loading Pattern:

• Each module uses a _LOADED guard variable to prevent double-loading
• Core modules are loaded first (version, output, security)
• Feature modules load their dependencies on-demand
• Configuration load order: main.conf then main.conf.local (user override)

---

Directory Structure

NFTBan follows the Filesystem Hierarchy Standard (FHS).

/etc/nftban/                    # Configuration
├── main.conf                   # Main configuration
├── main.conf.local             # User overrides (optional)
├── conf.d/                     # Module-specific configs
│   ├── feeds/                  # Threat feed configurations
│   ├── portscan/               # Portscan detection config
│   ├── ddos/                   # DDoS detection config
│   └── geoip/                  # GeoIP blocking config
├── ssl/                        # TLS certificates
│   ├── cert.pem
│   └── key.pem
├── whitelist.d/                # IP whitelists
└── blacklist.d/                # IP blacklists

/usr/lib/nftban/                # Libraries
├── core/                       # Core shell modules
├── lib/                        # Shared libraries
├── cli/                        # CLI command handlers
├── setup/                      # Installation helpers
└── exporters/                  # Metrics exporters

/var/lib/nftban/                # State data
├── state/                      # Runtime state
├── reports/                    # Generated reports
├── metrics/                    # Prometheus metrics
└── feeds/                      # Downloaded threat feeds

/var/log/nftban/                # Log files
├── nftban.log                  # Main log
├── audit.log                   # Audit trail
└── ui-access.log               # Web UI access log

/var/cache/nftban/              # Cache files
├── status.cache                # Cached status data
├── health.lock                 # Health check lock file
└── metrics.cache               # Cached metrics

/run/nftban/                    # Runtime sockets
├── nftband.sock                # Daemon IPC socket
└── auth.sock                   # Auth helper socket

---

Configuration Flow

Configuration is loaded in a specific order to allow layered overrides.

flowchart TD
    subgraph "Load Order"
        A["/etc/nftban/main.conf<br/>(defaults)"] --> B["/etc/nftban/main.conf.local<br/>(user overrides)"]
        B --> C["Environment Variables<br/>(NFTBAN_*)"]
        C --> D["Command Line Flags<br/>(--config, --port)"]
    end

    subgraph "Resulting Config"
        D --> E["Merged Configuration"]
    end

    subgraph "Runtime"
        E --> F["Go Services"]
        E --> G["Shell Scripts"]
    end

    style A fill:#e1f5fe
    style B fill:#b3e5fc
    style C fill:#81d4fa
    style D fill:#4fc3f7
    style E fill:#29b6f6

Loading

Configuration Precedence (lowest to highest):

1. Compiled defaults in code
2. /etc/nftban/main.conf - Package defaults
3. /etc/nftban/main.conf.local - Site-specific overrides
4. Environment variables (NFTBAN_* prefix)
5. Command-line flags

---

Related Pages

• Systemd Units Overview - Service configurations
• CLI Command Tree - Command documentation
• API Handlers Map - REST API endpoints
• Health Check Architecture - Auto-heal system

---

Documentation generated from NFTBan v1.9.3 source code analysis.