webyhomelab/niftywall repository overview

English 🇬🇧⁠ | Українська 🇺🇦⁠\n\n---\n Making Linux Firewalls Transparent, Smart, and Beautiful.

NiftyWall is a professional web dashboard for managing the nftables firewall. In the v3.0.0 update, the project underwent a full audit to achieve Enterprise-grade stability and security. This edition (main) is optimized for rapid deployment in an isolated Docker environment.

⁠📸 Screenshots

⁠❄️ Panic Mode & SAFE Mode

• 🛡️ SAFE Mode (Emergency Lockdown): Your digital "emergency brake" for the server. The SAFE Mode button activates a lockdown state:
  1. Instant Snapshot: Automatically creates a backup of all current firewall rules.
  2. Sterilization: Flushes the niftywall table completely — all unauthorized active connections are dropped.
  3. Whitelisting: Applies a minimal configuration allowing traffic only for critical services: SSH (22, 54322), NiftyWall (8080), and trusted interfaces (Tailscale, Loopback).
  4. Isolation: All public services (HTTP, DB, etc.) become unreachable until you exit the mode.
• ❄️ Panic Mode (Process Freezing): Intelligent resource monitoring. If the system detects abnormal CPU or RAM usage, you can freeze (SIGSTOP) malicious processes with a single click. Frozen processes are automatically pinned to the top of the monitor, releasing resources without a full kill, preserving their state for analysis.

⁠🧩 System Architecture

graph TD
    User((Administrator)) -->|HTTPS / PWA| UI[Web Dashboard]

    subgraph "Docker Container (Host Network)"
        subgraph "NiftyWall Core"
            UI -->|REST API / JWT| API[FastAPI Backend]
            API -->|Pydantic| VAL{Input Validator}
            VAL -->|Subprocess / JSON| NFT[nftables Engine]
            VAL -->|Socket / Logs| F2B[Fail2Ban Parser]
            VAL -->|Metrics| SYS[psutil System Monitor]
            API -->|Persistence| DB[(SQLite Database)]
            API -->|Isolated Backup| TM[Time Machine]
        end
    end

    subgraph "Host OS"
        F2B -.->|Volume Mount| HostF2B[fail2ban sockets & logs]
        subgraph "Linux Kernel"
            NFT -->|Netlink| Netfilter[Kernel Hooks]
            Netfilter -->|Packet Counters| NFT
        end
    end

    F2B -.->|GeoIP| WHO[Whois API]

⁠🚀 What's New in "Hardened"

• 🔐 SQLite Backend: All states migrated to a reliable SQLite database. Resolved Race Conditions.
• 🛡️ Strict Input Validation: Rigorous input validation via Pydantic. Full protection against NFT injections.
• 🕰️ Isolated Time Machine: Backup and Restore work exclusively with the niftywall table, without affecting Docker or VPN rules.
• 🔄 Smart DNAT + SNAT: Automatic addition of Masquerade rules to eliminate asymmetric routing issues.
• 🕵️ Resilient Fail2Ban: New parsing logic capable of querying status directly via fail2ban-client.

⁠🛠️ Installation (Docker Edition)

This method ensures full code isolation from the host system while utilizing necessary Kernel Hooks.

⁠1. Prerequisites

• Docker Engine 24.0+ and Docker Compose v2.
• nftables present on the host system (for kernel module loading).

⁠2. Deployment via Docker Compose

Create docker-compose.yml:

services:
  niftywall:
    image: webyhomelab/niftywall:latest
    container_name: niftywall
    privileged: true # Required for nftables management
    network_mode: host # Required for direct interface access
    restart: always
    environment:
      - SECRET_KEY=${SECRET_KEY} # openssl rand -hex 32
      - PANIC_ALLOWED_PORTS=22,80,443,54322
      - TZ=Europe/Kyiv
    volumes:
      - /var/log/fail2ban.log:/var/log/fail2ban.log:ro
      - /var/run/fail2ban:/var/run/fail2ban
      - /opt/niftywall/data:/app/data
      - /opt/niftywall/snapshots:/app/snapshots

⁠3. Run

docker compose up -d

⁠📋 Detailed System Requirements and Environments

NiftyWall is built on the principle of absolute autonomy. By utilizing an isolated inet niftywall table with high-priority chains, the system ensures stability in complex network environments.

