Architecture Overview

NFTBan Architecture Overview

System architecture documentation for NFTBan v1.15.0, 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"]
        WEB["Web Browser"]
    end

    subgraph "Go Services"
        UI["nftban-ui :3940"]
        AUTH["nftban-ui-auth"]
        DAEMON["nftband Daemon"]
    end

    subgraph "Shell Libraries"
        CORE["nftban Core"]
        LIB["nftban Lib"]
        CMDS["CLI Commands"]
    end

    subgraph "System Layer"
        NFT["nftables"]
        SURI["Suricata IDS"]
        JOURNAL["systemd-journal"]
    end

    subgraph "Data Storage"
        CONF["Configuration"]
        STATE["State Data"]
        LOG["Logs"]
        CACHE["Cache"]
    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

Path Reference:

Component	Path
CLI	/usr/sbin/nftban
Core	/usr/lib/nftban/core/
Lib	/usr/lib/nftban/lib/
Commands	/usr/lib/nftban/cli/
Configuration	/etc/nftban/
State	/var/lib/nftban/
Logs	/var/log/nftban/
Cache	/var/cache/nftban/

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["Main Config"] --> B["Local Overrides"]
        B --> C["Environment Variables"]
        C --> D["Command Line Flags"]
    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.15.0 source code analysis.