⁠🟢 1. Ideal Environment (Native Bare Metal / Cloud VPS)

Servers without additional third-party firewall layers.

• How it works: NiftyWall acts as the sole master of network traffic. It initializes input and forward chains with type filter and priority -100, allowing packet processing at the very beginning of the kernel network stack.
• Features: Highest rule processing speed, 100% predictability, and zero overhead.

⁠🟡 2. Mixed Environment (Servers with Docker / LXC / KVM)

Servers actively utilizing containerization.

• Compatibility: Full (v2.0+). NiftyWall no longer conflicts with Docker.
• "Shield-First" Concept: Thanks to priority -100, NiftyWall rules trigger BEFORE Docker's rules (which typically have priority 0). This allows you to block threats at the kernel level before they ever reach the virtual container bridges.
• Isolation: Operating in its own namespace (table inet niftywall) prevents accidental deletion of Docker rules during configuration resets.

⁠🔴 3. Hostile Environment (UFW or Firewalld active)

Servers where another high-level manager is already active.

• Compatibility: Not Recommended.
• The "Shadowing" Problem: nftables allows multiple tables to work in parallel. A packet must be allowed in both systems simultaneously. If NiftyWall allows traffic but a forgotten UFW blocks it, you will face hard-to-diagnose issues.
• Solution: It is recommended to execute systemctl disable --now ufw or firewalld before using NiftyWall. If you specifically need a GUI for them, use: UFW-GUI⁠ or Firewalld-GUI⁠.

Built in Ukraine under air raid sirens & blackouts ⚡
© 2026 Weby Homelab

Making Linux Firewalls Transparent, Smart, and Beautiful.

NiftyWall — це професійний веб-дашборд для керування фаєрволом nftables. У версії v3.0.0 проект пройшов повний аудит для досягнення Enterprise-стабільності та безпеки. Ця редакція (main) оптимізована для швидкого розгортання в ізольованому середовищі Docker.

⁠📸 Інтерфейс

⁠❄️ Panic Mode & SAFE Mode

• 🛡️ SAFE Mode (Екстрене блокування): Ваш цифровий "стоп-кран" для сервера. Кнопка SAFE Mode активує режим екстреного захисту:
  1. Миттєвий Snapshot: Автоматично створюється знімок усіх правил фаєрвола.
  2. Стерилізація: Повне очищення (Flush) таблиці niftywall — усі неавторизовані з'єднання розриваються.
  3. Білий список: Застосовується мінімальна конфігурація, що дозволяє трафік лише для критичних сервісів: SSH (22), NiftyWall (8080) та довірених інтерфейсів (Tailscale, Loopback).
  4. Ізоляція: Усі публічні сервіси (HTTP, DB тощо) стають недоступними до моменту виходу з режиму.
• ❄️ Panic Mode (Заморожування процесів): Інтелектуальний моніторинг ресурсів. Якщо система виявляє аномальне споживання CPU або RAM, ви можете заморозити (SIGSTOP) шкідливі процеси одним кліком. Заморожені процеси автоматично закріплюються вгорі списку, звільняючи ресурси без повної зупинки (kill), що дозволяє зберегти їх стан для аналізу.

⁠🧩 Архітектура системи

graph TD
    User((Адміністратор)) -->|HTTPS / PWA| UI[Web Dashboard]

    subgraph "Docker Container (Host Network)"
        subgraph "NiftyWall Core"
            UI -->|REST API / JWT| API[FastAPI Backend]
            API -->|Pydantic| VAL{Input Validator}
            VAL -->|Subprocess / JSON| NFT[nftables Engine]
            VAL -->|Socket / Logs| F2B[Fail2Ban Parser]
            VAL -->|Metrics| SYS[psutil System Monitor]
            API -->|Persistence| DB[(SQLite Database)]
            API -->|Isolated Backup| TM[Time Machine]
        end
    end

    subgraph "Host OS"
        F2B -.->|Volume Mount| HostF2B[fail2ban sockets & logs]
        subgraph "Linux Kernel"
            NFT -->|Netlink| Netfilter[Kernel Hooks]
            Netfilter -->|Packet Counters| NFT
        end
    end

    F2B -.->|GeoIP| WHO[Whois API]

⁠🚀 Що нового у версії "Hardened"

• 🔐 SQLite Backend: Усі стани (користувачі, логи, історія) перенесені в надійну БД SQLite. Вирішено проблему Race Conditions.
• 🛡️ Strict Input Validation: Сувора валідація всіх вхідних даних через Pydantic. Повний захист від NFT-ін'єкцій.
• 🕰️ Isolated Time Machine: Бекапи працюють виключно з таблицею niftywall, не зачіпаючи правила Docker чи VPN.
• 🔄 Smart DNAT + SNAT: Автоматичне додавання правил маскарадінгу для усунення проблем асиметричної маршрутизації.
• 🕵️ Resilient Fail2Ban: Нова логіка парсингу, що працює напряму через fail2ban-client.

⁠🛠️ Встановлення (Docker Edition)

Цей метод забезпечує повну ізоляцію коду від хост-системи, використовуючи лише необхідні Kernel Hooks.

⁠1. Попередні вимоги

• Docker Engine 24.0+ та Docker Compose v2.
• Наявність nftables у хост-системі (для завантаження модулів ядра).

⁠2. Розгортання через Docker Compose

Створіть docker-compose.yml:

services:
  niftywall:
    image: webyhomelab/niftywall:latest
    container_name: niftywall
    privileged: true # Необхідно для керування nftables
    network_mode: host # Необхідно для прямого доступу до інтерфейсів
    restart: always
    environment:
      - SECRET_KEY=${SECRET_KEY} # openssl rand -hex 32
      - PANIC_ALLOWED_PORTS=22,80,443
      - TZ=Europe/Kyiv
    volumes:
      - /var/log/fail2ban.log:/var/log/fail2ban.log:ro
      - /var/run/fail2ban:/var/run/fail2ban
      - /opt/niftywall/data:/app/data
      - /opt/niftywall/snapshots:/app/snapshots

⁠3. Запуск

docker compose up -d

⁠📋 Детальні Системні Вимоги та Сумісність (Environments)

Проект NiftyWall побудовано за принципом абсолютної автономії. Завдяки використанню ізольованої таблиці inet niftywall з найвищим пріоритетом ланцюгів, система гарантує стабільність у складних мережевих середовищах.

⁠🟢 1. Ідеальне середовище (Native Bare Metal / Cloud VPS)

Сервери без додаткових прошарків сторонніх фаєрволів.

• Як працює: NiftyWall є єдиним хазяїном мережевого трафіку. Він ініціалізує ланцюги input та forward з типом filter та пріоритетом -100, що дозволяє обробляти пакети на самому початку мережевого стеку ядра.
• Особливості: Найвища швидкість обробки правил, 100% передбачуваність та нульовий оверхед.

⁠🟡 2. Змішане середовище (Сервери з Docker / LXC / KVM)

Сервери, де активно використовується контейнеризація.

• Сумісність: Повна (v2.0+). NiftyWall більше не конфліктує з Docker.
• Концепція "Shield-First": Завдяки пріоритету -100, правила NiftyWall спрацьовують РАНІШЕ, ніж правила Docker (які зазвичай мають пріоритет 0). Це дозволяє вам заблокувати загрозу на рівні ядра до того, як вона взагалі потрапить у віртуальні мости контейнерів.
• Ізоляція: Робота у власному просторі імен (table inet niftywall) виключає випадкове видалення правил Docker при скиданні конфігурації.

⁠🔴 3. Вороже середовище (UFW або Firewalld)

Сервери, де вже активний інший високорівневий менеджер.

• Сумісність: Не рекомендовано.
• Проблема "Затінення": nftables дозволяє паралельну роботу кількох таблиць. Пакет має бути дозволений в обох системах одночасно. Якщо NiftyWall дозволяє трафік, а забутий UFW його блокує — ви отримаєте важку в діагностиці проблему.
• Рішення: Рекомендується виконати systemctl disable --now ufw або firewalld перед використанням NiftyWall. Якщо вам потрібен GUI саме для них, використовуйте: UFW-GUI⁠ або Firewalld-GUI⁠.

Built in Ukraine under air raid sirens & blackouts ⚡
© 2026 Weby Homelab

Made with ❤️ in Kyiv ✦ 2026 Weby Homelab ✦